docs(k-m): update

faq/key-manager.mdx

@@ -16,7 +16,7 @@ Key Manager helps organizations achieve secure key management by handling low-le
 
 ## 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.
+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?
 

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/navigation.json

@@ -623,6 +623,10 @@
                     "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"
@@ -654,7 +658,7 @@
                     "slug": "understanding-key-manager"
                   },
                   {
-                    "label": "Understanding the difference between Key Manager and Secret Manager",
+                    "label": "Differences between Key Manager and Secret Manager",
                     "slug": "differences-key-and-secret-manager"
                   }
                 ],

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

@@ -21,24 +21,14 @@ We recommend using Tink with Scaleway’s Key Manager, especially for Go-based a
 - [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)
 
 
 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
 
@@ -54,14 +44,20 @@ Open a terminal and export the following environment variables. Make sure that y
   export SCW_KM_KEY_ID="<key-id>"
   ```
 
-## Installing the necessary dependencies
+## Setting up Tink
+
+1. Open a terminal and access your project directory:
 
-1. Open a terminal and initialize a Go module in your project directory:
+  ```shell
+  cd <your-project-directory>
+  ```
+
+2. 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:
+3. Run the following commands to install the Tink library and the Scaleway Tink Provider for Go:
 
     ```shell
     # Install Tink for Go
@@ -71,5 +67,54 @@ Open a terminal and export the following environment variables. Make sure that y
     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).
+
+## 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.

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

@@ -66,13 +66,11 @@ Key Manager also supports the `GenerateDataKey` request without a plaintext oper
 
 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**.
