AWS code-library documentation change
Summary
Added example for ML-DSA KMS key, emphasized immutability of key spec/usage, updated example numbering, and added CurrentKeyMaterialId in outputs
Security assessment
The change introduces documentation for ML-DSA cryptographic algorithm support and emphasizes immutability of cryptographic properties post-creation, which are security best practices. However, there's no evidence of addressing a specific security vulnerability.
Diff
diff --git a/code-library/latest/ug/kms_example_kms_CreateKey_section.md b/code-library/latest/ug/kms_example_kms_CreateKey_section.md index 4839565f3..3f01b72fc 100644 --- a//code-library/latest/ug/kms_example_kms_CreateKey_section.md +++ b//code-library/latest/ug/kms_example_kms_CreateKey_section.md @@ -105,0 +106 @@ Output: + "CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6", @@ -128 +129 @@ 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.: @@ -165 +166 @@ 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.: @@ -199 +200,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** @@ -235 +271 @@ 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** @@ -251,0 +288 @@ Output: + "CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6", @@ -278 +315 @@ 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** @@ -351 +388 @@ 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**