AWS kms documentation change
Summary
Added example for ML-DSA KMS key, emphasized immutability of key spec/usage, added CurrentKeyMaterialId in outputs, renumbered examples
Security assessment
The addition of ML-DSA (module-lattice digital signature algorithm) key support indicates documentation of a new cryptographic algorithm, which is a security feature. The emphasis on immutability of key specs helps prevent misconfiguration but does not address a specific vulnerability.
Diff
diff --git a/kms/latest/developerguide/example_kms_CreateKey_section.md b/kms/latest/developerguide/example_kms_CreateKey_section.md index 38fb4f246..fa1223136 100644 --- a//kms/latest/developerguide/example_kms_CreateKey_section.md +++ b//kms/latest/developerguide/example_kms_CreateKey_section.md @@ -103,0 +104 @@ Output: + "CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6", @@ -126 +127 @@ 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.: @@ -163 +164 @@ 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.: @@ -197 +198,36 @@ 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** @@ -233 +269 @@ 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** @@ -249,0 +286 @@ Output: + "CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6", @@ -276 +313 @@ 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** @@ -349 +386 @@ 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**