feat(key-manager): add docs (#4344)

faq/key-manager.mdx

@@ -0,0 +1,39 @@
+---
+meta:
+  title: Key Manager FAQ
+  description: Explore Scaleway Key Manager with our comprehensive FAQ covering security, key types, and more.
+content:
+  h1: Key Manager
+dates:
+  validation: 2025-02-06
+category: identity-and-access-management
+productIcon: KeyManagerProductIcon
+---
+
+## Why should you use Scaleway Key Manager?
+
+Key Manager helps organizations achieve secure key management by handling low-level and error-prone cryptographic details for you.
+
+## What features does Scaleway Key Manager include?
+
+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.
+
+## Which management methods can I use with Key Manager?
+
+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.
+
+## Which cryptographic operations does Key Manager support?
+
+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
+
+## 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**.
+
+Refer to our [dedicated documentation](/key-manager/reference-content/understanding-key-manager/) to find out more about Key Manager.

macros/key-manager/encryption.mdx

@@ -0,0 +1,5 @@
+---
+macro: key-manager-encryption
+---
+
+**Key Manager only supports the `AES-256-GCM` [encryption scheme](/key-manager/concepts/#encryption-scheme).**

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

@@ -0,0 +1,13 @@
+---
+macro: key-manager-plaintext-vs-ciphertext
+---
+
+<Concept>
+ ## What is the difference between ciphertext and plaintext?
+ **Ciphertext** refers to data that has been encrypted using a cryptographic algorithm and a key.
+  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).
+  Unlike plaintext, ciphertext is not human-readable and cannot be understood or used without first decrypting it with the appropriate decryption key.
+
+ **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.
+</Concept>
+

menu/changelogs.json

@@ -97,6 +97,10 @@
       {
         "category": "audit-trail",
         "label": "Audit Trail"
+      },
+      {
+        "category": "key-manager",
+        "label": "Key Manager"
       }
     ],
     "category": "security-identity",

menu/navigation.json

@@ -608,6 +608,110 @@
             ],
             "label": "Secret Manager",
             "slug": "secret-manager"
+          },
+          {
+            "items": [
+              {
+                "label": "Overview",
+                "slug": "../key-manager"
+              },
+              {
+                "label": "Concepts",
+                "slug": "concepts"
+              },
+              {
+                "label": "Quickstart",
+                "slug": "quickstart"
+              },
+              {
+                "label": "FAQ",
+                "slug": "../faq/key-manager"
+              },
+              {
+                "items": [
+                  {
+                    "label": "Create a Key Manager key",
+                    "slug": "create-km-key"
+                  },
+                  {
+                    "label": "Retrieve the ID of a Key Manager key",
+                    "slug": "retrieve-km-key-id"
+                  },
+                  {
+                    "label": "Create and manage a Key Manager data encryption key",
+                    "slug": "create-manage-dek"
+                  },
+                  {
+                    "label": "Rotate Key Manager keys",
+                    "slug": "rotate-km-keys"
+                  },
+                  {
+                    "label": "Disable Key Manager keys",
+                    "slug": "disable-km-key"
+                  },
+                  {
+                    "label": "Delete Key Manager keys",
+                    "slug": "delete-km-key"
+                  }
+                ],
+                "label": "How to",
+                "slug": "how-to"
+              },
+              {
+                "items": [
+                  {
+                    "label": "Understanding security measures when using Key Manager",
+                    "slug": "security-recommendations"
+                  },
+                  {
+                    "label": "Understanding Key Manager",
+                    "slug": "understanding-key-manager"
+                  },
+                  {
+                    "label": "Differences between Key Manager and Secret Manager",
+                    "slug": "differences-key-and-secret-manager"
+                  }
+                ],
+                "label": "Additional Content",
+                "slug": "reference-content"
+              },
+              {
+                "items": [
+                  {
+                    "label": "Key Manager API Reference",
+                    "slug": "https://www.scaleway.com/en/developers/api/key-manager/"
+                  },
+                  {
+                    "label": "Creating a data encryption key using the Scaleway API and the Scaleway CLI",
+                    "slug": "create-dek-api-cli"
+                  },
+                  {
+                    "label": "Setting up and configuring Tink",
+                    "slug": "configuring-tink"
+                  },
+                  {
+                    "label": "Managing your Key Manager keys using Tink",
+                    "slug": "manage-keys-with-tink"
+                  },
+                  {
+                    "label": "Rotate keys using the Scaleway CLI and API",
+                    "slug": "rotate-keys-api-cli"
+                  },
+                  {
+                    "label": "Encrypting and decrypting data with a Key Manager data encryption key",
+                    "slug": "encrypt-decrypt-data-with-km-dek"
+                  },
+                  {
+                    "label": "Encrypting and decrypting data streams with Streaming AEAD, Tink and Key Manager",
+                    "slug": "encrypt-decrypt-keys-with-streaming-aead-tink"
+                  }
+                ],
+                "label": "API/CLI",
+                "slug": "api-cli"
+              }
+            ],
+            "label": "Key Manager",
+            "slug": "key-manager"
           }
         ],
         "label": "Security & Identity",

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

