Skip to content

Commit fbe799c

Browse files
nerda-codesnerda-codes
committed
docs(key-manager): add
1 parent 10b521c commit fbe799c

File tree

5 files changed

+139
-69
lines changed

5 files changed

+139
-69
lines changed

‎faq/key-manager.mdx‎

Lines changed: 9 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -5,65 +5,35 @@ meta:
55
content:
66
h1: Key Manager
77
dates:
8-
validation: 2024-12-09
8+
validation: 2024-12-11
99
category: identity-and-access-management
10-
productIcon: KeyManagerProductIcon
10+
productIcon: AuditTrailProductIcon
1111
---
1212

1313
## Why should you use Scaleway Key Manager?
1414

1515
Key Manager helps organizations achieve secure key management by handling low-level and error-prone cryptographic details for you.
1616

17-
1817
## What features does Scaleway Key Manager include?
1918

2019
Scaleway Key Manager allows you to create, manage and use cryptographic keys in a centralized and secure service. All your cryptographic operations can be delegated to Key Manager, which in turn ensures the security and availability of your keys.
2120

2221
## Which management methods can I use with Key Manager?
2322

24-
Key Manager allows you to create and manage the complete lifecycle of a key. Below are all the ways you can use Key Manager to manage your data.
25-
26-
### Create a key:
27-
28-
You must specify a **key usage**, which defines the **purpose of the key** (encryption, signing, etc.) and which **cryptographic algorithm** will be used to derive the key. Upon key creation, a first key version is also automatically created.
29-
30-
### Retrieve a key:
31-
32-
Retrieving a key **only returns the metadata associated with the key**. The key versions will not be returned when retrieving a key.
33-
34-
### List keys:
35-
36-
You can retrieve a subset of your keys according to filters such as "name", "description", "tags", etc.
37-
38-
### Update a key:
39-
40-
You can update the key's name, description or tags at any time.
41-
42-
### Enable and disable key protection:
43-
44-
**Enabling key protection prevents any accidental deletion of a key**. You must disable key protection before deleting a key to which key protection is applied.
45-
46-
### Rotate a key:
47-
48-
Rotating a key **creates a new key version and makes all previous versions obsolete**.
49-
50-
### Delete a key:
51-
52-
Deleting a key also **deletes all its versions**.
53-
23+
Read our [dedicated documentation](/identity-and-access-management/key-manager/reference-content/understanding-key-manager/#management-methods-you-can-use-with-key-manager) to find out about the management methods Key Manager provides.
5424

5525
## Which cryptographic operations does Key Manager support?
5626

57-
At the moment, Scaleway's Key Manager supports the three following cryptographic operations.
27+
Key Manager supports the three following cryptographic operations:
5828

59-
| Encryption | Decryption | Data encryption key generation |
60-
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
61-
| Encrypt data using the latest version of the Key Manager key. The encryption algorithm used is the one defined when setting the 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 only to encrypt data encryption keys, not actual payloads. [Find out how to encrypt and decrypt payloads using The Scaleway Tink provider](/identity-and-access-management/key-manager/api-cli/manage-keys-with-tink) | This operation lets you decrypt an encrypted payload. **The only way to decrypt an encrypted payload is by using the `Decrypt` endpoint. Since key versions never leave Key Manager, there is no other way to decrypt data outside Key Manager.** A payload encrypted with an older key version can still be decrypted. In this case, for convenience, the payload encrypted with the latest key version will be returned, along with the decrypted payload. | Generate a symmetric [data encryption key](/identity-and-access-management/key-manager/concepts/#data-encryption-key-(dek)) (DEK) that can be used outside Key Manager to encrypt and decrypt payloads. This DEK is encrypted with a key encryption key, specified by the caller. **The management of the DEK is the responsibility of the caller. The DEK should be stored safely and have the same lifecycle as the payload it encrypts.** |
29+
- [Encryption](/identity-and-access-management/key-manager/concepts/#encryption)
30+
- [Decryption](/identity-and-access-management/key-manager/concepts/#decryption)
31+
- [Data encryption key](/identity-and-access-management/key-manager/concepts/#data-encryption-key-dek) generation
6232

6333
## Which algorithms and key usage does Key Manager support?
6434

65-
Key Manager **only supports symmetric encryption as of yet**.
35+
<Macro id="encryption" />
6636

6737
Keys with a [key usage](/identity-and-access-management/key-manager/concepts/#key-usage) set to `symmetric_encryption` are **used to encrypt and decrypt data**.
6838

69-
Key Manager currently **only supports the `AES-256-GCM` key algorithm**. Refer to our [dedicated documentation](/identity-and-access-management/key-manager/reference-content/understanding-key-manager/) to find out which parameters (in compliance with the [recommendations of ANSSI](https://cyber.gouv.fr/publications/mecanismes-cryptographiques)) are used when creating and using a key with the `AES-256 GCM` [symmetric encryption](/identity-and-access-management/key-manager/concepts/#symmetric-encryption) algorithm.
39+
Refer to our [dedicated documentation](/identity-and-access-management/key-manager/reference-content/understanding-key-manager/) to find out more about Key Manager.

‎identity-and-access-management/key-manager/concepts.mdx‎

Lines changed: 64 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -24,29 +24,76 @@ Ciphertext refers to data that has been encrypted using a cryptographic algorith
2424

2525
Unlike [plaintext](#plaintext), ciphertext is not human-readable and cannot be understood or used without first decrypting it with the appropriate decryption key.
2626

27+
## Cryptographic operation
28+
29+
A cryptographic operation is any action performed using cryptography to secure data, ensure privacy, or authenticate information.
30+
31+
Key Manager supports the three following cryptographic operations:
32+
33+
- [Encryption](#encryption)
34+
- [Decryption](#decryption)
35+
- [Data encryption key](#data-encryption-key-dek) generation
36+
37+
38+
These operations are designed to protect data from unauthorized access, ensure its integrity, and verify the identities of users or systems.
39+
2740
## Data encryption key (DEK)
2841

29-
A data encryption key is a type of key that has a single purpose: encrypting and decrypting a [payload](#payload).
42+
A data encryption key is a type of key that can be used outside Key Manager to encrypt and decrypt [payloads](#payload).
43+
44+
Key Manager generates DEKs on-demand. They are then encrypted by a [key encryption key](#key-encryption-key-kek) specified by the user, and forwarded to the recipient.
45+
46+
DEKs are **not stored in or managed by Key Manager**. The user is reponsible for safely storing and managing DEKs. DEKs should have the same lifecycle as the [payload](#payload) they encrypt**.
47+
48+
## Decryption
49+
50+
A cryptographic operation used to convert [ciphertext](#ciphertext) back into its original [plaintext](#plaintext) form, using a key encryption key.
51+
52+
The only way to decrypt an encrypted payload is by using the `Decrypt` [endpoint](https://www.scaleway.com/en/developers/api/key-manager/V1/#path-keys-decrypt-keys). Since key versions never leave Key Manager, there is no other way to decrypt data outside Key Manager.** A payload encrypted with an older key version can still be decrypted. In this case, for convenience, the payload encrypted with the latest key version will be returned, along with the decrypted payload.
53+
54+
## Encryption
55+
56+
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).
3057

31-
DEKs are generated on-demand, and are then encrypted by a [key encryption key](#key-encryption-key-(kek)) before being forwarded to the user.
58+
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).
3259

33-
DEKs are not stored in Key Manager, but by the recipient. The lifecycle of a DEK typically follows the lifecycle of the payload:
60+
[Find out how to encrypt and decrypt payloads using The Scaleway Tink provider](/identity-and-access-management/key-manager/api-cli/manage-keys-with-tink)
3461

35-
1. A new DEK is generated for each payload that needs encryption.
36-
2. The DEK is disposed of as soon as the payload becomes irrelevant.
62+
## Encryption algorithm
63+
64+
An encryption algorithm is the specific procedure used to perform encryption and decryption.
65+
66+
It defines the exact steps to transform plaintext into ciphertext and vice versa using a key.
67+
68+
As of now, Key Manager supports the following encryption algorithm:
69+
70+
- AES (Advanced Encryption Standard): A widely used symmetric encryption algorithm.
3771

3872
## Encryption method
3973

40-
An encryption method is a process used to convert readable data ([plaintext](#plaintext)) into an unreadable format ([ciphertext](#ciphertext)) to protect its confidentiality.
74+
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).
4175

42-
There are two types of encryption methods:
76+
There are three types of encryption methods:
4377

4478
- [Symmetric encryption](#symmetric-encryption)
4579
- [Asymmetric encrytpion](#asymmetric-encryption)
80+
- Hybrid encryption: An encryption method that combines both symmetric and asymmetric methods
81+
82+
Key Manager only supports symmetric encryption.
83+
84+
## Encryption scheme
85+
86+
An encryption scheme is a structured approach to encryption that specifies the encryption algorithm, key size, and mode of operation for block chiphers.
87+
88+
For example, in the `AES-256-GCM` encryption scheme:
89+
90+
- `AES` refers to the Advanced Encryption Standard (AES) encryption algorithm
91+
- `256` refers to the key length in bits
92+
- `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.
4693

4794
## Key encryption key (KEK)
4895

49-
A key encryption key (KEK) is a type of key that has a single purpose: encrypting and decrypting [data encryption keys](#data-encryption-key-(dek)).
96+
A key encryption key (KEK) is a type of key that has a single purpose: encrypting and decrypting [data encryption keys](#data-encryption-key-dek).
5097

5198
The KEK is permanently stored in Scaleway's Key Manager and never leaves it. It cannot be accessed by anyone, and should be [rotated](/identity-and-access-management/key-manager/api-cli/rotate-keys-api-cli/) regularly.
5299

@@ -72,6 +119,14 @@ After rotating your Key Manager keys, all cryptographic operations will use the
72119
The key usage specifies the **algorithm** used to create subsequent key versions, and the **scope of cryptographic operations** supported by your key encryption key.
73120
You must define a key usage upon key creation. As of now, Key Manager **only supports symmetric encryption**.
74121

122+
## Key version
123+
124+
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.
125+
126+
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.
127+
128+
Data you have encrypted with previous key versions will still be accessible and decipherable using those specific keys, ensuring backward compatibility.
129+
75130
## Payload
76131

77132
A payload refers to the core data or message being transmitted, processed, or protected. It is the information of interest that encryption or other security mechanisms aim to secure.
@@ -94,4 +149,4 @@ Symmetric encryption is a fundamental type of cryptographic method where the sam
94149

95150
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.
96151

97-
Symmetric encryption algorithms like AES are widely used in scenarios where speed and efficiency are critical. Key manager supports the `AES_256_GCM` symmetric encryption algorithm.
152+
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.

‎identity-and-access-management/key-manager/how-to/manage-dek.mdx‎

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,13 @@ content:
77
paragraph: Discover how to create a data encryption key from the Scaleway console to encrypt and decrypt your payloads using Scaleway's Key Manager.
88
tags: key-manager data-encryption-key data key payload encryption
99
dates:
10-
validation: 2024-12-09
11-
posted: 2024-12-09
10+
validation: 2024-12-11
11+
posted: 2024-12-11
1212
categories:
1313
- identity-and-access-management
1414
---
1515

16-
Scaleway's key Manager allows you to create [data encryption keys (DEK)](/identity-and-access-management/key-manager/concepts/#data-encryption-key-(dek)) to encrypt and decrypt your [payload](/identity-and-access-management/key-manager/concepts/#payload).
16+
Scaleway's key Manager allows you to create [data encryption keys (DEK)](/identity-and-access-management/key-manager/concepts/#data-encryption-key-dek) to encrypt and decrypt your [payload](/identity-and-access-management/key-manager/concepts/#payload).
1717

1818
You can then use your Key Manager key to encrypt your DEK.
1919

@@ -35,10 +35,9 @@ You can then use your Key Manager key to encrypt your DEK.
3535
4. Click **Generate data encryption key**. A pop-up displays with the [ciphertext](/identity-and-access-management/key-manager/concepts/#ciphertext) of your DEK.
3636
5. Copy and store your DEK's ciphertext safely.
3737
<Message type="important">
38-
As Key Manager does not store your DEKs, we recommend that you **always store the ciphertext** of your data encryption key rather than its [plaintext](/identity-and-access-management/key-manager/concepts/#plaintext).
38+
- We recommend that you **always store the ciphertext** of your data encryption key rather than its [plaintext](/identity-and-access-management/key-manager/concepts/#plaintext).
39+
- While Scaleway Key Manager is responsible for generating, encrypting, and decrypting data encryption keys, it does not store, manage, or monitor them, nor does it engage in cryptographic operations with these keys. **You must use and manage data encryption keys outside of Key Manager**.
40+
- Read our [documentation](/identity-and-access-management/key-manager/reference-content/understanding-key-manager/) to understand Key Manager.
3941
</Message>
4042
6. Optionally, click **Display plaintext** to make sure that the plaintext does not contain any mistakes.
41-
7. Click **Close**.
42-
43-
### Differences between ciphertext and plaintext
44-
43+
7. Click **Close**.

0 commit comments

Comments
 (0)