feat(key-manager): add a documentation for key rotation

identity-and-access-management/key-manager/api-cli/key-rotation.mdx

@@ -0,0 +1,102 @@
+---
+meta:
+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: 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-10-07
+posted: 2024-10-07
+categories:
+  - identity-and-access-management
+---
+
+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.
+
+<Message type="important">
+    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.
+</Message>
+
+## Why is key rotation recommended?
+
+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
+the total number of bytes encrypted with the same key version. For example, for the symmetric algorithm AES-256-GCM,
+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).
+
+- **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.
+
+- **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
+
+Copy the following command to configure automatic rotation when creating a key:
+
+```
+    curl -X POST \
+    --header 'Content-Type: application/json' \
+    --header 'X-Auth-Token: <Scaleway_API_Secret_Key>' \
+    '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 follows:
+
+```
+    curl -X POST 'https://api.scaleway.com/key-manager/v1alpha1/regions/fr-par/keys/<your_key_id>/rotate' \
+    --header 'X-Auth-Token: <Scaleway_API_Secret_Key>' \
+    --data ''
+```
+
+<Message type="important">
+    Avoid relying on irregular or manual key rotation as the primary security measure for your application.
+</Message>
+
+Keep in mind that:
+
+- Manually rotating a key does not interrupt, modify or affect its existing automatic rotation schedule.
+- 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.