From c04a194f8cb05a64b0339a3bffb50f8ea632a554 Mon Sep 17 00:00:00 2001 From: nerda-codes Date: Thu, 23 Oct 2025 14:30:56 +0200 Subject: [PATCH 1/3] docs(add): complete ref content page --- pages/key-manager/concepts.mdx | 57 +++--------- .../cryptographic-details-key-manager.mdx | 87 +++++++++++++++---- 2 files changed, 80 insertions(+), 64 deletions(-) diff --git a/pages/key-manager/concepts.mdx b/pages/key-manager/concepts.mdx index 3b07e8d9c1..5986badce5 100644 --- a/pages/key-manager/concepts.mdx +++ b/pages/key-manager/concepts.mdx @@ -3,22 +3,14 @@ title: Key Manager - Concepts description: Explore essential cryptographic concepts, including symmetric and asymmetric encryption, data encryption keys (DEKs), key encryption keys (KEKs), and Scaleway Key Manager's robust features for secure key management and encryption operations. tags: key-manager key encryption-key dates: - validation: 2025-09-03 + validation: 2025-10-23 --- ## Asymmetric encryption Asymmetric encryption is a fundamental type of cryptographic method used to secure data with a pair of keys: a **public key** and a **private key**. -The public key is used for encryption and can be shared openly, while the private key is used for decryption and must be kept secret. This design eliminates the need to share a single key securely, which is a challenge in symmetric encryption. - -Asymmetric encryption is particularly well-suited for secure communication and authentication, such as encrypting emails or verifying digital signatures. However, it is slower than symmetric encryption. Algorithms like RSA and ECC are common examples of asymmetric encryption. - -As of now, Key Manager supports the following asymmetric encryption algorithms: - -- RSA-OAEP-2048-SHA256: RSA encryption with 2048-bit key and OAEP padding using SHA-256. -- RSA-OAEP-3072-SHA256: RSA encryption with 3072-bit key and OAEP padding using SHA-256. (recommended) -- RSA-OAEP-4096-SHA256: RSA encryption with 4096-bit key and OAEP padding using SHA-256. +Refer to the [Understanding Key Manager cryptography](/key-manager/reference-content/cryptographic-details-key-manager/#asymmetric-encryption) documentation page for more information. ## Ciphertext @@ -61,7 +53,7 @@ The only way to decrypt an encrypted payload is by using the `Decrypt` [endpoint ## Encryption -A cryptographic operation used to encrypt data using the latest version of the Key Manager key. The [encryption algorithm](#encryption-algorithm) used is the one defined when setting the [key usage](#key-usage). +Encryption is a cryptographic operation used to encrypt data using the latest version of the Key Manager key. The [encryption algorithm](#encryption-algorithm) used is the one defined when setting the [key usage](#key-usage). The input data is arbitrary, but this endpoint should only be used to encrypt **data encryption keys**, not actual [payloads](#payload). @@ -69,43 +61,21 @@ The input data is arbitrary, but this endpoint should only be used to encrypt ** ## Encryption algorithm -An encryption algorithm is the specific procedure used to perform encryption and decryption. - -It defines the exact steps to transform plaintext into ciphertext and vice versa using a key. - -As of now, Key Manager supports the following **symmetric** encryption algorithm: - -- AES (Advanced Encryption Standard): A widely used symmetric encryption algorithm. - -It also supports the following **asymmetric** encryption algorithms: +An encryption algorithm is the specific procedure used to perform encryption and decryption. It defines the exact steps to transform plaintext into ciphertext and vice versa using a key. -- RSA-OAEP-2048-SHA256: RSA encryption with 2048-bit key and OAEP padding using SHA-256. -- RSA-OAEP-3072-SHA256: RSA encryption with 3072-bit key and OAEP padding using SHA-256. (recommended) -- RSA-OAEP-4096-SHA256: RSA encryption with 4096-bit key and OAEP padding using SHA-256. - -Refer to the [Understanding Key Manager cryptography](/key-manager/reference-content/cryptographic-details-key-manager/) documentation page for more information. +Refer to the [Understanding Key Manager cryptography](/key-manager/reference-content/cryptographic-details-key-manager/#encryption-algorithm) documentation page for more information. ## Encryption method An encryption method is a broader approach used to convert readable data ([plaintext](#plaintext)) into an unreadable format ([ciphertext](#ciphertext)) which may involve one or more [encryption algorithms](#encryption-algorithm). -There are three types of encryption methods: - -- [Symmetric encryption](#symmetric-encryption) -- [Asymmetric encryption](#asymmetric-encryption) -- Hybrid encryption: An encryption method that combines both symmetric and asymmetric methods - -Key Manager supports symmetric and asymmetric encryption. Refer to the [Understanding Key Manager cryptography](/key-manager/reference-content/cryptographic-details-key-manager/) documentation page for more information. +Refer to the [Understanding Key Manager cryptography](/key-manager/reference-content/cryptographic-details-key-manager/#encryption-method) documentation page for more information. ## Encryption scheme An encryption scheme is a structured approach to encryption that specifies the encryption algorithm, key size, and mode of operation for block ciphers. -For example, in the `AES-256-GCM` encryption scheme: - -- `AES` refers to the Advanced Encryption Standard (AES) encryption algorithm -- `256` refers to the key length in bits -- `GCM` or Galois/Counter Mode, is the mode of operation for block ciphers. GCM encrypts your plaintext data using AES, and authenticates it using a unique "tag". This means that if anyone tampers with your data, you will know because the tag will not match anymore. +Refer to the [Understanding Key Manager cryptography](/key-manager/reference-content/cryptographic-details-key-manager/#encryption-scheme) documentation page for more information. ## Key encryption key (KEK) @@ -167,16 +137,7 @@ Signature is a cryptographic technique used to ensure the authenticity and integ Signatures are widely used in scenarios like document signing, secure communication, and identity verification. They offer assurance that the data originated from a trusted source and has not been tampered with. -As of now, Key Manager supports the following asymmetric signing algorithms: - -- EC-P256-SHA256: ECDSA signing with the P-256 curve and SHA-256. (recommended) -- EC-P384-SHA256: ECDSA signing with the P-384 curve and SHA-384. -- RSA-PSS-2048-SHA256: RSA-PSS signing with 2048-bit key and SHA-256. -- RSA-PSS-3072-SHA256: RSA-PSS signing with 3072-bit key and SHA-256. -- RSA-PSS-4096-SHA256: RSA-PSS signing with 4096-bit key and SHA-256. -- RSA-PKCS1-2048-SHA256: RSA PKCS#1 v1.5 signing with 2048-bit key and SHA-256. -- RSA-PKCS1-3072-SHA256: RSA PKCS#1 v1.5 signing with 3072-bit key and SHA-256. -- RSA-PKCS1-4096-SHA256: RSA PKCS#1 v1.5 signing with 4096-bit key and SHA-256. +Refer to the [Understanding Key Manager cryptography](/key-manager/reference-content/cryptographic-details-key-manager/#encryption-scheme) documentation page for more information on supported signing algorithms. ## Signature verification @@ -198,3 +159,5 @@ Symmetric encryption is a fundamental type of cryptographic method where the sam Because symmetric encryption relies on a single key, it is generally fast and ideal for encrypting large volumes of data. However, its security depends entirely on keeping the key confidential. Symmetric encryption algorithms like AES are widely used in scenarios where speed and efficiency are critical. As of now, Key Manager only supports the `AES_256_GCM` symmetric encryption algorithm. + +Refer to the [Understanding Key Manager cryptography](/key-manager/reference-content/cryptographic-details-key-manager/#symmetric-encryption) documentation page for more information. \ No newline at end of file diff --git a/pages/key-manager/reference-content/cryptographic-details-key-manager.mdx b/pages/key-manager/reference-content/cryptographic-details-key-manager.mdx index 91a76810e8..ca36c89823 100644 --- a/pages/key-manager/reference-content/cryptographic-details-key-manager.mdx +++ b/pages/key-manager/reference-content/cryptographic-details-key-manager.mdx @@ -3,7 +3,7 @@ title: Understanding Key Manager cryptography description: This page describes the cryptographic mechanisms used by Scaleway Key Manager, in accordance with ANSSI-PA-079 recommendations. tags: key-manager security dates: - validation: 2025-09-15 + validation: 2025-10-23 posted: 2025-05-23 --- @@ -11,6 +11,59 @@ dates: This page provides information on the core cryptographic mechanisms used by Key Manager. It explains how cryptographic keys are generated, managed, and used to encrypt data. Key Manager uses these mechanisms in compliance with the cryptographic guidelines issued by [France's national cybersecurity agency](https://cyber.gouv.fr/), as outlined in the ANSSI-PA-079 recommendations, to ensure the confidentiality and integrity of customer data. +### Encryption algorithm + +An encryption algorithm is the specific procedure used to perform encryption and decryption. It defines the exact steps to transform plaintext into ciphertext and vice versa using a key. + +As of now, Key Manager supports the following **symmetric** encryption algorithm: + +- AES (Advanced Encryption Standard): A widely used symmetric encryption algorithm. + +It also supports the following **asymmetric** encryption algorithms: + +- RSA-OAEP-2048-SHA256: RSA encryption with 2048-bit key and OAEP padding using SHA-256. +- RSA-OAEP-3072-SHA256: RSA encryption with 3072-bit key and OAEP padding using SHA-256. (recommended) +- RSA-OAEP-4096-SHA256: RSA encryption with 4096-bit key and OAEP padding using SHA-256. + +### Encryption method + +An encryption method is a broader approach used to convert readable data ([plaintext](/key-manager/concepts/#plaintext)) into an unreadable format ([ciphertext](/key-manager/concepts/#ciphertext)) which may involve one or more [encryption algorithms](#encryption-algorithm). + +There are three types of encryption methods: + +- Symmetric encryption +- Asymmetric encryption +- Hybrid encryption: An encryption method that combines both symmetric and asymmetric methods + +Key Manager supports symmetric and asymmetric encryption. + +### Encryption scheme + +An encryption scheme is a structured approach to encryption that specifies the encryption algorithm, key size, and mode of operation for block ciphers. + +For example, in the `AES-256-GCM` encryption scheme: + +- `AES` refers to the Advanced Encryption Standard (AES) encryption algorithm +- `256` refers to the key length in bits +- `GCM` or Galois/Counter Mode, is the mode of operation for block ciphers. GCM encrypts your plaintext data using AES, and authenticates it using a unique "tag". This means that if anyone tampers with your data, you will know because the tag will not match anymore. + +### Signature + +Signature is a cryptographic technique used to ensure the authenticity and integrity of data. In this process, a digest (hash) of the message is created and then signed using a private key. This signature can later be verified by anyone with access to the corresponding public key. + +Signatures are widely used in scenarios like document signing, secure communication, and identity verification. They offer assurance that the data originated from a trusted source and has not been tampered with. + +As of now, Key Manager supports the following asymmetric signing algorithms: + +- EC-P256-SHA256: ECDSA signing with the P-256 curve and SHA-256. (recommended) +- EC-P384-SHA256: ECDSA signing with the P-384 curve and SHA-384. +- RSA-PSS-2048-SHA256: RSA-PSS signing with 2048-bit key and SHA-256. +- RSA-PSS-3072-SHA256: RSA-PSS signing with 3072-bit key and SHA-256. +- RSA-PSS-4096-SHA256: RSA-PSS signing with 4096-bit key and SHA-256. +- RSA-PKCS1-2048-SHA256: RSA PKCS#1 v1.5 signing with 2048-bit key and SHA-256. +- RSA-PKCS1-3072-SHA256: RSA PKCS#1 v1.5 signing with 3072-bit key and SHA-256. +- RSA-PKCS1-4096-SHA256: RSA PKCS#1 v1.5 signing with 4096-bit key and SHA-256. + ### Random number generation #### Key encryption key (KEK) generation @@ -37,6 +90,20 @@ Scaleway Key Manager supports Bring Your Own Key (BYOK), allowing customers to i To protect against direct reuse, imported key material is not used directly. Instead, it is processed using the HKDF algorithm (HMAC-based Key Derivation Function) with SHA-256 as the hash algorithm, incorporating secure random bytes added as a salt value. +### Asymmetric encryption + +Asymmetric encryption is a fundamental type of cryptographic method used to secure data with a pair of keys: a **public key** and a **private key**. + +The public key is used for encryption and can be shared openly, while the private key is used for decryption and must be kept secret. This design eliminates the need to share a single key securely, which is a challenge in symmetric encryption. + +Asymmetric encryption is particularly well-suited for secure communication and authentication, such as encrypting emails or verifying digital signatures. However, it is slower than symmetric encryption. Algorithms like RSA and ECC are common examples of asymmetric encryption. + +As of now, Key Manager supports the following asymmetric encryption algorithms: + +- RSA-OAEP-2048-SHA256: RSA encryption with 2048-bit key and OAEP padding using SHA-256. +- RSA-OAEP-3072-SHA256: RSA encryption with 3072-bit key and OAEP padding using SHA-256. (recommended) +- RSA-OAEP-4096-SHA256: RSA encryption with 4096-bit key and OAEP padding using SHA-256. + ### Symmetric encryption Scaleway Key Manager uses **AES-256-GCM** (AES with a 256-bit key in Galois/Counter Mode) with authenticated associated data (AEAD) for encrypting and decrypting user payloads. @@ -48,24 +115,10 @@ To reduce the risk of key overuse, plaintext payloads are limited to a maximum s - While Key Manager internally uses AES-256-GCM, this does not restrict users to the same algorithm for their data encryption keys (DEKs). + While Key Manager internally uses AES-256-GCM, this does not restrict users to the same algorithm for their data encryption keys (DEKs). We recommend using cryptographic libraries like Tink, which handle DEK management with robust and reviewed algorithms. Scaleway provides Tink integrations for Go and Python, which is the preferred integration method. - [Tink Python integration](https://github.com/scaleway/tink-py-scwkms) - [Tink Go integration](https://github.com/scaleway/tink-go-scwkms) - - -### Asymmetric encryption - -Asymmetric encryption is a fundamental type of cryptographic method used to secure data with a pair of keys: a **public key** and a **private key**. - -The public key is used for encryption and can be shared openly, while the private key is used for decryption and must be kept secret. This design eliminates the need to share a single key securely, which is a challenge in symmetric encryption. - -Asymmetric encryption is particularly well-suited for secure communication and authentication, such as encrypting emails or verifying digital signatures. However, it is slower than symmetric encryption. Algorithms like RSA and ECC are common examples of asymmetric encryption. - -As of now, Key Manager supports the following asymmetric encryption algorithms: - -- RSA-OAEP-2048-SHA256: RSA encryption with 2048-bit key and OAEP padding using SHA-256. -- RSA-OAEP-3072-SHA256: RSA encryption with 3072-bit key and OAEP padding using SHA-256. (recommended) -- RSA-OAEP-4096-SHA256: RSA encryption with 4096-bit key and OAEP padding using SHA-256. \ No newline at end of file + \ No newline at end of file From 3a0d12b32a89c8890c234421d3809ac76b4f9943 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?N=C3=A9da?= <87707325+nerda-codes@users.noreply.github.com> Date: Thu, 23 Oct 2025 16:07:06 +0200 Subject: [PATCH 2/3] Update pages/key-manager/reference-content/cryptographic-details-key-manager.mdx Co-authored-by: Jessica <113192637+jcirinosclwy@users.noreply.github.com> --- .../reference-content/cryptographic-details-key-manager.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/key-manager/reference-content/cryptographic-details-key-manager.mdx b/pages/key-manager/reference-content/cryptographic-details-key-manager.mdx index ca36c89823..47a73b73b7 100644 --- a/pages/key-manager/reference-content/cryptographic-details-key-manager.mdx +++ b/pages/key-manager/reference-content/cryptographic-details-key-manager.mdx @@ -22,7 +22,7 @@ As of now, Key Manager supports the following **symmetric** encryption algorithm It also supports the following **asymmetric** encryption algorithms: - RSA-OAEP-2048-SHA256: RSA encryption with 2048-bit key and OAEP padding using SHA-256. -- RSA-OAEP-3072-SHA256: RSA encryption with 3072-bit key and OAEP padding using SHA-256. (recommended) +- RSA-OAEP-3072-SHA256: RSA encryption with 3072-bit key and OAEP padding using SHA-256. (Recommended) - RSA-OAEP-4096-SHA256: RSA encryption with 4096-bit key and OAEP padding using SHA-256. ### Encryption method From 49d08b82778d33ddeede1cbbe651eba7bd6be615 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?N=C3=A9da?= <87707325+nerda-codes@users.noreply.github.com> Date: Thu, 23 Oct 2025 16:07:29 +0200 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Jessica <113192637+jcirinosclwy@users.noreply.github.com> --- .../reference-content/cryptographic-details-key-manager.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/key-manager/reference-content/cryptographic-details-key-manager.mdx b/pages/key-manager/reference-content/cryptographic-details-key-manager.mdx index 47a73b73b7..da76058d82 100644 --- a/pages/key-manager/reference-content/cryptographic-details-key-manager.mdx +++ b/pages/key-manager/reference-content/cryptographic-details-key-manager.mdx @@ -55,7 +55,7 @@ Signatures are widely used in scenarios like document signing, secure communicat As of now, Key Manager supports the following asymmetric signing algorithms: -- EC-P256-SHA256: ECDSA signing with the P-256 curve and SHA-256. (recommended) +- EC-P256-SHA256: ECDSA signing with the P-256 curve and SHA-256. (Recommended) - EC-P384-SHA256: ECDSA signing with the P-384 curve and SHA-384. - RSA-PSS-2048-SHA256: RSA-PSS signing with 2048-bit key and SHA-256. - RSA-PSS-3072-SHA256: RSA-PSS signing with 3072-bit key and SHA-256. @@ -101,7 +101,7 @@ Asymmetric encryption is particularly well-suited for secure communication and a As of now, Key Manager supports the following asymmetric encryption algorithms: - RSA-OAEP-2048-SHA256: RSA encryption with 2048-bit key and OAEP padding using SHA-256. -- RSA-OAEP-3072-SHA256: RSA encryption with 3072-bit key and OAEP padding using SHA-256. (recommended) +- RSA-OAEP-3072-SHA256: RSA encryption with 3072-bit key and OAEP padding using SHA-256. (Recommended) - RSA-OAEP-4096-SHA256: RSA encryption with 4096-bit key and OAEP padding using SHA-256. ### Symmetric encryption