AWS kms documentation change

Service: kms · 2025-06-16 · Documentation low

File: kms/latest/developerguide/offline-operations.md

Summary

Added documentation for offline verification using ML-DSA key pairs, including message size handling, EXTERNAL_MU message type, and OpenSSL integration examples

Security assessment

The change documents a new cryptographic implementation (ML-DSA) aligned with FIPS 204 standard for post-quantum security. While it enhances security documentation, there's no evidence of addressing an existing vulnerability.

Diff

diff --git a/kms/latest/developerguide/offline-operations.md b/kms/latest/developerguide/offline-operations.md
index 0906f2b6c..8d0d8fc78 100644
--- a//kms/latest/developerguide/offline-operations.md
+++ b//kms/latest/developerguide/offline-operations.md
@@ -5 +5 @@
-Deriving shared secrets offlineOffline verification with SM2 key pairs (China Regions only)
+Deriving shared secrets offlineOffline verification with ML-DSA key pairsOffline verification with SM2 key pairs (China Regions only)
@@ -18,0 +19,2 @@ This topic provides example offline operations and details the tools AWS KMS pro
+  * Offline verification with ML-DSA key pairs
+
@@ -77,0 +80,97 @@ Show moreShow less
+## Offline verification with ML-DSA key pairs
+
+AWS KMS supports a hedged variant of ML-DSA signing, as described in [Federal Information Processing Standards (FIPS) 204 standard](https://csrc.nist.gov/pubs/fips/204/final) section 3.4 for messages up to 4 KB bytes.
+
+To sign messages larger than 4 KB, you perform the message pre-processing step outside of AWS KMS. This hashing step creates a 64-byte message representative μ, as defined in NIST FIPS 204, section 6.2.
+
+AWS KMS has a message type called `EXTERNAL_MU` for messages larger than 4 KB. When you use this instead of the `RAW` message type, AWS KMS:
+
+  * Assumes you've already performed the hashing step
+
+  * Skips its internal hashing process
+
+  * Works with messages of any size
+
+
+
+
+When you verify a message, the method that you use depends on the size restriction of the external system or library and whether it supports the 64-byte message representative μ:
+
+  * If the message is smaller than the size restriction, use the `RAW` message type.
+
+  * If the message is larger than the size restriction, use the representative μ in the external system.
+
+
+
+
+The following sections demonstrate how to sign messages using AWS KMS and verify messages using OpenSSL. We provide examples for both messages under and over the 4 KB message size limit imposed by AWS KMS. OpenSSL doesn't impose a limit on message size for verification.
+
+For both examples, first get the public key from AWS KMS. Use the following AWS CLI command:
+    
+    
+    aws kms get-public-key \
+        --key-id _<1234abcd-12ab-34cd-56ef-1234567890ab>_ \
+        --output text \
+        --query PublicKey | base64 --decode > public_key.der
+
+### Message size less than 4KB
+
+For messages under 4 KB, use the `RAW` message type with AWS KMS. While you can use `EXTERNAL_MU`, it isn't necessary for messages within the size limit.
+
+Use the following AWS CLI command to sign the message:
+    
+    
+    aws kms sign \
+        --key-id _<1234abcd-12ab-34cd-56ef-1234567890ab>_ \
+        --message 'your message' \
+        --message-type RAW \
+        --signing-algorithm ML_DSA_SHAKE_256 \
+        --output text \
+        --query Signature | base64 --decode > ExampleSignature.bin
+
+To verify this message using OpenSSL use the following command:
+    
+    
+    echo -n 'your message' | ./openssl dgst -verify public_key.der -signature ExampleSignature.bin
+
+### Message size more than 4KB
+
+To sign messages larger than 4KB, use the `EXTERNAL_MU` message type. When you use `EXTERNAL_MU`, you pre-hash the message externally to a 64-byte representative μ as defined in NIST FIPS 204 section 6.2 and pass it to the signing or verifying operations. Note that this is different from the "Pre-hash MLDSA" or HashML-DSA defined in NIST FIPS 204 section 5.4. 
+
+  1. First, construct a message prefix. The prefix contains a domain separator, the length of any context, and the context. The default for the domain separator and context length is zero.
+
+  2. Prepend the message prefix to the message.
+
+  3. Use SHAKE256 to hash the public key and prepend it to the result of step 2.
+
+  4. Finally, hash the result of step 3 to produce a 64-byte `EXTERNAL_MU`.
+
+
+
+
+The following example uses OpenSSL 3.5 to construct the `EXTERNAL_MU`:
+    
+    
+    {
+        openssl asn1parse -inform DER -in public_key.der -strparse 17 -noout -out - 2>/dev/null |
+        openssl dgst -provider default -shake256 -xoflen 64 -binary;
+        printf '\x00\x00';
+        echo -n "your message"
+    } | openssl dgst -provider default -shake256 -xoflen 64 -binary > mu.bin
+
+After you create the `mu.bin` file, call the AWS KMS API with the following command to sign the message:
+    
+    
+    aws kms sign \
+        --key-id _<1234abcd-12ab-34cd-56ef-1234567890ab>_ \
+        --message fileb://mu.bin \
+        --message-type EXTERNAL_MU \
+        --signing-algorithm ML_DSA_SHAKE_256 \
+        --output text \
+        --query Signature | base64 --decode > ExampleSignature.bin
+
+The resulting signature is the same as a `RAW` signature on the original message. You can use the same OpenSSL 3.5 command to verify the message:
+    
+    
+    echo -n 'your message' | ./openssl dgst -verify public_key.der -signature ExampleSignature.bin
+