feat(key-manager): add docs

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-03
+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).**

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

@@ -598,6 +598,106 @@
             ],
             "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": "Create and manage a Key Manager data encryption key",
+                    "slug": "create-manage-dek"
+                  },
+                  {
+                    "label": "Perform key rotation on 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": "Understanding the difference 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 Tink",
+                    "slug": "configuring-tink"
+                  },
+                  {
+                    "label": "Managing your Key Manager keys using Tink",
+                    "slug": "manage-keys-with-tink"
+                  },
+                  {
+                    "label": "Perform key rotation 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/key-manager/api-cli/configuring-tink.mdx

@@ -0,0 +1,75 @@
+---
+meta:
+  title: Configuring Tink
+  description: Follow this guide to learn how to configure your environment and dependencies before using Tink in your projects.
+content:
+  h1: 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 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/)
+
+
+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.
+
+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.
+To use Tink with Scaleway Key Manager, you need to install dependencies that let Tink interact with Key Manager.
+
+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**.
+
+## 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>"
+  ```
+
+## Installing the necessary dependencies
+
+1. Open a terminal and initialize a Go module in your project directory:
+    ```shell
+    go mod init <your-project-directory>
+    ```
+
+2. 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
+    ```
+3. Optionally, create a key encryption key (KEK) to start using Key Manager.
+4. Optionally, create a data encryption key (DEK) that will be used for data encryption and decryption. Find out how to create and manage DEKs in the [dedicated documentation](replace-with-link).

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

@@ -0,0 +1,78 @@
+---
+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-03
+  posted: 2025-02-03
+---
+
+<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 64KB in size**.
+
+However, you can use the DEK independently from Key Manager, for example with the [Tink extension](replace-with-link) or with [OpenSSL](replace-with-link).
+
+    <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>
+
+