From 1eaa8cf79c3adaf2a1b82ad1e0ddba7059f9522f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?M=C3=A9lanie=20Marques?= <mmarques@scaleway.com>
Date: Mon, 2 Sep 2024 16:00:02 +0200
Subject: [PATCH] feat(key-manager): add a documentation for key rotation

---
 .../key-manager/how-to/key-rotation.mdx       | 105 ++++++++++++++++++
 1 file changed, 105 insertions(+)
 create mode 100644 identity-and-access-management/key-manager/how-to/key-rotation.mdx

diff --git a/identity-and-access-management/key-manager/how-to/key-rotation.mdx b/identity-and-access-management/key-manager/how-to/key-rotation.mdx
new file mode 100644
index 0000000000..f4c37d81ba
--- /dev/null
+++ b/identity-and-access-management/key-manager/how-to/key-rotation.mdx
@@ -0,0 +1,105 @@
+---
+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.
+
+<Message type="note">
+    Rotating a key won't 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.
+</Message>
+
+## 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: <your_scaleway_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/<your_key_id>' \
+    --header 'Content-Type: application/json' \
+    --header 'X-Auth-Token: <your_scaleway_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/<your_key_id>/rotate' \
+    --header 'X-Auth-Token: <your_scaleway_token>' \
+    --data ''
+```
+
+<Message type="important">
+    Avoid relying on irregular or manual key rotation as the primary security measure for your application.
+</Message>
+
+<Message type="note">
+    Manually rotating a key does not interrupt, modify or affect its existing automatic rotation schedule.
+</Message>
+
+<Message type="note">
+    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.
+</Message>