From 8fb2d234929adeaf4b145a481d3979d5e62ca288 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A9lanie=20Marques?= Date: Mon, 2 Sep 2024 16:00:02 +0200 Subject: [PATCH 1/2] feat(key-manager): add a documentation for key rotation --- .../key-manager/api-cli/key-rotation.mdx | 100 ++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 identity-and-access-management/key-manager/api-cli/key-rotation.mdx diff --git a/identity-and-access-management/key-manager/api-cli/key-rotation.mdx b/identity-and-access-management/key-manager/api-cli/key-rotation.mdx new file mode 100644 index 0000000000..ed0723e43a --- /dev/null +++ b/identity-and-access-management/key-manager/api-cli/key-rotation.mdx @@ -0,0 +1,100 @@ +--- +meta: +title: Key Rotation +description: Find out how to rotate keys, and why you should adopt this practice. +content: +h1: Key Rotation +paragraph: Find out how to rotate keys, and why you should adopt this practice. +tags: key sensitive-data rotation +dates: +validation: 2024-08-28 +posted: 2024-08-28 +categories: + - identity-and-access-management +--- + +Key rotation is a critical security practice that ensures encryption keys are not reused for extended periods. +Regularly rotating keys helps limit the number of messages encrypted with the same key version, +thereby reducing the risk of exposure if a key is compromised. This enhances the overall security and resilience of +your system. Note that 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. + + + Rotating a key will not re-encrypt the DEK you may have generated or any data you may have encrypted. When calling + decrypt with your key on data encrypted before the rotation, the response will contain the ciphertext of your data + with the latest rotation of the key. If you want you can replace your current ciphertext with the new one. + Note that as long as you do not delete the key, everything that you encrypted with it will always be decipherable. + + +## Why should you rotate your keys? + +Key rotation offers several important benefits: + +- **Mitigate cryptanalysis attacks:** Limiting the number 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 +the total number of bytes encrypted with the same key version. For example, for the symmetric algorithm AES-256-GCM, +the keys must be rotated before approximately 2^32 encryptions have been performed, following the guidelines of [NIST +publication 800-38D](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf). +- **Minimize the impact of key compromise:** Regular key rotation limits the number of messages that could be exposed if +a key is compromised. This reduces the potential damage from such an incident. +- **Maintain system resilience against security incidents:** Regular key rotation helps your system stay resilient to +both manual key rotation, whether prompted by a security breach or the need to upgrade to a stronger encryption algorithm. +- **Regulatory requirements:** Many industry regulations and standards, such as PCI DSS, NIST guidelines, and others, +require or recommend regular key rotation as part of maintaining strong cryptographic controls. + +## Automated key rotation policy + +To configure automatic rotation when creating a key, proceed as follows: + +``` + curl -X POST \ + --header 'Content-Type: application/json' \ + --header 'X-Auth-Token: ' \ + 'https://api.scaleway.com/key-manager/v1alpha1/regions/fr-par/keys' \ + --data '{ + "project_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "name": "my-key", + "usage": { + "symmetric_encryption": "aes_256_gcm" + }, + "description": "my key with a rotation policy", + "rotation_policy": { + "rotation_period": "2592000s", // 30 days + "next_rotation_at": "2024-10-01T01:00:00Z" + } + }' +``` + +- **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: + +``` + curl -X PATCH 'https://api.scaleway.com/key-manager/v1alpha1/regions/fr-par/keys/' \ + --header 'Content-Type: application/json' \ + --header 'X-Auth-Token: ' \ + --data '{ + "rotation_policy": { + "rotation_period": "2592000s", // 30 days + "next_rotation_at": "2024-10-01T01:00:00Z" + } + }' +``` + +## Manually rotate your key +To rotate your key manually, you can use the RotateKey endpoint as shown below: + +``` + curl -X POST 'https://api.scaleway.com/key-manager/v1alpha1/regions/fr-par/keys//rotate' \ + --header 'X-Auth-Token: ' \ + --data '' +``` + + + Avoid relying on irregular or manual key rotation as the primary security measure for your application. + + +- Manually rotating a key does not interrupt, modify or affect its existing automatic rotation schedule. +- Note that key rotation (both manual and automated) is not possible when you import your own key, because a new key material +would be required for each rotation. From 3602d127a78ff4d93cd5c39c69f03e8f978f7363 Mon Sep 17 00:00:00 2001 From: nerda-codes <87707325+nerda-codes@users.noreply.github.com> Date: Thu, 3 Oct 2024 17:39:11 +0200 Subject: [PATCH 2/2] docs(review): neda review --- .../key-manager/api-cli/key-rotation.mdx | 60 ++++++++++--------- 1 file changed, 31 insertions(+), 29 deletions(-) diff --git a/identity-and-access-management/key-manager/api-cli/key-rotation.mdx b/identity-and-access-management/key-manager/api-cli/key-rotation.mdx index ed0723e43a..54c4619894 100644 --- a/identity-and-access-management/key-manager/api-cli/key-rotation.mdx +++ b/identity-and-access-management/key-manager/api-cli/key-rotation.mdx @@ -1,55 +1,54 @@ --- meta: -title: Key Rotation +title: Perform key rotation using the Scaleway CLI and API description: Find out how to rotate keys, and why you should adopt this practice. content: -h1: Key Rotation +h1: Perform key rotation using the Scaleway CLI and API paragraph: Find out how to rotate keys, and why you should adopt this practice. tags: key sensitive-data rotation dates: -validation: 2024-08-28 -posted: 2024-08-28 +validation: 2024-10-07 +posted: 2024-10-07 categories: - identity-and-access-management --- -Key rotation is a critical security practice that ensures encryption keys are not reused for extended periods. -Regularly rotating keys helps limit the number of messages encrypted with the same key version, -thereby reducing the risk of exposure if a key is compromised. This enhances the overall security and resilience of -your system. Note that 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. - - - Rotating a key will not re-encrypt the DEK you may have generated or any data you may have encrypted. When calling - decrypt with your key on data encrypted before the rotation, the response will contain the ciphertext of your data - with the latest rotation of the key. If you want you can replace your current ciphertext with the new one. - Note that as long as you do not delete the key, everything that you encrypted with it will always be decipherable. +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. However, this may vary based on your specific use-case and risk profile. + + + Rotating a key will not re-encrypt your data encryption key or any data you may have encrypted. When performing a + decryption operation with your key on data encrypted before the rotation, the response will contain the ciphertext of your data + with the latest rotation of the key. You can replace your current ciphertext with the new one. + As long as you do not delete the key, anything that you have encrypted with it will still be decipherable. -## Why should you rotate your keys? +## Why is key rotation recommended? -Key rotation offers several important benefits: +Key rotation offers several important advantages such as: -- **Mitigate cryptanalysis attacks:** Limiting the number of messages encrypted with the same key version reduces the risk of +- **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 the total number of bytes encrypted with the same key version. For example, for the symmetric algorithm AES-256-GCM, -the keys must be rotated before approximately 2^32 encryptions have been performed, following the guidelines of [NIST +keys must be rotated before approximately 2^32 encryptions have been performed, following the guidelines of [NIST publication 800-38D](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf). -- **Minimize the impact of key compromise:** Regular key rotation limits the number of messages that could be exposed if -a key is compromised. This reduces the potential damage from such an incident. -- **Maintain system resilience against security incidents:** Regular key rotation helps your system stay resilient to + +- **Minimizing the impact of key compromise:** Regular key rotation limits the amount of messages that could be exposed if +a key is compromised. + +- **Maintaining system resilience against security incidents:** Regular key rotation helps your system stay resilient to both manual key rotation, whether prompted by a security breach or the need to upgrade to a stronger encryption algorithm. -- **Regulatory requirements:** Many industry regulations and standards, such as PCI DSS, NIST guidelines, and others, + +- **Complying with regulatory requirements:** Many industry regulations and standards, such as PCI DSS, NIST guidelines, and others, require or recommend regular key rotation as part of maintaining strong cryptographic controls. ## Automated key rotation policy -To configure automatic rotation when creating a key, proceed as follows: +Copy the following command to configure automatic rotation when creating a key: ``` curl -X POST \ --header 'Content-Type: application/json' \ - --header 'X-Auth-Token: ' \ + --header 'X-Auth-Token: ' \ 'https://api.scaleway.com/key-manager/v1alpha1/regions/fr-par/keys' \ --data '{ "project_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", @@ -68,7 +67,7 @@ To configure automatic rotation when creating a key, proceed as follows: - **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 as follows: ``` curl -X PATCH 'https://api.scaleway.com/key-manager/v1alpha1/regions/fr-par/keys/' \ @@ -83,11 +82,12 @@ To configure automatic rotation on an existing key, use the UpdateKey endpoint a ``` ## Manually rotate your key -To rotate your key manually, you can use the RotateKey endpoint as shown below: + +To rotate your key manually, you can use the `RotateKey` endpoint as follows: ``` curl -X POST 'https://api.scaleway.com/key-manager/v1alpha1/regions/fr-par/keys//rotate' \ - --header 'X-Auth-Token: ' \ + --header 'X-Auth-Token: ' \ --data '' ``` @@ -95,6 +95,8 @@ To rotate your key manually, you can use the RotateKey endpoint as shown below: Avoid relying on irregular or manual key rotation as the primary security measure for your application. +Keep in mind that: + - Manually rotating a key does not interrupt, modify or affect its existing automatic rotation schedule. -- Note that key rotation (both manual and automated) is not possible when you import your own key, because a new key material +- Key rotation (both manual and automated) is not possible when you import your own key, because a new key material would be required for each rotation.