@@ -123,7 +123,8 @@ Below is a list of the permission sets available at Scaleway.
 | 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           |
 | BlockStorageReadOnly         | List and read access to Block Storage                |
 | BlockStorageFullAccess       | Full access to create, read, list, edit and delete in Block Storage            |
-
+| KeyManagerFullAccess       | Full access to create, read, list, edit and delete in Key Manager           |
+| KeyManagerReadOnly       | List and read access to Key Manager            |
 
 <Message type="important">
   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

@@ -0,0 +1,120 @@
+---
+meta:
+  title: Setting up and configuring Tink
+  description: Follow this guide to learn how to configure your environment and dependencies before using Tink in your projects.
+content:
+  h1: Setting up and configuring Tink
+  paragraph: Follow this guide to learn how to configure your environment and dependencies before using Tink in your projects.
+tags: key-management dek data-encryption-key cli sdk api encryption
+dates:
+  validation: 2025-02-03
+  posted: 2025-02-03
+---
+
+This page shows you how to set up and configure Tink for encrypting and decrypting data with Scaleway's Key Manager.
+
+We recommend using Tink with Scaleway’s Key Manager, especially for Go-based applications.
+
+<Macro id="requirements" />
+
+- A Scaleway account logged into the [console](https://console.scaleway.com)
+- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization
+- Downloaded and installed [Go](https://go.dev/doc/install)
+- Installed the [Scaleway Go SDK](https://github.com/scaleway/scaleway-sdk-go) with [valid credentials](/scaleway-sdk/go-sdk/)
+- [Created a Key Manager key](/key-manager/how-to/create-km-key)
+
+
+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.
+
+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.
+To use Tink with Scaleway Key Manager, you need to install dependencies that let Tink interact with Key Manager.
+
+
+## Setting up environment variables
+
+Open a terminal and export the following environment variables. Make sure that you replace the placeholder values with your own.
+
+  ```bash
+  export SCW_ACCESS_KEY="<access-key>"
+  export SCW_SECRET_KEY="<secret-key>"
+  export SCW_DEFAULT_ORGANIZATION_ID="<organization-id>"
+  export SCW_PROJECT_ID="<project-id>"
+  export SCW_DEFAULT_REGION="<region>"
+  export SCW_API_URL="<api-url>"
+  export SCW_KM_KEY_ID="<key-id>"
+  ```
+
+## Setting up Tink
+
+1. Open a terminal and access your project directory:
+
+    ```shell
+    cd <your-project-directory>
+    ```
+
+2. Initialize a Go module in your project directory:
+    ```shell
+    go mod init <your-project-directory>
+    ```
+
+3. Run the following commands to install the Tink library and the Scaleway Tink Provider for Go:
+
+    ```shell
+    # Install Tink for Go
+    go get -u github.com/tink-crypto/tink-go/v2
+
+    # Install the Scaleway Tink extension
+    go get -u github.com/scaleway/tink-go-scwkms
+    go mod tidy
+    ```
+
+## Configuring Tink
+
+In order to use Tink for data encryption, you need to provide it with a key URI and a configuration file:
+
+- The key URI points to your key encryption key (KEK) in Scaleway Key Manager.
+
+- The configuration file grants Tink the necessary permissions to access and use the KEK identified by the Key URI.
+
+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.
+
+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.
+
+Scaleway supports the **Go Tink provider**.
+
+1. [Retrieve the ID](/key-manager/how-to/retrieve-km-key-id) (UUIDv4 format) of your Key Manager's key (KEK).
+2. Copy the following template and paste it into a `.go` file:
+
+    ```go
+    import (
+        "github.com/scaleway/scaleway-sdk-go/scw" //  Library that helps your Go program interact with Scaleway
+        "github.com/tink-crypto/tink-go/v2/aead" // Tink library
+        "github.com/scaleway/tink-go-scwkms/integration/scwkms" // Scaleway's Tink extension
+    )
+
+    const region = "<REGION>"                              // Replace the placeholder with the region where your key is created
+    const keyID = "7f967268-bebb-43b0-9fe2-e13bd23bf421" // Replace the placeholder with the unique ID of your key encryption key
+
+    keyURIPrefix := "scw-kms://regions/" + region + "/keys/"
+    keyURI := keyURIPrefix + keyID
+
+    // Set up a connection to Scaleway
+    config, _ := scw.LoadConfig() // Loads your Scaleway configuration
+    profile, _ := config.GetActiveProfile() // Gets the active profile (your account settings)
+
+    // Set up the connection to use your key in Key Manager
+    kms, _ := scwkms.NewClientWithOptions(
+        keyURIPrefix,
+        scw.WithProfile(profile), // Uses your account profile
+        scw.WithEnv(), // Uses environment settings
+    )
+    // Prepare the key for encryption and decryption
+    kekAEAD, _ := kms.GetAEAD(keyURI)
+    ```
+3. Replace the placeholder values with your own.
+
+    <Message type="note">
+     The `kekAEAD` object represents the key in Scaleway’s Key Manager. It allows you to encrypt payloads and decrypt ciphertexts.
+    </Message>
+
+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

@@ -0,0 +1,76 @@
+---
+meta:
+  title: Creating a data encryption key using the Scaleway API and the Scaleway CLI
+  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.
+content:
+  h1: Creating a data encryption key using the Scaleway API and the Scaleway CLI
+  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.
+tags: key-management dek data-encryption-key cli sdk api encryption
+dates:
+  validation: 2025-02-06
+  posted: 2025-02-06
+---
+
+<Macro id="requirements" />
+
+- A Scaleway account logged into the [console](https://console.scaleway.com)
+- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization
+- 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)
+- Retrieved your key encryption key's ID
+- Created an [API key](/iam/how-to/create-api-keys/)
+- Downloaded and configured the [Scaleway CLI](https://github.com/scaleway/scaleway-cli?tab=readme-ov-file#getting-started)
+
+## Generate a DEK using the Scaleway CLI
+
+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.
+        ```bash
+        export SCW_ACCESS_KEY=<SCALEWAY_API_ACCESS_KEY>
+        export SCW_SECRET_KEY=<SCALEWAY_API_SECRET_KEY>
+        export SCW_DEFAULT_ORGANIZATION_ID=<SCALEWAY_ORGANIZATION_ID>
+        export SCW_PROJECT_ID=<SCALEWAY_PROJECT_ID>
+        export SCW_DEFAULT_REGION="fr-par"
+        export SCW_API_URL="https://api.scaleway.com"
+        ```
+
+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.
+        ```bash
+        scw keymanager key generate-data-key key-id=<your_kek_id> algorithm=aes_256_gcm
+        ```
+
+An output similar to the following should display:
+        ```bash
+        KeyID       <kek_id>
+        Algorithm   <algorithm_used_to_encrypt_your_key>
+        Ciphertext  <your_base64_encrypted_dek>
+        Plaintext   <your_base64_decrypted_dek>
+        CreatedAt   <creation_date>
+        ```
+
+    <Message type="important">
+     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.
+    </Message>
+
+## Generate a DEK using the API
+
+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.
+        ```bash
+        curl --location 'https://api.scaleway.com/key-manager/v1alpha1/regions/fr-par/keys/<your_key_id>/generate-data-key' \
+        --header 'Content-Type: application/json' \
+        --header 'X-Auth-Token: <your_secret_key>' \
+        --data '{
+            "algorithm": "aes_256_gcm"
+        }'
+        ```
+
+Key Manager also supports the `GenerateDataKey` request without a plaintext operation, which only returns an encrypted data encryption key.
+
+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.
+
+**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**.
+
+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/).
+
+    <Message type="important">
+    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.
+    **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.**
+    </Message>