From a75b4f0b3902d79826592a526bfd9d9b52c09878 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A9lanie=20Marques?= Date: Mon, 12 May 2025 16:06:16 +0200 Subject: [PATCH 1/2] feat(key_manager): add asymmetric concepts --- pages/key-manager/concepts.mdx | 53 ++++++++++++++++--- pages/key-manager/faq.mdx | 9 +++- .../understanding-key-manager.mdx | 17 ++++-- 3 files changed, 66 insertions(+), 13 deletions(-) diff --git a/pages/key-manager/concepts.mdx b/pages/key-manager/concepts.mdx index 850bc57d4e..31b83a851a 100644 --- a/pages/key-manager/concepts.mdx +++ b/pages/key-manager/concepts.mdx @@ -18,6 +18,12 @@ The public key is used for encryption and can be shared openly, while the privat 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 currently 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. + ## Ciphertext Ciphertext refers to data that has been encrypted using a cryptographic algorithm and a key. @@ -31,11 +37,13 @@ Ciphertext can be encrypted on the client side as long as the encryption key use A cryptographic operation is any action performed using cryptography to secure data, ensure privacy, or authenticate information. -Key Manager supports the three following cryptographic operations: +Key Manager supports the five following cryptographic operations: - [Encryption](#encryption) - [Decryption](#decryption) - [Data encryption key](#data-encryption-key-dek) generation +- [Signature](#signature) +- [Signature verification](#signature-verification) These operations are designed to protect data from unauthorized access, ensure its integrity, and verify the identities of users or systems. @@ -57,7 +65,7 @@ The only way to decrypt an encrypted payload is by using the `Decrypt` [endpoint 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). -Only keys with a usage set to `symmetric_encryption` are supported by this method. The input data is arbitrary, but this endpoint should only be used to encrypt **data encryption keys**, not actual [payloads](#payload). +The input data is arbitrary, but this endpoint should only be used to encrypt **data encryption keys**, not actual [payloads](#payload). [Find out how to encrypt and decrypt payloads using The Scaleway Tink provider](/key-manager/api-cli/manage-keys-with-tink) @@ -67,10 +75,16 @@ An encryption algorithm is the specific procedure used to perform encryption and It defines the exact steps to transform plaintext into ciphertext and vice versa using a key. -As of now, Key Manager supports the following encryption algorithm: +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](#plaintext)) into an unreadable format ([ciphertext](#ciphertext)) which may involve one or more [encryption algorithms](#encryption-algorithm). @@ -78,10 +92,10 @@ An encryption method is a broader approach used to convert readable data ([plain There are three types of encryption methods: - [Symmetric encryption](#symmetric-encryption) -- [Asymmetric encrytpion](#asymmetric-encryption) +- [Asymmetric encryption](#asymmetric-encryption) - Hybrid encryption: An encryption method that combines both symmetric and asymmetric methods -Key Manager only supports symmetric encryption. +Key Manager supports symmetric and asymmetric encryption. ## Encryption scheme @@ -116,14 +130,16 @@ When using [symmetric encryption](#symmetric-encryption), it is generally recomm After rotating your Key Manager keys, all cryptographic operations will use the new rotated keys. All data encrypted with former key versions will remain decipherable with the former key. +Key rotation is only available for symmetric keys. + ## Key usage The key usage specifies the **algorithm** used to create subsequent key versions, and the **scope of cryptographic operations** supported by your key encryption key. -You must define a key usage upon key creation. As of now, Key Manager **only supports symmetric encryption**. +You must define a key usage upon key creation. Key Manager supports symmetric encryption, asymmetric encryption and asymmetric signing. ## Key version -A key version is a a specific iteration of your key encryption key. Each version of your key represents a distinct state or version that may be [rotated](#key-rotation) or replaced over time. +A key version is a specific iteration of your key encryption key. Each version of your key represents a distinct state or version that may be [rotated](#key-rotation) or replaced over time. Key versions allow you to manage and track changes to your data encryption keys. When using key versions, all cryptographic operations will rely on the current key version. @@ -145,6 +161,29 @@ A region refers to the **geographical location** in which your key will be creat A root encryption key (REK) is another type of key that has the single purpose of encrypting and decrypting KEKs in order to store them in hard storage. Scaleway's Key Manager has one REK per region, which is securely stored in our facilities. +## 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 for 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. + +## Signature verification + +Signature verification is the process of confirming the authenticity and integrity of a digital signature. +It involves using the public key corresponding to the private key that was used to create the signature to verify that the data has not been altered and that it comes from the claimed sender. +This process is crucial for ensuring secure and reliable communication. + ## Symmetric encryption Symmetric encryption is a fundamental type of cryptographic method where the same key is used to both encrypt and decrypt data. This means that the sender and receiver must have access to the same secret key, which they use to secure their communication. diff --git a/pages/key-manager/faq.mdx b/pages/key-manager/faq.mdx index bf6baea115..ebf2eddd85 100644 --- a/pages/key-manager/faq.mdx +++ b/pages/key-manager/faq.mdx @@ -29,11 +29,18 @@ Key Manager supports the three following cryptographic operations: - [Encryption](/key-manager/concepts/#encryption) - [Decryption](/key-manager/concepts/#decryption) - [Data encryption key](/key-manager/concepts/#data-encryption-key-dek) generation +- [Signature](/key-manager/concepts/#signature) +- [Signature verification](/key-manager/concepts/#signature-verification) + ## Which algorithms and key usage does Key Manager support? -Keys with a [key usage](/key-manager/concepts/#key-usage) set to `symmetric_encryption` are **used to encrypt and decrypt data**. +Key Manager supports multiple [key usages](/key-manager/concepts/#key-usage) to suit different cryptographic operations: + +- Keys with a usage set to `symmetric_encryption` are used to encrypt and decrypt data using symmetric algorithms. +- Keys with a usage set to `asymmetric_encryption` are used for encrypting and decrypting data with asymmetric algorithms, typically involving a public-private key pair. +- Keys with a usage set to `asymmetric_signing` are used for generating and verifying digital signatures, ensuring data authenticity and integrity. Refer to our [dedicated documentation](/key-manager/reference-content/understanding-key-manager/) to find out more about Key Manager. diff --git a/pages/key-manager/reference-content/understanding-key-manager.mdx b/pages/key-manager/reference-content/understanding-key-manager.mdx index 5770349ce3..055b591a78 100644 --- a/pages/key-manager/reference-content/understanding-key-manager.mdx +++ b/pages/key-manager/reference-content/understanding-key-manager.mdx @@ -51,6 +51,8 @@ Key Manager supports the three following cryptographic operations: - [Encryption](/key-manager/concepts/#encryption) - [Decryption](/key-manager/concepts/#decryption) - [Data encryption key](/key-manager/concepts/#data-encryption-key-dek) generation +- [Signature](/key-manager/concepts/#signature) +- [Signature verification](/key-manager/concepts/#signature-verification) ## Management methods you can use with Key Manager @@ -74,13 +76,15 @@ Upon key creation, Key Manager automatically creates a first key version. ## Key usage and algorithms -The key usage specifies the [encryption algorithm](/key-manager/concepts/#encryption-algorithm) used to create subsequent key versions, and the **scope of cryptographic operations** supported by the key. +The key usage specifies the [encryption algorithm](/key-manager/concepts/#encryption-algorithm) or [signing algorithm](/key-manager/concepts/#signature) used to create subsequent key versions, and defines the **scope of cryptographic operations** supported by the key. -Keys with a key usage set to `symmetric_encryption` are **used to encrypt and decrypt data**. +- Keys with a key usage set to `symmetric_encryption` are used to encrypt and decrypt data using symmetric algorithms. +- Keys with a key usage set to `asymmetric_encryption` are used to encrypt and decrypt data using asymmetric algorithms. +- Keys with a key usage set to `asymmetric_signing` are used to generate and verify digital signatures. -The following parameters, in compliance with the [recommendations of the French Cybersecurity Agency (ANSSI)](https://cyber.gouv.fr/publications/mecanismes-cryptographiques), are used when creating and using a key with the `AES-256 GCM` [encryption scheme](/key-manager/concepts/#encryption-scheme). +The following parameters, in compliance with the [recommendations of the French Cybersecurity Agency (ANSSI)](https://cyber.gouv.fr/publications/mecanismes-cryptographiques), are used when creating and using a key. ### Key derivation algorithm @@ -92,9 +96,12 @@ Key Manager generates a 256-bit key using a cryptographically secure random numb ### Key version length -The key version has a length of 256 bits, ensuring strong cryptographic security. +For symmetric encryption, the key version has a length of 256 bits, ensuring strong cryptographic security. +The key size for asymmetric keys depends on the encryption algorithm used: +- RSA key sizes. Common key sizes are 2048, 3072, or 4096 bits +- EC key sizes. Common key sizes are 256 bits (known as P-256) and 384 bits (known as P-384) ### Block cipher -For encryption, Key Manager uses the Galois/Counter Mode (GCM), which is a mode of operation for block ciphers, with a block size of 128 bits. 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. +For symmetric encryption, Key Manager uses the Galois/Counter Mode (GCM), which is a mode of operation for block ciphers, with a block size of 128 bits. 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. From 80662a4af15773f511f712b66f29e0ba03992c5a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?N=C3=A9da?= <87707325+nerda-codes@users.noreply.github.com> Date: Tue, 13 May 2025 11:16:00 +0200 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Rowena Jones <36301604+RoRoJ@users.noreply.github.com> --- pages/key-manager/concepts.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/key-manager/concepts.mdx b/pages/key-manager/concepts.mdx index 31b83a851a..647f6d3609 100644 --- a/pages/key-manager/concepts.mdx +++ b/pages/key-manager/concepts.mdx @@ -18,7 +18,7 @@ The public key is used for encryption and can be shared openly, while the privat 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 currently supports the following asymmetric encryption algorithms: +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) @@ -167,7 +167,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 for now, Key Manager supports the following asymmetric signing algorithms: +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.