Skip to content

Commit f9a6f6d

Browse files
nerda-codesnerda-codes
authored
feat(key-manager): add docs (#4344)
1 parent d98ac46 commit f9a6f6d

30 files changed

+1800
-3
lines changed

‎faq/key-manager.mdx‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
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: 2025-02-06
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+
## What features does Scaleway Key Manager include?
18+
19+
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.
20+
21+
## Which management methods can I use with Key Manager?
22+
23+
Read our [dedicated documentation](/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.
24+
25+
## Which cryptographic operations does Key Manager support?
26+
27+
Key Manager supports the three following cryptographic operations:
28+
29+
- [Encryption](/key-manager/concepts/#encryption)
30+
- [Decryption](/key-manager/concepts/#decryption)
31+
- [Data encryption key](/key-manager/concepts/#data-encryption-key-dek) generation
32+
33+
## Which algorithms and key usage does Key Manager support?
34+
35+
<Macro id="encryption" />
36+
37+
Keys with a [key usage](/key-manager/concepts/#key-usage) set to `symmetric_encryption` are **used to encrypt and decrypt data**.
38+
39+
Refer to our [dedicated documentation](/key-manager/reference-content/understanding-key-manager/) to find out more about Key Manager.

‎macros/key-manager/encryption.mdx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
macro: key-manager-encryption
3+
---
4+
5+
**Key Manager only supports the `AES-256-GCM` [encryption scheme](/key-manager/concepts/#encryption-scheme).**

‎macros/key-manager/plaintext-vs-ciphertext.mdx‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
macro: key-manager-plaintext-vs-ciphertext
3+
---
4+
5+
<Concept>
6+
## What is the difference between ciphertext and plaintext?
7+
**Ciphertext** refers to data that has been encrypted using a cryptographic algorithm and a key.
8+
Ciphertext can be encrypted on the client side as long as the encryption key used for encryption is safely stored (in a Key Manager, for example).
9+
Unlike plaintext, ciphertext is not human-readable and cannot be understood or used without first decrypting it with the appropriate decryption key.
10+
11+
**Plaintext** refers to unencrypted, readable data. In the context of key management, plaintext often refers to cryptographic keys or sensitive data that are stored or transmitted in an unencrypted form. This term is often used in contrast to ciphertext, which is data that has been encrypted and is not readable without decryption.
12+
</Concept>
13+

‎menu/changelogs.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,10 @@
9797
{
9898
"category": "audit-trail",
9999
"label": "Audit Trail"
100+
},
101+
{
102+
"category": "key-manager",
103+
"label": "Key Manager"
100104
}
101105
],
102106
"category": "security-identity",

‎menu/navigation.json‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -608,6 +608,110 @@
608608
],
609609
"label": "Secret Manager",
610610
"slug": "secret-manager"
611+
},
612+
{
613+
"items": [
614+
{
615+
"label": "Overview",
616+
"slug": "../key-manager"
617+
},
618+
{
619+
"label": "Concepts",
620+
"slug": "concepts"
621+
},
622+
{
623+
"label": "Quickstart",
624+
"slug": "quickstart"
625+
},
626+
{
627+
"label": "FAQ",
628+
"slug": "../faq/key-manager"
629+
},
630+
{
631+
"items": [
632+
{
633+
"label": "Create a Key Manager key",
634+
"slug": "create-km-key"
635+
},
636+
{
637+
"label": "Retrieve the ID of a Key Manager key",
638+
"slug": "retrieve-km-key-id"
639+
},
640+
{
641+
"label": "Create and manage a Key Manager data encryption key",
642+
"slug": "create-manage-dek"
643+
},
644+
{
645+
"label": "Rotate Key Manager keys",
646+
"slug": "rotate-km-keys"
647+
},
648+
{
649+
"label": "Disable Key Manager keys",
650+
"slug": "disable-km-key"
651+
},
652+
{
653+
"label": "Delete Key Manager keys",
654+
"slug": "delete-km-key"
655+
}
656+
],
657+
"label": "How to",
658+
"slug": "how-to"
659+
},
660+
{
661+
"items": [
662+
{
663+
"label": "Understanding security measures when using Key Manager",
664+
"slug": "security-recommendations"
665+
},
666+
{
667+
"label": "Understanding Key Manager",
668+
"slug": "understanding-key-manager"
669+
},
670+
{
671+
"label": "Differences between Key Manager and Secret Manager",
672+
"slug": "differences-key-and-secret-manager"
673+
}
674+
],
675+
"label": "Additional Content",
676+
"slug": "reference-content"
677+
},
678+
{
679+
"items": [
680+
{
681+
"label": "Key Manager API Reference",
682+
"slug": "https://www.scaleway.com/en/developers/api/key-manager/"
683+
},
684+
{
685+
"label": "Creating a data encryption key using the Scaleway API and the Scaleway CLI",
686+
"slug": "create-dek-api-cli"
687+
},
688+
{
689+
"label": "Setting up and configuring Tink",
690+
"slug": "configuring-tink"
691+
},
692+
{
693+
"label": "Managing your Key Manager keys using Tink",
694+
"slug": "manage-keys-with-tink"
695+
},
696+
{
697+
"label": "Rotate keys using the Scaleway CLI and API",
698+
"slug": "rotate-keys-api-cli"
699+
},
700+
{
701+
"label": "Encrypting and decrypting data with a Key Manager data encryption key",
702+
"slug": "encrypt-decrypt-data-with-km-dek"
703+
},
704+
{
705+
"label": "Encrypting and decrypting data streams with Streaming AEAD, Tink and Key Manager",
706+
"slug": "encrypt-decrypt-keys-with-streaming-aead-tink"
707+
}
708+
],
709+
"label": "API/CLI",
710+
"slug": "api-cli"
711+
}
712+
],
713+
"label": "Key Manager",
714+
"slug": "key-manager"
611715
}
612716
],
613717
"label": "Security & Identity",

‎pages/iam/reference-content/permission-sets.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -123,7 +123,8 @@ Below is a list of the permission sets available at Scaleway.
123123
| SecretManagerSecretWrite | Permission to edit the metadata (name, tags, description, etc.) of secrets and their versions in Secret Manager. Does not include permission to create secrets and versions |
124124
| BlockStorageReadOnly | List and read access to Block Storage |
125125
| BlockStorageFullAccess | Full access to create, read, list, edit and delete in Block Storage |
126-
126+
| KeyManagerFullAccess | Full access to create, read, list, edit and delete in Key Manager |
127+
| KeyManagerReadOnly | List and read access to Key Manager |
127128

128129
<Message type="important">
129130
Some additional permission sets may appear on your Scaleway console if you are enrolled in beta testing for products or features.

‎pages/key-manager/api-cli/configuring-tink.mdx‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
meta:
3+
title: Setting up and configuring Tink
4+
description: Follow this guide to learn how to configure your environment and dependencies before using Tink in your projects.
5+
content:
6+
h1: Setting up and configuring Tink
7+
paragraph: Follow this guide to learn how to configure your environment and dependencies before using Tink in your projects.
8+
tags: key-management dek data-encryption-key cli sdk api encryption
9+
dates:
10+
validation: 2025-02-03
11+
posted: 2025-02-03
12+
---
13+
14+
This page shows you how to set up and configure Tink for encrypting and decrypting data with Scaleway's Key Manager.
15+
16+
We recommend using Tink with Scaleway’s Key Manager, especially for Go-based applications.
17+
18+
<Macro id="requirements" />
19+
20+
- A Scaleway account logged into the [console](https://console.scaleway.com)
21+
- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization
22+
- Downloaded and installed [Go](https://go.dev/doc/install)
23+
- Installed the [Scaleway Go SDK](https://github.com/scaleway/scaleway-sdk-go) with [valid credentials](/scaleway-sdk/go-sdk/)
24+
- [Created a Key Manager key](/key-manager/how-to/create-km-key)
25+
26+
27+
Tink is a library that helps you perform encryption (securing data) and manage encryption keys. It can work with various key management services (KMS), including Scaleway's Key Manager.
28+
29+
The Scaleway Tink extension generates a unique data encryption key for each piece of data that it encrypts. This method follows the cryptography best practices of using unique data encryption keys for each encryption operation.
30+
To use Tink with Scaleway Key Manager, you need to install dependencies that let Tink interact with Key Manager.
31+
32+
33+
## Setting up environment variables
34+
35+
Open a terminal and export the following environment variables. Make sure that you replace the placeholder values with your own.
36+
37+
```bash
38+
export SCW_ACCESS_KEY="<access-key>"
39+
export SCW_SECRET_KEY="<secret-key>"
40+
export SCW_DEFAULT_ORGANIZATION_ID="<organization-id>"
41+
export SCW_PROJECT_ID="<project-id>"
42+
export SCW_DEFAULT_REGION="<region>"
43+
export SCW_API_URL="<api-url>"
44+
export SCW_KM_KEY_ID="<key-id>"
45+
```
46+
47+
## Setting up Tink
48+
49+
1. Open a terminal and access your project directory:
50+
51+
```shell
52+
cd <your-project-directory>
53+
```
54+
55+
2. Initialize a Go module in your project directory:
56+
```shell
57+
go mod init <your-project-directory>
58+
```
59+
60+
3. Run the following commands to install the Tink library and the Scaleway Tink Provider for Go:
61+
62+
```shell
63+
# Install Tink for Go
64+
go get -u github.com/tink-crypto/tink-go/v2
65+
66+
# Install the Scaleway Tink extension
67+
go get -u github.com/scaleway/tink-go-scwkms
68+
go mod tidy
69+
```
70+
71+
## Configuring Tink
72+
73+
In order to use Tink for data encryption, you need to provide it with a key URI and a configuration file:
74+
75+
- The key URI points to your key encryption key (KEK) in Scaleway Key Manager.
76+
77+
- The configuration file grants Tink the necessary permissions to access and use the KEK identified by the Key URI.
78+
79+
Tink generates a data encryption key (DEK) which will be used to encrypt your data. The DEK itself is then encrypted using the KEK from Key Manager. This ensures that the DEK is securely protected and can only be decrypted by someone with access to the KEK.
80+
81+
The final output is a single ciphertext that includes both the encrypted data and the encrypted DEK (wrapped DEK). This means that the DEK and the data are both securely packaged together.
82+
83+
Scaleway supports the **Go Tink provider**.
84+
85+
1. [Retrieve the ID](/key-manager/how-to/retrieve-km-key-id) (UUIDv4 format) of your Key Manager's key (KEK).
86+
2. Copy the following template and paste it into a `.go` file:
87+
88+
```go
89+
import (
90+
"github.com/scaleway/scaleway-sdk-go/scw" // Library that helps your Go program interact with Scaleway
91+
"github.com/tink-crypto/tink-go/v2/aead" // Tink library
92+
"github.com/scaleway/tink-go-scwkms/integration/scwkms" // Scaleway's Tink extension
93+
)
94+
95+
const region = "<REGION>" // Replace the placeholder with the region where your key is created
96+
const keyID = "7f967268-bebb-43b0-9fe2-e13bd23bf421" // Replace the placeholder with the unique ID of your key encryption key
97+
98+
keyURIPrefix := "scw-kms://regions/" + region + "/keys/"
99+
keyURI := keyURIPrefix + keyID
100+
101+
// Set up a connection to Scaleway
102+
config, _ := scw.LoadConfig() // Loads your Scaleway configuration
103+
profile, _ := config.GetActiveProfile() // Gets the active profile (your account settings)
104+
105+
// Set up the connection to use your key in Key Manager
106+
kms, _ := scwkms.NewClientWithOptions(
107+
keyURIPrefix,
108+
scw.WithProfile(profile), // Uses your account profile
109+
scw.WithEnv(), // Uses environment settings
110+
)
111+
// Prepare the key for encryption and decryption
112+
kekAEAD, _ := kms.GetAEAD(keyURI)
113+
```
114+
3. Replace the placeholder values with your own.
115+
116+
<Message type="note">
117+
The `kekAEAD` object represents the key in Scaleway’s Key Manager. It allows you to encrypt payloads and decrypt ciphertexts.
118+
</Message>
119+
120+
Find out how to encrypt and decrypt data with Tink in the [dedicated documentation](/key-manager/api-cli/encrypt-decrypt-data-with-km-dek/).

‎pages/key-manager/api-cli/create-dek-api-cli.mdx‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
meta:
3+
title: Creating a data encryption key using the Scaleway API and the Scaleway CLI
4+
description: Learn how to generate a data encryption key (DEK) using the Scaleway CLI or API, leveraging Key Manager with AES encryption for secure data handling.
5+
content:
6+
h1: Creating a data encryption key using the Scaleway API and the Scaleway CLI
7+
paragraph: Learn how to generate a data encryption key (DEK) using the Scaleway CLI or API, leveraging Key Manager with AES encryption for secure data handling.
8+
tags: key-management dek data-encryption-key cli sdk api encryption
9+
dates:
10+
validation: 2025-02-06
11+
posted: 2025-02-06
12+
---
13+
14+
<Macro id="requirements" />
15+
16+
- A Scaleway account logged into the [console](https://console.scaleway.com)
17+
- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization
18+
- Created a key encryption key either from the [Scaleway console](/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)
19+
- Retrieved your key encryption key's ID
20+
- Created an [API key](/iam/how-to/create-api-keys/)
21+
- Downloaded and configured the [Scaleway CLI](https://github.com/scaleway/scaleway-cli?tab=readme-ov-file#getting-started)
22+
23+
## Generate a DEK using the Scaleway CLI
24+
25+
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.
26+
```bash
27+
export SCW_ACCESS_KEY=<SCALEWAY_API_ACCESS_KEY>
28+
export SCW_SECRET_KEY=<SCALEWAY_API_SECRET_KEY>
29+
export SCW_DEFAULT_ORGANIZATION_ID=<SCALEWAY_ORGANIZATION_ID>
30+
export SCW_PROJECT_ID=<SCALEWAY_PROJECT_ID>
31+
export SCW_DEFAULT_REGION="fr-par"
32+
export SCW_API_URL="https://api.scaleway.com"
33+
```
34+
35+
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.
36+
```bash
37+
scw keymanager key generate-data-key key-id=<your_kek_id> algorithm=aes_256_gcm
38+
```
39+
40+
An output similar to the following should display:
41+
```bash
42+
KeyID <kek_id>
43+
Algorithm <algorithm_used_to_encrypt_your_key>
44+
Ciphertext <your_base64_encrypted_dek>
45+
Plaintext <your_base64_decrypted_dek>
46+
CreatedAt <creation_date>
47+
```
48+
49+
<Message type="important">
50+
For convenience, Key Manager returns the plaintext version of the DEK, but it should never be stored in this form. Storing the decrypted plaintext of your DEK undermines the security provided by Key Manager, rendering it ineffective.
51+
</Message>
52+
53+
## Generate a DEK using the API
54+
55+
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.
56+
```bash
57+
curl --location 'https://api.scaleway.com/key-manager/v1alpha1/regions/fr-par/keys/<your_key_id>/generate-data-key' \
58+
--header 'Content-Type: application/json' \
59+
--header 'X-Auth-Token: <your_secret_key>' \
60+
--data '{
61+
"algorithm": "aes_256_gcm"
62+
}'
63+
```
64+
65+
Key Manager also supports the `GenerateDataKey` request without a plaintext operation, which only returns an encrypted data encryption key.
66+
67+
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.
68+
69+
**Key Manager does not handle direct data encryption**. It is specifically designed to **encrypt and decrypt Data Encryption Keys (DEKs) and is limited to processing inputs up to 64 kB in size**.
70+
71+
However, you can use the DEK independently from Key Manager, for example with the [Tink extension](/key-manager/api-cli/encrypt-decrypt-data-with-km-dek/) or with [OpenSSL](/key-manager/api-cli/encrypt-decrypt-data-with-km-dek/).
72+
73+
<Message type="important">
74+
The way the KEK is generated, its length, and the encryption algorithm used, **cannot be changed or customized after creation**. 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.
75+
**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.**
76+
</Message>

0 commit comments

Comments
 (0)