Skip to content

Commit 10b521c

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

18 files changed

+1290
-0
lines changed

‎faq/key-manager.mdx‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
meta:
3+
title: Key Manager FAQ
4+
description: Explore Scaleway Key Manager with our comprehensive FAQ covering security, key types, and more.
5+
content:
6+
h1: Key Manager
7+
dates:
8+
validation: 2024-12-09
9+
category: identity-and-access-management
10+
productIcon: KeyManagerProductIcon
11+
---
12+
13+
## Why should you use Scaleway Key Manager?
14+
15+
Key Manager helps organizations achieve secure key management by handling low-level and error-prone cryptographic details for you.
16+
17+
18+
## What features does Scaleway Key Manager include?
19+
20+
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.
21+
22+
## Which management methods can I use with Key Manager?
23+
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+
54+
55+
## Which cryptographic operations does Key Manager support?
56+
57+
At the moment, Scaleway's Key Manager supports the three following cryptographic operations.
58+
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.** |
62+
63+
## Which algorithms and key usage does Key Manager support?
64+
65+
Key Manager **only supports symmetric encryption as of yet**.
66+
67+
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**.
68+
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.

‎identity-and-access-management/key-manager/api-cli/create-dek-api-cli.mdx‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
meta:
3+
title: Create a data encryption key using the Scaleway API and the Scaleway CLI
4+
description: Discover how to create a data encryption key using the Scaleway API and the Scaleway CLI.
5+
content:
6+
h1: Create a data encryption key using the Scaleway API and the Scaleway CLI
7+
paragraph: Discover how to create a data encryption key using the Scaleway API and the Scaleway CLI.
8+
tags: key-management dek data-encryption-key cli sdk api encryption
9+
categories:
10+
- identity-and-access-management
11+
dates:
12+
validation: 2024-12-09
13+
posted: 2024-12-09
14+
---
15+
16+
<Macro id="requirements" />
17+
18+
- A Scaleway account logged into the [console](https://console.scaleway.com)
19+
- [Owner](/identity-and-access-management/iam/concepts/#owner) status or [IAM permissions](/identity-and-access-management/iam/concepts/#permission) allowing you to perform actions in the intended Organization
20+
- Created a key encryption key either from the [Scaleway console](/identity-and-access-management/key-manager/how-to/create-km-key) or the [Key Manager API](https://www.scaleway.com/en/developers/api/key-manager/#path-keys-create-a-key)
21+
- Retrieved your key encryption key's ID
22+
- Created an [API key](/identity-and-access-management/iam/how-to/create-api-keys/)
23+
- Downloaded and configured the [Scaleway CLI](https://github.com/scaleway/scaleway-cli?tab=readme-ov-file#getting-started)
24+
25+
## Generate a DEK using the Scaleway CLI
26+
27+
1. Open a terminal and paste the following commands to export your environment variables. Make sure that you replace the placeholder values with your own.
28+
```bash
29+
export SCW_ACCESS_KEY=<SCALEWAY_API_ACCESS_KEY>
30+
export SCW_SECRET_KEY=<SCALEWAY_API_SECRET_KEY>
31+
export SCW_DEFAULT_ORGANIZATION_ID=<SCALEWAY_ORGANIZATION_ID>
32+
export SCW_PROJECT_ID=<SCALEWAY_PROJECT_ID>
33+
export SCW_DEFAULT_REGION="fr-par"
34+
export SCW_API_URL="https://api.scaleway.com"
35+
```
36+
37+
2. Paste the following command to generate a data encryption key via the Scaleway CLI. Make sure that you replace `<your_kek_id>` with the ID of your key encryption key.
38+
```bash
39+
scw keymanager key generate-data-key key-id=<your_kek_id> algorithm=aes_256_gcm
40+
```
41+
42+
An output similar to the following should display:
43+
```bash
44+
KeyID <kek_id>
45+
Algorithm <algorithm_used_to_encrypt_your_key>
46+
Ciphertext <your_base64_encrypted_dek>
47+
Plaintext <your_base64_decrypted_dek>
48+
CreatedAt <creation_date>
49+
```
50+
51+
52+
## Generate a DEK using the API
53+
54+
Paste the following command to create your data encryption key via the Key Manager API. Make sure that you replace the placeholder values with your own.
55+
```bash
56+
curl --location 'https://api.scaleway.com/key-manager/v1alpha1/regions/fr-par/keys/<your_key_id>/generate-data-key' \
57+
--header 'Content-Type: application/json' \
58+
--header 'X-Auth-Token: <your_secret_key>' \
59+
--data '{
60+
"algorithm": "aes_256_gcm"
61+
}'
62+
```
63+
64+
Key Manager also supports the `GenerateDataKey` request without a plaintext operation, which only returns an encrypted data encryption key.
65+
66+
If you need to use your DEK, you can decrypt it using the [Decrypt data operation](https://www.scaleway.com/en/developers/api/key-manager/#path-keys-decrypt-data) specifying the `kek_id` parameter used to encrypt it.
67+
68+
Key Manager **does not allow the use of data encryption keys for data encryption**.
69+
70+
However, you can use the DEK independently from Key Manager, for example with the [Tink extension](/encrypt-decrypt-dek-/#encrypt-and-decrypt-data-with-tink-and-key-manager) or with [OpenSSL](/encrypt-decrypt-dek/#manually-encrypt-and-decrypt-data-with-a-key-manager-dek).
71+
72+
73+
!!! info
74+
75+
The way the KEK is generated, its length, and the encryption algorithm used, **cannot be changed or customized after creation**.
76+
77+
However, unlike the KEK, you have the flexibility to choose any encryption algorithm (cipher) you prefer for encrypting and decrypting your data with the DEK. You are not restricted to a specific encryption method for the data itself.
78+
79+
**We highly recommend that you use standard and well-established ciphers (and the proper mode), as well as a library like Tink, that chooses the right cryptosystem according to your use-case.**

‎identity-and-access-management/key-manager/api-cli/index.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
meta:
3+
title: Key Manager - API/CLI Documentation
4+
description: Key Manager API/CLI Documentation
5+
content:
6+
h1: API/CLI Documentation
7+
paragraph: Key Manager API/CLI Documentation
8+
---

0 commit comments

Comments
 (0)