Skip to content

feat(key_manager): add asymmetric concepts #4947

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 46 additions & 7 deletions pages/key-manager/concepts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 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.
Expand All @@ -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.

Expand All @@ -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)

Expand All @@ -67,21 +75,27 @@ 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).

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

Expand Down Expand Up @@ -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.

Expand All @@ -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 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.

## 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.
Expand Down
9 changes: 8 additions & 1 deletion pages/key-manager/faq.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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?

<Macro id="encryption" />

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.
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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.

<Macro id="key-manager-encryption" />

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

Expand All @@ -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.

Loading