AWS kms documentation change
Summary
Restructured key material requirements with expanded documentation, including new details about HMAC key hashing, valid key length ranges, and explicit formatting requirements for asymmetric keys. Added explicit 'Important' note about ML-DSA key import unsupport.
Security assessment
The changes enhance documentation clarity around cryptographic standards (RFC compliance) and key material handling requirements. While not addressing a specific disclosed vulnerability, they reinforce secure practices by explicitly defining valid key lengths, hashing requirements for oversized HMAC keys, and rejection criteria for non-compliant parameters. The ML-DSA unsupport note prevents insecure usage attempts.
Diff
diff --git a/kms/latest/developerguide/importing-keys-conceptual.md b/kms/latest/developerguide/importing-keys-conceptual.md index 7905a0994..dffffee60 100644 --- a//kms/latest/developerguide/importing-keys-conceptual.md +++ b//kms/latest/developerguide/importing-keys-conceptual.md @@ -92,8 +92,120 @@ AWS KMS supports the following key specs for KMS keys with imported key material -KMS key key spec | Key material requirements ----|--- -**Symmetric encryption keys** SYMMETRIC_DEFAULT | 256-bits (32 bytes) of binary dataIn China Regions, it must be a 128-bits (16 bytes) of binary data. -**HMAC keys** HMAC_224HMAC_256HMAC_384HMAC_512 | HMAC key material must conform to [RFC 2104](https://datatracker.ietf.org/doc/html/rfc2104). The key length must be at least the same length specified by the key spec. The maximum key length is 1024-bits. -**RSA asymmetric private key** RSA_2048RSA_3072RSA_4096 | The RSA asymmetric private key that you import must be part of a key pair that conforms to [RFC 3447](https://datatracker.ietf.org/doc/html/rfc3447/).**Modulus** : 2048 bits, 3072 bits or 4096 bits**Number of primes** : 2 (multi-prime RSA keys are not supported) Asymmetric key material must be BER-encoded or DER-encoded in Public-Key Cryptography Standards (PKCS) #8 format that complies with [[RFC 5208](https://datatracker.ietf.org/doc/html/rfc5208)](https://datatracker.ietf.org/doc/html/rfc5208). -**Elliptic curve asymmetric private key** ECC_NIST_P256 (secp256r1)ECC_NIST_P384 (secp384r1)ECC_NIST_P521 (secp521r1)ECC_SECG_P256K1 (secp256k1) | The ECC asymmetric private key that you import must be part of a key pair that conforms to [RFC 5915](https://datatracker.ietf.org/doc/html/rfc5915/). **Curve** : NIST P-256, NIST P-384, NIST P-521, or Secp256k1 **Parameters** : Named curves only (ECC keys with explicit parameters are rejected) **Public point coordinates** : May be compressed, uncompressed, or projective Asymmetric key material must be BER-encoded or DER-encoded in Public-Key Cryptography Standards (PKCS) #8 format that complies with [[RFC 5208](https://datatracker.ietf.org/doc/html/rfc5208)](https://datatracker.ietf.org/doc/html/rfc5208). -**ML-DSA key** ML_DSA_44 ML_DSA_65 ML_DSA_87 | Importing ML-DSA keys is not supported. -**SM2 asymmetric private key** (China Regions only) | The SM2 asymmetric private key that you import must be part of a key pair that conforms to GM/T 0003. **Curve** : SM2 **Parameters** : Named curve only (SM2 keys with explicit parameters are rejected) **Public point coordinates** : May be compressed, uncompressed, or projective Asymmetric key material must be BER-encoded or DER-encoded in Public-Key Cryptography Standards (PKCS) #8 format that complies with [[RFC 5208](https://datatracker.ietf.org/doc/html/rfc5208)](https://datatracker.ietf.org/doc/html/rfc5208). + * **Symmetric encryption keys** + + * **Key spec:** + + * SYMMETRIC_DEFAULT. + + * **Requirements:** + + * 256-bits (32 bytes) of binary data. + + * In China Regions, it must be a 128-bits (16 bytes) of binary data. + + * **HMAC keys** + + * **Key specs:** + + * HMAC_224 + + * HMAC_256 + + * HMAC_384 + + * HMAC_512 + + * **Requirements:** + + * HMAC key material must conform to [RFC 2104](https://datatracker.ietf.org/doc/html/rfc2104). + + * The key length must be at least the same length specified by the key spec. The maximum key length is 1024-bits. + + * If your key material exceeds 1024 bits, you can hash the key material and import the hash output. The hashing algorithm must match the key spec of the HMAC KMS key you're creating. + + * **Example:** + + * To import 2048 bits of key material into an HMAC_256 key, first compute the SHA-256 hash of the 2048-bit key material, then import the resulting 256-bit hash output into the KMS key. + + * **Valid key lengths:** + + * HMAC_224: 224–1024 bits + + * HMAC_256: 256–1024 bits + + * HMAC_384: 384–1024 bits + + * HMAC_512: 512–1024 bits + + * **RSA asymmetric private key** + + * **Key specs:** + + * RSA_2048 + + * RSA_3072 + + * RSA_4096 + + * **Requirements:** + + * The RSA asymmetric private key that you import must be part of a key pair that conforms to [RFC 3447](https://datatracker.ietf.org/doc/html/rfc3447/). + + * **Modulus:** 2048 bits, 3072 bits or 4096 bits + + * **Number of primes:** 2 (multi-prime RSA keys are not supported) + + * Asymmetric key material must be BER-encoded or DER-encoded in Public-Key Cryptography Standards (PKCS) #8 format that complies with [RFC 5208](https://datatracker.ietf.org/doc/html/rfc5208). + + * **Elliptic curve asymmetric private key** + + * **Key specs:** + + * ECC_NIST_P256 (secp256r1) + + * ECC_NIST_P384 (secp384r1) + + * ECC_NIST_P521 (secp521r1) + + * ECC_SECG_P256K1 (secp256k1) + + * **Requirements:** + + * The ECC asymmetric private key that you import must be part of a key pair that conforms to [RFC 5915](https://datatracker.ietf.org/doc/html/rfc5915/). + + * **Curve:** NIST P-256, NIST P-384, NIST P-521, or Secp256k1. + + * **Parameters:** Named curves only (ECC keys with explicit parameters are rejected). + + * **Public point coordinates:** May be compressed, uncompressed, or projective. + + * Asymmetric key material must be BER-encoded or DER-encoded in Public-Key Cryptography Standards (PKCS) #8 format that complies with [RFC 5208](https://datatracker.ietf.org/doc/html/rfc5208). + + * **ML-DSA key** + + * **Key specs:** + + * ML_DSA_44 + + * ML_DSA_65 + + * ML_DSA_87 + +###### Important + +Importing ML-DSA keys is not supported. + + * **SM2 asymmetric private key** (China Regions only) + + * **Requirements:** + + * The SM2 asymmetric private key that you import must be part of a key pair that conforms to GM/T 0003. + + * **Curve:** SM2. + + * **Parameters:** Named curve only (SM2 keys with explicit parameters are rejected). + + * **Public point coordinates:** May be compressed, uncompressed, or projective. + + * Asymmetric key material must be BER-encoded or DER-encoded in Public-Key Cryptography Standards (PKCS) #8 format that complies with [RFC 5208](https://datatracker.ietf.org/doc/html/rfc5208). + + +