From 3fe09a6cdb6e9df297b55b8b8efc66fabde1a3a9 Mon Sep 17 00:00:00 2001 From: nerda-codes Date: Thu, 6 Feb 2025 10:38:52 +0100 Subject: [PATCH] docs(key-manager): last tweaks --- menu/navigation.json | 6 +-- .../key-manager/api-cli/configuring-tink.mdx | 14 +++---- .../encrypt-decrypt-data-with-km-dek.mdx | 37 ++++++++++--------- .../api-cli/manage-keys-with-tink.mdx | 17 +++++---- .../api-cli/rotate-keys-api-cli.mdx | 16 ++++---- pages/key-manager/concepts.mdx | 4 +- .../key-manager/how-to/create-manage-dek.mdx | 2 +- .../key-manager/how-to/retrieve-km-key-id.mdx | 9 +++-- pages/key-manager/how-to/rotate-kem-keys.mdx | 8 ++-- .../differences-key-and-secret-manager.mdx | 4 +- .../understanding-key-manager.mdx | 2 +- 11 files changed, 62 insertions(+), 57 deletions(-) diff --git a/menu/navigation.json b/menu/navigation.json index e4ca5fddda..f32f452d78 100644 --- a/menu/navigation.json +++ b/menu/navigation.json @@ -632,7 +632,7 @@ "slug": "create-manage-dek" }, { - "label": "Perform key rotation on Key Manager keys", + "label": "Rotate Key Manager keys", "slug": "rotate-km-keys" }, { @@ -676,7 +676,7 @@ "slug": "create-dek-api-cli" }, { - "label": "Setting up Tink", + "label": "Setting up and configuring Tink", "slug": "configuring-tink" }, { @@ -684,7 +684,7 @@ "slug": "manage-keys-with-tink" }, { - "label": "Perform key rotation using the Scaleway CLI and API", + "label": "Rotate keys using the Scaleway CLI and API", "slug": "rotate-keys-api-cli" }, { diff --git a/pages/key-manager/api-cli/configuring-tink.mdx b/pages/key-manager/api-cli/configuring-tink.mdx index 415a0d6a2b..fd261f349e 100644 --- a/pages/key-manager/api-cli/configuring-tink.mdx +++ b/pages/key-manager/api-cli/configuring-tink.mdx @@ -1,9 +1,9 @@ --- meta: - title: Configuring Tink + 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: Configuring Tink + 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: @@ -11,7 +11,7 @@ dates: posted: 2025-02-03 --- -This page shows you how to configure Tink for encrypting and decrypting data with Scaleway's Key Manager. +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. @@ -48,9 +48,9 @@ Open a terminal and export the following environment variables. Make sure that y 1. Open a terminal and access your project directory: - ```shell - cd - ``` + ```shell + cd + ``` 2. Initialize a Go module in your project directory: ```shell @@ -117,4 +117,4 @@ Scaleway supports the **Go Tink provider**. The `kekAEAD` object represents the key in Scaleway’s Key Manager. It allows you to encrypt payloads and decrypt ciphertexts. -Find out how to encrypt and decrypt data with Tink in the dedicated documentation. \ No newline at end of file +Find out how to encrypt and decrypt data with Tink in the [dedicated documentation](/key-manager/api-cli/encrypt-decrypt-data-with-km-dek/). \ No newline at end of file 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 index 1675b0fd13..8218e09cfa 100644 --- 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 @@ -132,20 +132,21 @@ To encrypt your data using OpenSSl, you need to: 3. Encrypt the content of `plaintext.txt` using OpenSSL and the `AES-256-CBC` cipher encryption algorithm. -Open a terminal and paste the following command to perform the actions described above. Make sure that you replace `` and `` with the relevant values. -```bash -# Decrypt the encrypted DEK using scw key decrypt -decrypted_data_key=$(scw keymanager key decrypt key-id= ciphertext= | awk '$1 == "Plaintext" {print $2}' | base64 -d) +4. Open a terminal and paste the following command to perform the actions described above. Make sure that you replace `` and `` with the relevant values. -# Put your data plaintext into a .txt file -echo -n "Your plaintext here" > plaintext.txt + ```bash + # Decrypt the encrypted DEK using scw key decrypt + decrypted_data_key=$(scw keymanager key decrypt key-id= ciphertext= | awk '$1 == "Plaintext" {print $2}' | base64 -d) -# Encrypt your file using OpenSSL and AES-256-CBC -openssl enc -aes-256-cbc -in plaintext.txt -out encrypted.bin -K $(echo -n "$decrypted_data_key" | hexdump -ve '/1 "%02x"') -iv 0 -nosalt -p + # Put your data plaintext into a .txt file + echo -n "Your plaintext here" > plaintext.txt -# Remove the plaintext data -rm plaintext.txt -``` + # Encrypt your file using OpenSSL and AES-256-CBC + openssl enc -aes-256-cbc -in plaintext.txt -out encrypted.bin -K $(echo -n "$decrypted_data_key" | hexdump -ve '/1 "%02x"') -iv 0 -nosalt -p + + # Remove the plaintext data + rm plaintext.txt + ``` ### Decrypting data with OpenSSL @@ -155,14 +156,14 @@ To decrypt your encrypted data using OpenSSL, you need to: 2. Decrypt the content of `encrypted.bin` which contains your encrypted data, using OpenSSL and the `AES-256-CBC` cipher encryption algorithm. -Open a terminal and paste the following command to perform the actions described above. Make sure that you replace `` and `` with the relevant values. -```bash - # Decrypt the encrypted DEK using scw key decrypt - decrypted_data_key=$(scw keymanager key decrypt key-id= ciphertext= | awk '$1 == "Plaintext" {print $2}' | base64 -d) +3. Open a terminal and paste the following command to perform the actions described above. Make sure that you replace `` and `` with the relevant values. + ```bash + # Decrypt the encrypted DEK using scw key decrypt + decrypted_data_key=$(scw keymanager key decrypt key-id= ciphertext= | awk '$1 == "Plaintext" {print $2}' | base64 -d) - # Decrypt your data using OpenSSL and AES-256-CBC - openssl enc -aes-256-cbc -d -in encrypted.bin -out decrypted.bin -K $(echo -n "$decrypted_data_key" | hexdump -ve '/1 "%02x"') -iv 0 -nosalt -p -``` + # Decrypt your data using OpenSSL and AES-256-CBC + openssl enc -aes-256-cbc -d -in encrypted.bin -out decrypted.bin -K $(echo -n "$decrypted_data_key" | hexdump -ve '/1 "%02x"') -iv 0 -nosalt -p + ``` 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. diff --git a/pages/key-manager/api-cli/manage-keys-with-tink.mdx b/pages/key-manager/api-cli/manage-keys-with-tink.mdx index 2e2d222ffc..7805b1b000 100644 --- a/pages/key-manager/api-cli/manage-keys-with-tink.mdx +++ b/pages/key-manager/api-cli/manage-keys-with-tink.mdx @@ -25,22 +25,23 @@ This documentation page provides information on Key Manager Key Encryption Keys ## Encrypting and decrypting data with Tink -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. +Paste the following code into a `.go` file. This template contains an example of 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 + associatedData := []byte("") // Refer to the the ##Associated data section below for more information + secretData := []byte("Hello, World!") // Defines secretData as the plaintext message ("Hello, World!") we want to encrypt - ciphertext, _ := kekAEAD.Encrypt(secretData, associatedData) // Encrypt the data - fmt.Println(ciphertext) // Print the encrypted data + ciphertext, _ := kekAEAD.Encrypt(secretData, associatedData) // Encrypts the data, the result is stored in ciphertext + fmt.Println(ciphertext) // Prints the encrypted data ("Hello, World!" as unreadable bytes) - plaintext, _ := kekAEAD.Decrypt([]byte(ciphertext), associatedData) - fmt.Println(string(plaintext)) // Output: "Hello, World!" + plaintext, _ := kekAEAD.Decrypt([]byte(ciphertext), associatedData) // Decrypts the data, turning the ciphertext back into the original secretData + fmt.Println(string(plaintext)) // Converts the decrypted unreadable bytes back to a string and prints "Hello, World!" ``` 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`. + - The payload to encrypt is limited in size: Key Manager only allows up to 64 KB. 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. diff --git a/pages/key-manager/api-cli/rotate-keys-api-cli.mdx b/pages/key-manager/api-cli/rotate-keys-api-cli.mdx index 0b813634ee..88e0975ca6 100644 --- a/pages/key-manager/api-cli/rotate-keys-api-cli.mdx +++ b/pages/key-manager/api-cli/rotate-keys-api-cli.mdx @@ -1,17 +1,17 @@ --- meta: -title: Perform key rotation using the Scaleway CLI and API -description: Learn why key rotation enhances security and how to configure automated or manual key rotation in Scaleway's Key Manager. + title: Rotate keys using the Scaleway CLI and API + description: Learn why key rotation enhances security and how to configure automated or manual key rotation in Scaleway's Key Manager. content: -h1: Perform key rotation using the Scaleway CLI and API -paragraph: Learn why key rotation enhances security and how to configure automated or manual key rotation in Scaleway's Key Manager. -tags: key sensitive-data rotation + h1: Rotate keys using the Scaleway CLI and API + paragraph: Learn why key rotation enhances security and how to configure automated or manual key rotation in Scaleway's Key Manager. +tags: key sensitive-data rotation versioning dates: validation: 2025-02-03 posted: 2025-02-03 --- -Key rotation is a critical security practice that ensures that encryption keys are not reused for extended periods of time. Regularly rotating keys helps limit the number of messages encrypted with the same key version. +[Key rotation](/key-manager/concepts/#key-rotation) is a critical security practice that ensures that encryption keys are not reused for extended periods of time. Regularly rotating keys helps limit the number of messages encrypted with the same key version. 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. @@ -69,7 +69,7 @@ Copy the following command to configure automatic rotation when creating a key: - **rotation_period:** duration between two key rotations (min: 24 hours, max: 100 years). - **next_rotation_at:** date at which the key will be rotated next. -To configure automatic rotation on an existing key, use the `UpdateKey` endpoint as follows: +To configure automatic rotation on an existing key, use the `UpdateKey` [endpoint](https://www.scaleway.com/en/developers/api/key-manager/#path-keys-update-a-key) as follows: ``` curl -X PATCH 'https://api.scaleway.com/key-manager/v1alpha1/regions/fr-par/keys/' \ @@ -85,7 +85,7 @@ To configure automatic rotation on an existing key, use the `UpdateKey` endpoint ## Manually rotate your key -To rotate your key manually, you can use the `RotateKey` endpoint as follows: +To rotate your key manually, you can use the `RotateKey` [endpoint](https://www.scaleway.com/en/developers/api/key-manager/#path-keys-rotate-a-key) as follows: ``` curl -X POST 'https://api.scaleway.com/key-manager/v1alpha1/regions/fr-par/keys//rotate' \ diff --git a/pages/key-manager/concepts.mdx b/pages/key-manager/concepts.mdx index 8261550bef..1a35c67307 100644 --- a/pages/key-manager/concepts.mdx +++ b/pages/key-manager/concepts.mdx @@ -45,13 +45,13 @@ A data encryption key is a type of key that can be used outside Key Manager to e Key Manager generates DEKs on-demand. They are then encrypted by a [key encryption key](#key-encryption-key-kek) specified by the user, and forwarded to the recipient. -DEKs are **not stored in or managed by Key Manager**. Users are responsible for safely storing and managing DEKs. DEKs should have the same lifecycle as the [payload](#payload) they encrypt**. +DEKs are **not stored in or managed by Key Manager**. Users are responsible for safely storing and managing DEKs. DEKs should have the same lifecycle as the [payload](#payload) they encrypt. ## Decryption A cryptographic operation used to convert [ciphertext](#ciphertext) back into its original [plaintext](#plaintext) form, using a key encryption key. -The only way to decrypt an encrypted payload is by using the `Decrypt` [endpoint](https://www.scaleway.com/en/developers/api/key-manager/V1/#path-keys-decrypt-keys). Since key versions never leave Key Manager, there is no other way to decrypt data outside Key Manager.** A payload encrypted with an older key version can still be decrypted. In this case, for convenience, the payload encrypted with the latest key version will be returned, along with the decrypted payload. +The only way to decrypt an encrypted payload is by using the `Decrypt` [endpoint](https://www.scaleway.com/en/developers/api/key-manager/V1/#path-keys-decrypt-data). Since key versions never leave Key Manager, there is no other way to decrypt data outside Key Manager. A payload encrypted with an older key version can still be decrypted. In this case, for convenience, the payload encrypted with the latest key version will be returned, along with the decrypted payload. ## Encryption diff --git a/pages/key-manager/how-to/create-manage-dek.mdx b/pages/key-manager/how-to/create-manage-dek.mdx index 505d996385..8020fb1925 100644 --- a/pages/key-manager/how-to/create-manage-dek.mdx +++ b/pages/key-manager/how-to/create-manage-dek.mdx @@ -38,5 +38,5 @@ You can then use your Key Manager key to encrypt your DEK. - Read our [documentation](/key-manager/reference-content/understanding-key-manager/) to understand Key Manager. 6. Optionally, click **Display plaintext** to make sure that the plaintext does not contain any mistakes. - + 7. Click **Close**. diff --git a/pages/key-manager/how-to/retrieve-km-key-id.mdx b/pages/key-manager/how-to/retrieve-km-key-id.mdx index ebfcf8cfd1..56c5d07a7b 100644 --- a/pages/key-manager/how-to/retrieve-km-key-id.mdx +++ b/pages/key-manager/how-to/retrieve-km-key-id.mdx @@ -7,16 +7,19 @@ content: paragraph: Discover how to retrieve the ID of a Key Manager key from the Scaleway console to encrypt your data. tags: key-manager key-id dates: - validation: 2025-02-03 - posted: 2025-02-03 + validation: 2025-02-06 + posted: 2025-02-06 --- This page shows you how to retrieve the ID of your Key Manager key to encrypt data. +- 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](/key-manager/how-to/create-km-key/) a Key Manager key ## How to retrieve the ID of a Key Manager key 1. Click **Key Manager** in the **Security and Identity section** of the [Scaleway console](https://console.scaleway.com) side menu. 2. Click next to the key of which you wish to retrieve the ID. The key's **Overview** page displays. -3. Click **Copy key ID**. \ No newline at end of file +3. Click **Copy key ID**. The ID of your key is copied. \ No newline at end of file diff --git a/pages/key-manager/how-to/rotate-kem-keys.mdx b/pages/key-manager/how-to/rotate-kem-keys.mdx index eec44ec67f..bbe0ce969d 100644 --- a/pages/key-manager/how-to/rotate-kem-keys.mdx +++ b/pages/key-manager/how-to/rotate-kem-keys.mdx @@ -1,11 +1,11 @@ --- meta: - title: Perform key rotation using the Scaleway console + title: Rotate keys using the Scaleway console description: Discover how to rotate a key from the Scaleway console to decrypt your data using Scaleway's Key Manager. content: - h1: Perform key rotation using the Scaleway console + h1: Rotate keys using the Scaleway console paragraph: Discover how to rotate a key from the Scaleway console to decrypt your data using Scaleway's Key Manager. -tags: key-manager encryption data key +tags: key-manager rotation key-version dates: validation: 2025-02-03 posted: 2025-02-03 @@ -21,7 +21,7 @@ This reduces the risk of exposure if a key is compromised, thus enhancing the ov - [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization - [Created](/key-manager/how-to/create-km-key/) a Key Manager key -## How to perform key rotation +## How to rotate keys 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 you want to rotate. Your key's **Overview** tab displays. 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 index 16cd8c5267..94703556ad 100644 --- a/pages/key-manager/reference-content/differences-key-and-secret-manager.mdx +++ b/pages/key-manager/reference-content/differences-key-and-secret-manager.mdx @@ -1,9 +1,9 @@ --- meta: - title: Understanding the difference between Key Manager and Secret Manager + title: Differences between Key Manager and Secret Manager description: Discover the differences between Secret Manager and Key Manager, and learn which security tool best fits your data protection needs. content: - h1: Understanding the difference between Key Manager and Secret Manager + h1: Differences between Key Manager and Secret Manager paragraph: Discover the differences between Secret Manager and Key Manager, and learn which security tool best fits your data protection needs. tags: key-manager secret-manager security dates: diff --git a/pages/key-manager/reference-content/understanding-key-manager.mdx b/pages/key-manager/reference-content/understanding-key-manager.mdx index e28bee3562..7f68dfde68 100644 --- a/pages/key-manager/reference-content/understanding-key-manager.mdx +++ b/pages/key-manager/reference-content/understanding-key-manager.mdx @@ -13,7 +13,7 @@ dates: ## How to use Key Manager? -We recommend using the keys you store in Key Manager as [key encryption keys (KEK)](/key-manager/concepts/#key-encryption-key-kek), and use them to encrypt and decrypt your [data encryption keys (DEK)](/identity-and-access-management/key-manager/concepts/#data-encryption-key-dek). We do not recommend storing your data encryption keys in Key Manager. +We recommend using the keys you store in Key Manager as [key encryption keys (KEK)](/key-manager/concepts/#key-encryption-key-kek), and use them to encrypt and decrypt your [data encryption keys (DEK)](/key-manager/concepts/#data-encryption-key-dek). We do not recommend storing your data encryption keys in Key Manager.