+**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](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>
-
-
+    </Message>

pages/key-manager/api-cli/encrypt-decrypt-data-with-km-dek.mdx

@@ -23,8 +23,7 @@ This page shows you how to encrypt and decrypt data using your Key Manager [data
 - Downloaded and configured the [Scaleway CLI](https://github.com/scaleway/scaleway-cli?tab=readme-ov-file#getting-started)
 - Dowloaded and installed [Go](https://go.dev/doc/install)
 - [Created a Key Manager data encryption key](/key-manager/how-to/create-manage-dek/)
-
-
+- [Created](/key-manager/how-to/create-km-key) and [retrieved the ID](/key-manager/how-to/retrieve-km-key-id) your Key Manager key
 
 ### Configuring your environment variables
 
@@ -41,31 +40,15 @@ Open a terminal and paste the following command to export your environment varia
     export SCW_KM_KEY_ID="<key-id>"
 ```
 
-
 ### Using the Go Tink provider
 
-1. Open a terminal and navigate to your project directory, and initialize a Go module:
-
-    ```bash
-    go mod init <your-project-directory>
-    ```
+1. [Set up Tink](/key-manager/api-cli/configuring-tink/#setting-up-tink).
 
-2. Add the [Scaleway Tink provider for Go](https://github.com/scaleway/tink-go-scwkms/tree/main) to your `go.mod` file.
-
-    ```bash
-    go get github.com/scaleway/tink-go-scwkms
-    ```
-
-3. Add the Tink library for Go to your `go.mod` file:
-    ```bash
-    go get github.com/tink-crypto/tink-go/v2
-    go mod tidy
-    ```
     <Message type="note">
      The Tink library for Go is a cryptographic library that simplifies encryption, decryption, and key management operations.
     </Message>
-4. Create a Go project with a `test.go` file in it.
-5. Copy the following code.
+2. Create a `test.go` file in your Go project.
+3. Copy and paste the following code in your `test.go` file.
     ```bash
     package main
 
@@ -118,14 +101,12 @@ Open a terminal and paste the following command to export your environment varia
         fmt.Printf("Decrypted ciphertext: %s\n", decryptedCiphertext)
     }
     ```
-6. Paste the code from the step above in your `test.go` file.
-7. Replace `<region>` with the region where your key is located and save your changes.
-8. Run your code:
+4. Replace `<region>` with the region where your key is located and save your changes.
+5. Run your code:
     ```bash
     go run test.go
     ```
 
-
 ## Manually encrypt and decrypt data with a Key Manager DEK
 
 ### OpenSSL overview
@@ -144,7 +125,6 @@ Scaleway Key Manager then uses your key encryption key (KEK) to decrypt the encr
 
 ### Encrypting data with OpenSSL
 
-
 To encrypt your data using OpenSSl, you need to:
 
 1. Decrypt your encrypted DEK using your Key Manager key (key encryption key).
@@ -189,7 +169,6 @@ Open a terminal and paste the following command to perform the actions described
  If you do not wish to use OpenSSL to encrypt and decrypt your data encryption key, you can do it manually using the procedure below, which follows best practices.
 </Message>
 
-
 ### Encrypting a DEK manually
 
 1. [Generate one data encryption key](replace-with-link) **for each plaintext you want to encrypt**.
@@ -220,4 +199,4 @@ Open a terminal and paste the following command to perform the actions described
         <Message type="note">
          Use the same cryptographic algorithm and decryption mechanism as the ones you used during the encryption process.
         </Message>
-4. Delete the plaintext DEK from permanent storage after using it to enhance security.
+4. Delete the plaintext DEK from permanent storage after using it to enhance security.

pages/key-manager/api-cli/encrypt-decrypt-keys-with-streaming-aead-tink.mdx

@@ -28,6 +28,7 @@ This page shows you how to use the Key Manager Tink extension to encrypt and dec
 - Created a key encryption key (KEK) in Key Manager
 - A working Go environment
 - Installed the [Scaleway Go SDK](https://github.com/scaleway/scaleway-sdk-go) and created [credentials](/scaleway-sdk/go-sdk/)
+- [Added the necessary dependencies](/key-manager/api-cli/configuring-tink/#setting-up-tink) for your Go project
 
 ## Configuring your environment variables
 
@@ -48,14 +49,7 @@ Open a terminal and paste the following commands to export your environment vari
 ## Encrypting and decrypting large data streams using AEAD
 
 
-1. Open a terminal and add the necessary dependencies for your Go project ([Scaleway Tink provider for Go](https://github.com/scaleway/tink-go-scwkms/tree/main) and Tink):
-
-    ```
-     go get github.com/scaleway/tink-go-scwkms
-     go get github.com/tink-crypto/tink-go/v2
-    ```
-
-2. Create a Go project and paste the following code into a Go file:
+1. Paste the following code into a Go file:
 
     ```
     package main
@@ -198,10 +192,10 @@ Open a terminal and paste the following commands to export your environment vari
      - Associated data is authenticated but not encrypted
     </Message>
 
-3. Save your changes and run the following commands to execute your code:
+2. Save your changes.
+3. Run the following commands to execute your code:
 
     ```
     go mod tidy
     go run test.go
-    ``
-
+    ``

pages/key-manager/api-cli/manage-keys-with-tink.mdx

@@ -20,60 +20,12 @@ This documentation page provides information on Key Manager Key Encryption Keys
 - Created and enabled a data encryption key (DEK) in your Key Manager
 - A working Go environment
 - Installed the [Scaleway Go SDK](https://github.com/scaleway/scaleway-sdk-go) with [valid credentials](/scaleway-sdk/go-sdk/)
+- [Set up and configured Tink](/key-manager/api-cli/configuring-tink/)
 
 
-## Installing the necessary tools
+## Encrypting and decrypting data with Tink
 
-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.
-
-1. Open a terminal and run the following commands:
-
-    ```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
-    ```
-2. Retrieve the ID (UUIDv4 format) of your Key Manager's key (KEK).
-3. 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)
-    ```
-4. 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>
-
-## Encrypting and decrypting data
-
-Paste the following code into a `.go` file. This file contains the data we will encrypt (`"Hello, World!"`), and the code to encrypt and decrypt it.
+Paste the following code into a `.go` file. This template contains the data we will encrypt (`"Hello, World!"`), and the code to encrypt and decrypt it.
     ```go
     associatedData := []byte("") // Read the ## Associated data section for more information
     secretData := []byte("Hello, World!") // Data we want to encrypt
@@ -257,5 +209,4 @@ The example above can work for most use cases. However, there is no "one fits al
 
 <Message type="important">
  Scaleway does not define keys managed by Key Manager (or any other key management service) as DEKs or KEKs. The context in which you use these keys makes them DEKs or KEKs. We usually assume that keys in Key Manager are only used to protect other keys, hence the use of the terms "KEKs" and "DEKs".
-</Message>
-
+</Message>

pages/key-manager/concepts.mdx

@@ -60,7 +60,7 @@ A cryptographic operation used to encrypt data using the latest version of the K
 
 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).
 
-[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)
+[Find out how to encrypt and decrypt payloads using The Scaleway Tink provider](/key-manager/api-cli/manage-keys-with-tink)
 
 ## Encryption algorithm
 
@@ -98,7 +98,7 @@ For example, in the `AES-256-GCM` encryption scheme:
 
 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).
 
-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.
+The KEK is permanently stored in Scaleway's Key Manager and never leaves it. It cannot be accessed by anyone, and should be [rotated](/key-manager/api-cli/rotate-keys-api-cli/) regularly.
 
 ## Key management
 

pages/key-manager/how-to/create-km-key.mdx

@@ -20,7 +20,7 @@ Scaleway's Key Manager allows you to create key encryption keys from the [Scalew
 
 ## How to create a Key Manager key
 
-1. Click Key Manager in the **Security and Identity section** of the [Scaleway console](https://console.scaleway.com) side menu.
+1. Click **Key Manager** in the **Security and Identity section** of the [Scaleway console](https://console.scaleway.com) side menu.
 2. Click **+ Create key**.
 3. Choose the region in which you want to create your key.
 4. Enter a name, a description, and optional tags for your key.