docs(key-manager): apply suggestions from code review

nerda-codes · jcirinosclwy · web-flow · commit 86aa8c7462f0 · 2025-02-05T16:17:13.000+01:00
Co-authored-by: Jessica &lt;113192637+jcirinosclwy@users.noreply.github.com&gt;
diff --git a/pages/key-manager/api-cli/configuring-tink.mdx b/pages/key-manager/api-cli/configuring-tink.mdx
@@ -24,9 +24,9 @@ We recommend using Tink with Scaleway’s Key Manager, especially for Go-based a
 - [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.
+
+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.
 
 
diff --git a/pages/key-manager/api-cli/create-dek-api-cli.mdx b/pages/key-manager/api-cli/create-dek-api-cli.mdx
@@ -72,5 +72,5 @@ However, you can use the DEK independently from Key Manager, for example with th
 
     <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.**
+    **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>
diff --git a/pages/key-manager/api-cli/encrypt-decrypt-data-with-km-dek.mdx b/pages/key-manager/api-cli/encrypt-decrypt-data-with-km-dek.mdx
@@ -118,11 +118,10 @@ To decrypt or encrypt your data using OpenSSL, you need to send your encrypted D
 Scaleway Key Manager then uses your key encryption key (KEK) to decrypt the encrypted DEK, returning it to its plaintext (unencrypted) form, which you can then use to decrypt your actual data.
 
 <Message type="important">
- - **We do not recommend that you use OpenSSL in a production environment**.
+ - **We do not recommend using OpenSSL in a production environment**.
  - You should **never save the plaintext DEK on disk or any permanent storage, as it poses a security risk**.
 </Message>
 
-
 ### Encrypting data with OpenSSL
 
 To encrypt your data using OpenSSl, you need to:
@@ -180,7 +179,7 @@ Open a terminal and paste the following command to perform the actions described
 2. Use your newly created DEK to encrypt the desired plaintext securely.
 
         <Message type="note">
-         We recommend using **standard and well-established ciphers** such as `AES` (Advanced Encryption Standard), to perform the encryption operation.
+         We recommend using **standard and well-established ciphers**, such as `AES` (Advanced Encryption Standard), to perform the encryption operation.
         </Message>
 
 3. After encrypting the plaintext using your DEK, concatenate the encrypted DEK with the resulting ciphertext. This ensures that the encrypted DEK is securely associated with the corresponding ciphertext for decryption.
diff --git a/pages/key-manager/api-cli/encrypt-decrypt-keys-with-streaming-aead-tink.mdx b/pages/key-manager/api-cli/encrypt-decrypt-keys-with-streaming-aead-tink.mdx
@@ -11,7 +11,7 @@ dates:
   posted: 2025-02-03
 ---
 
-This page shows you how to use Scaleway Key Manager with Tink to securely handle large data streams. Specifically, it uses AEAD, which ensures both encryption and authentication of data, along with associated data (like file paths) that is authenticated but not encrypted. This is important for handling large files efficiently, especially in cases where stream processing is necessary (such as video files or large logs).
+This page shows you how to use Scaleway Key Manager with Tink to securely handle large data streams. Specifically, it uses AEAD, which ensures both encryption and authentication of data, along with associated data (like file paths) that is authenticated but not encrypted. This is important for handling large files efficiently, especially in cases where stream processing is necessary, such as video files or large logs.
 
 Tink is a multi-language cryptographic library that simplifies common cryptographic operations like encryption, decryption, signing, and more. It provides cryptographic primitives, including AEAD.
 
@@ -48,7 +48,6 @@ Open a terminal and paste the following commands to export your environment vari
 
 ## Encrypting and decrypting large data streams using AEAD
 
-
 1. Paste the following code into a Go file:
 
     ```
@@ -189,7 +188,7 @@ Open a terminal and paste the following commands to export your environment vari
     ```
     <Message type="note">
      - The example above shows you how to use the Key Manager remote key encryption key to protect your data encryption key and AEAD stream, you can also protect the data encryption key using another non-remote key.
-     - Associated data is authenticated but not encrypted
+     - Associated data is authenticated but not encrypted.
     </Message>
 
 2. Save your changes.
diff --git a/pages/key-manager/api-cli/manage-keys-with-tink.mdx b/pages/key-manager/api-cli/manage-keys-with-tink.mdx
@@ -38,7 +38,7 @@ Paste the following code into a `.go` file. This template contains the data we w
     ```
 
 <Message type="important">
- While the code shown above functions as intended, this is not a recommended pattern and the following limitations apply:
+ While the code shown above functions as intended, this is not a recommended pattern, and the following limitations apply:
   - It is slow: since the key resides on Scaleway Key Manager, each encryption or decryption operation translates into a remote API call.
   - The payload to encrypt is limited in size: Key Manager only allows up to 64 KiB. As a result, you will not be able to encrypt larger payloads with `kekAEAD`.
   - You cannot choose the cipher and the algorithm that suit your use case, Key Manager handles that on your behalf.
@@ -123,7 +123,7 @@ Tink does not handle single keys, it manages groups of keys called **keysets**,
     encDEK := buf.Bytes()  // encrypted DEK in Tink wire format
     ```
 
-You can then store the bytes of the encrypted DEK in a database for example, with the encrypted data it protects. For example, the encrypted data (enc_data) and the encrypted DEK (enc_dek) might be stored together in a row in a database (base64-encoded in the following example):
+You can then store the bytes of the encrypted DEK in a database, for example, with the encrypted data it protects. For example, the encrypted data (enc_data) and the encrypted DEK (enc_dek) might be stored together in a row in a database (base64-encoded in the following example):
 
     ```console
     SELECT id, enc_data, enc_dek FROM sensible_stuff;
@@ -137,7 +137,6 @@ You can then store the bytes of the encrypted DEK in a database for example, wit
     ...
     ```
 
-
 ## Associated Data
 
 Associated Data (AD) is not encrypted, but it is authenticated. It must be the same when you encrypt and decrypt data, otherwise the decryption fails. This is useful to prevent reading the wrong data in the wrong context. In the table above, the data in both rows 42 and 43 is protected by the same DEK. If we swapped the data, an application would be able to decrypt the data from another row. But, by providing the intended ID as the associated data, the decryption would fail.
@@ -159,7 +158,6 @@ Run the following command to encrypt your data with `Associated Data`. In the ex
 
 Associated Data does not need to be stored, as it can be inferred from the context at decryption time. It is also possible to use a unique DEK for each payload. We recommend using Associated Data.
 
-
 ## Hierarchy of keys
 
 Unlike KEKs that reside and are managed by Key Manager, DEKs are free: you can generate and have as many as you want.
diff --git a/pages/key-manager/api-cli/rotate-keys-api-cli.mdx b/pages/key-manager/api-cli/rotate-keys-api-cli.mdx
@@ -15,7 +15,7 @@ Key rotation is a critical security practice that ensures that encryption keys a
 
 This reduces the risk of exposure if a key is compromised, thus enhancing the overall security and resilience of your system. For symmetric encryption, it is generally recommended to rotate keys every 30 to 90 days.
 
-However, this may vary based on your specific use-case and risk profile.
+However, this may vary based on your specific use case and risk profile.
 
 <Message type="important">
     Rotating a key will not re-encrypt your data encryption key or any data you may have encrypted. When performing a
@@ -26,7 +26,7 @@ However, this may vary based on your specific use-case and risk profile.
 
 ## Why is key rotation recommended?
 
-Key rotation offers several important advantages such as:
+Key rotation offers several important advantages, such as:
 
 - **Mitigating cryptanalysis attacks:** Limiting the amount of messages encrypted with the same key version reduces the risk of
 cryptanalysis attacks. The recommended key lifetime varies depending on the key algorithm, the number of messages, and
diff --git a/pages/key-manager/concepts.mdx b/pages/key-manager/concepts.mdx
@@ -37,7 +37,6 @@ Key Manager supports the three following cryptographic operations:
 - [Decryption](#decryption)
 - [Data encryption key](#data-encryption-key-dek) generation
 
-
 These operations are designed to protect data from unauthorized access, ensure its integrity, and verify the identities of users or systems.
 
 ## Data encryption key (DEK)
@@ -86,7 +85,7 @@ Key Manager only supports symmetric encryption.
 
 ## Encryption scheme
 
-An encryption scheme is a structured approach to encryption that specifies the encryption algorithm, key size, and mode of operation for block chiphers.
+An encryption scheme is a structured approach to encryption that specifies the encryption algorithm, key size, and mode of operation for block ciphers.
 
 For example, in the `AES-256-GCM` encryption scheme:
 
diff --git a/pages/key-manager/how-to/create-manage-dek.mdx b/pages/key-manager/how-to/create-manage-dek.mdx
@@ -10,6 +10,7 @@ dates:
   validation: 2025-02-03
   posted: 2025-02-03
 ---
+
 Scaleway's key Manager allows you to create [data encryption keys (DEK)](/key-manager/concepts/#data-encryption-key-dek) to encrypt and decrypt your [payload](/key-manager/concepts/#payload).
 
 You can then use your Key Manager key to encrypt your DEK.
diff --git a/pages/key-manager/how-to/disable-km-keys.mdx b/pages/key-manager/how-to/disable-km-keys.mdx
@@ -13,7 +13,6 @@ dates:
 
 This page shows you how to disable a Key Manager key which is enabled by default. Disabling a key renders it unusable for cryptographic operations by any user and application.
 
-
 <Macro id="requirements" />
 
 - A Scaleway account logged into the [console](https://console.scaleway.com)
@@ -29,4 +28,3 @@ This page shows you how to disable a Key Manager key which is enabled by default
      Your key might be used by third-party programs. Disabling it could cause your services to stop working. You can enable your key again anytime.
     </Message>
 4. Click **Disable key** to confirm.
-
diff --git a/pages/key-manager/quickstart.mdx b/pages/key-manager/quickstart.mdx
@@ -36,7 +36,6 @@ Scaleway's Key Manager allows you to create key encryption keys from the [Scalew
 
 ## How to create and manage a data encryption key (DEK)
 
-
 1. Click Key Manager in the **Security and Identity section** of the [Scaleway console](https://console.scaleway.com) side menu. Your keys display.
 2. Click the key for which to create a data encryption key.
 3. Scroll down to the **Create data encryption key** section.
diff --git a/pages/key-manager/reference-content/differences-key-and-secret-manager.mdx b/pages/key-manager/reference-content/differences-key-and-secret-manager.mdx
@@ -16,13 +16,12 @@ The difference between the two of them is not always clear, and you may be unsur
 
 This page helps you answer that question.
 
-
 ## Secret Manager
 
 Secret Manager stores various secrets that your applications might need to access at some point. For example, when your application needs to call an external API service or connect to a database, it fetches the API token
 or the credentials from Secret Manager before proceeding.
 
-Secrets can be largely anything you want: API tokens, credentials to connect to a database or simply sensitive data. There are no limits, other than the size of the secrets which is limited to 64 KiB.
+Secrets can be largely anything you want: API tokens, credentials to connect to a database, or simply sensitive data. There are no limits, other than the size of the secrets which is limited to 64 KiB.
 
 
 ## Key Manager
diff --git a/pages/key-manager/reference-content/security-recommendations.mdx b/pages/key-manager/reference-content/security-recommendations.mdx
@@ -19,12 +19,10 @@ We strongly advise that you **never store [data encryption keys (DEKs)](/key-man
 
 You should always use your [key encryption key (KEK)](/key-manager/concepts/#key-encryption-key-kek) [created via Key Manager](/key-manager/how-to/create-km-key/) to encrypt and decrypt your DEKs.
 
-
 ## Key deletion
 
 Always **delete the plaintext version of your DEKs** after use. The key you should use to encrypt your DEKs securely is your KEK.
 
-
 This practice is crucial for **maintaining the security of the encrypted data** by minimizing the time during which the plaintext DEKs are exposed and vulnerable to unauthorized access.
 
 ## Use DEKs only once
diff --git a/pages/key-manager/reference-content/understanding-key-manager.mdx b/pages/key-manager/reference-content/understanding-key-manager.mdx
@@ -80,7 +80,7 @@ Keys with a key usage set to `symmetric_encryption` are **used to encrypt and de
 
 <Macro id="key-manager-encryption" />
 
-The following parameters, in compliance with the [recommendations the French Cybersecurity Agency (ANSSI)](https://cyber.gouv.fr/publications/mecanismes-cryptographiques), are used when creating and using a key with the `AES-256 GCM` [encryption scheme](/key-manager/concepts/#encryption-scheme).
+The following parameters, in compliance with the [recommendations of the French Cybersecurity Agency (ANSSI)](https://cyber.gouv.fr/publications/mecanismes-cryptographiques), are used when creating and using a key with the `AES-256 GCM` [encryption scheme](/key-manager/concepts/#encryption-scheme).
 
 ### Key derivation algorithm
 
