AWS cli documentation change

Service: cli · 2025-06-28 · Documentation medium

File: cli/latest/reference/kms/create-key.md

Summary

Added documentation for ML-DSA key type, emphasized immutability of key spec/usage after creation, updated CLI version references, and added CurrentKeyMaterialId in output examples

Security assessment

The addition of ML-DSA_65 key spec documentation introduces support for post-quantum cryptographic algorithms, which is a security feature. Emphasizing that key spec/usage can't be changed after creation improves security awareness but doesn't address a specific vulnerability.

Diff

diff --git a/cli/latest/reference/kms/create-key.md b/cli/latest/reference/kms/create-key.md
index b11053ab6..f04cff157 100644
--- a//cli/latest/reference/kms/create-key.md
+++ b//cli/latest/reference/kms/create-key.md
@@ -15 +15 @@
-  * [AWS CLI 2.27.42 Command Reference](../../index.html) »
+  * [AWS CLI 2.27.45 Command Reference](../../index.html) »
@@ -567,0 +568 @@ Output:
+            "CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
@@ -591 +592 @@ For more information, see [Creating keys](https://docs.aws.amazon.com/kms/latest
-The following `create-key` example creates a KMS key that contains an asymmetric RSA key pair for encryption and decryption.
+The following `create-key` example creates a KMS key that contains an asymmetric RSA key pair for encryption and decryption. The key spec and key usage can’t be changed after the key is created.:
@@ -629 +630 @@ For more information, see [Asymmetric keys in AWS KMS](https://docs.aws.amazon.c
-To create an asymmetric KMS key that contains an asymmetric elliptic curve (ECC) key pair for signing and verification. The `--key-usage` parameter is required even though `SIGN_VERIFY` is the only valid value for ECC KMS keys.
+To create an asymmetric KMS key that contains an asymmetric elliptic curve (ECC) key pair for signing and verification. The `--key-usage` parameter is required even though `SIGN_VERIFY` is the only valid value for ECC KMS keys. The key spec and key usage can’t be changed after the key is created.:
@@ -664 +665,37 @@ For more information, see [Asymmetric keys in AWS KMS](https://docs.aws.amazon.c
-**Example 4: To create an HMAC KMS key**
+**Example 4: To create an asymmetric ML-DSA KMS key for signing and verification**
+
+This example creates a module-lattice digital signature algorithm (ML-DSA) key for signing and verification. The key-usage parameter is required even though `SIGN_VERIFY` is the only valid value for ML-DSA keys.
+    
+    
+    aws kms create-key \
+        --key-spec ML_DSA_65 \
+        --key-usage SIGN_VERIFY
+    
+
+Output:
+    
+    
+    {
+        "KeyMetadata": {
+            "Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
+            "AWSAccountId": "111122223333",
+            "CreationDate": "2019-12-02T07:48:55-07:00",
+            "Description": "",
+            "Enabled": true,
+            "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
+            "KeyManager": "CUSTOMER",
+            "KeySpec": "ML_DSA_65",
+            "KeyState": "Enabled",
+            "KeyUsage": "SIGN_VERIFY",
+            "MultiRegion": false,
+            "Origin": "AWS_KMS",
+            "SigningAlgorithms": [
+                "ML_DSA_SHAKE_256"
+            ]
+        }
+    }
+    
+
+For more information, see [Asymmetric keys in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) in the _AWS Key Management Service Developer Guide_.
+
+**Example 5: To create an HMAC KMS key**
@@ -701 +738 @@ For more information, see [HMAC keys in AWS KMS](https://docs.aws.amazon.com/kms
-**Example 4: To create a multi-Region primary KMS key**
+**Example 6: To create a multi-Region primary KMS key**
@@ -717,0 +755 @@ Output:
+            "CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
@@ -745 +783 @@ For more information, see [Asymmetric keys in AWS KMS](https://docs.aws.amazon.c
-**Example 5: To create a KMS key for imported key material**
+**Example 7: To create a KMS key for imported key material**
@@ -820 +858 @@ For more information, see [AWS CloudHSM key stores](https://docs.aws.amazon.com/
-**Example 7: To create a KMS key in an external key store**
+**Example 8: To create a KMS key in an external key store**
@@ -1060 +1098 @@ KeyMetadata -> (structure)
-  * [AWS CLI 2.27.42 Command Reference](../../index.html) »
+  * [AWS CLI 2.27.45 Command Reference](../../index.html) »