After you download the public key and import token, encrypt your key material using the public key that you downloaded and the wrapping algorithm that you specified. If you need to replace the public key or import token, or change the wrapping algorithm, you must download a new public key and import token. For information about the public keys and wrapping algorithms that AWS KMS supports, see Select a wrapping public key spec and Select a wrapping algorithm.
The key material must be in binary format. For detailed information, see Requirements for imported key material.
Note
For asymmetric key pairs, encrypt and import only the private key. AWS KMS derives the public key from the private key.
The following combination is NOT supported: ECC_NIST_P521 key material, the RSA_2048 public wrapping key spec, and an RSAES_OAEP_SHA_* wrapping algorithm.
You cannot directly wrap ECC_NIST_P521 key material with a RSA_2048 public wrapping key. Use a larger wrapping key or an RSA_AES_KEY_WRAP_SHA_* wrapping algorithm.
The RSA_AES_KEY_WRAP_SHA_256 and RSA_AES_KEY_WRAP_SHA_1 wrapping algorithms are not supported in China Regions.
Typically, you encrypt your key material when you export it from your hardware security module (HSM) or key management system. For information about how to export key material in binary format, see the documentation for your HSM or key management system. You can also refer to the following section that provides a proof of concept demonstration using OpenSSL.
When you encrypt your key material, use the same wrapping algorithm that you specified when you downloaded the public key and import token. To find the wrapping algorithm that you specified, see the CloudTrail log event for the associated GetParametersForImport request.
Generate key material for testing
The following OpenSSL commands generate key material of each supported type for testing. These examples are provided only for testing and proof-of-concept demonstrations. For production systems, use a more secure method to generate your key material, such as a hardware security module or key management system.
To convert the private keys of asymmetric key pairs into DER-encoded format, pipe the key
material generation command to the following openssl pkcs8
command. The
topk8
parameter directs OpenSSL to take a private key as input and return a
PKCS#8 formatted key. (The default behavior is the opposite.)
openssl pkcs8 -topk8 -outform der -nocrypt
The following commands generate test key material for each of the supported key types.
-
Symmetric encryption key (32 bytes)
This command generates a 256-bit symmetric key (32-byte random string) and saves it in the
PlaintextKeyMaterial.bin
file. You do not need to encode this key material.openssl rand -out PlaintextKeyMaterial.bin 32
In China Regions only, you must generate a 128-bit symmetric key (16-byte random string).
openssl rand -out PlaintextKeyMaterial.bin 16
-
HMAC keys
This command generates a random byte string of the specified size. You do not need to encode this key material.
The length of your HMAC key must match the length defined by the key spec of the KMS key. For example, if the KMS key is HMAC_384, you must import a 384-bit (48-byte) key.
openssl rand -out HMAC_224_PlaintextKey.bin 28 openssl rand -out HMAC_256_PlaintextKey.bin 32 openssl rand -out HMAC_384_PlaintextKey.bin 48 openssl rand -out HMAC_512_PlaintextKey.bin 64
-
RSA private keys
openssl genpkey -algorithm rsa -pkeyopt rsa_keygen_bits:2048 | openssl pkcs8 -topk8 -outform der -nocrypt > RSA_2048_PrivateKey.der openssl genpkey -algorithm rsa -pkeyopt rsa_keygen_bits:3072 | openssl pkcs8 -topk8 -outform der -nocrypt > RSA_3072_PrivateKey.der openssl genpkey -algorithm rsa -pkeyopt rsa_keygen_bits:4096 | openssl pkcs8 -topk8 -outform der -nocrypt > RSA_4096_PrivateKey.der
-
ECC private keys
openssl genpkey -algorithm ec -pkeyopt ec_paramgen_curve:P-256 | openssl pkcs8 -topk8 -outform der -nocrypt > ECC_NIST_P256_PrivateKey.der openssl genpkey -algorithm ec -pkeyopt ec_paramgen_curve:P-384 | openssl pkcs8 -topk8 -outform der -nocrypt > ECC_NIST_P384_PrivateKey.der openssl genpkey -algorithm ec -pkeyopt ec_paramgen_curve:P-521 | openssl pkcs8 -topk8 -outform der -nocrypt > ECC_NIST_P521_PrivateKey.der openssl genpkey -algorithm ec -pkeyopt ec_paramgen_curve:secp256k1 | openssl pkcs8 -topk8 -outform der -nocrypt > ECC_SECG_P256K1_PrivateKey.der
-
SM2 private keys (China Regions only)
openssl genpkey -algorithm ec -pkeyopt ec_paramgen_curve:sm2 | openssl pkcs8 -topk8 -outform der -nocrypt > SM2_PrivateKey.der
Examples of encrypting key
material with OpenSSL
The following examples show how to use OpenSSL
Important
These examples are a proof of concept demonstration only. For production systems, use a more secure method (such as a commercial HSM or key management system) to generate and store your key material.
The following combination is NOT supported: ECC_NIST_P521 key material, the RSA_2048 public wrapping key spec, and an RSAES_OAEP_SHA_* wrapping algorithm.
You cannot directly wrap ECC_NIST_P521 key material with a RSA_2048 public wrapping key. Use a larger wrapping key or an RSA_AES_KEY_WRAP_SHA_* wrapping algorithm.
AWS KMS supports the RSAES_OAEP_SHA_1 for symmetric encryption keys (SYMMETRIC_DEFAULT), elliptic curve (ECC) private keys, SM2 private keys, and HMAC keys.
RSAES_OAEP_SHA_1 is not supported for RSA private keys. Also, you cannot use an RSA_2048 public wrapping key with any RSAES_OAEP_SHA_* wrapping algorithm to wrap an ECC_NIST_P521 (secp521r1) private key. You must use a larger public wrapping key or an RSA_AES_KEY_WRAP wrapping algorithm.
The following example encrypts your key material with the public key that you
downloaded and the RSAES_OAEP_SHA_1 wrapping algorithm, and saves it in the
EncryptedKeyMaterial.bin
file.
In this example:
-
is the file that contains the downloaded wrapping public key.WrappingPublicKey.bin
-
is the file that contains the key material that you are encrypting, such asPlaintextKeyMaterial.bin
PlaintextKeyMaterial.bin
,HMAC_384_PlaintextKey.bin
orECC_NIST_P521_PrivateKey.der
.
$
openssl pkeyutl \
-encrypt \
-in PlaintextKeyMaterial.bin
\
-out EncryptedKeyMaterial.bin \
-inkey WrappingPublicKey.bin
\
-keyform DER \
-pubin \
-pkeyopt rsa_padding_mode:oaep \
-pkeyopt rsa_oaep_md:sha1
Proceed to Step 4: Import the key material.