Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions,
see Getting Started with Amazon Web Services in China
(PDF).
Importing key material step 3: Encrypt the
key material
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 Amazon 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.
For asymmetric key pairs, encrypt and import only the private key. Amazon 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.
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 proofofconcept 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 DERencoded 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 256bit symmetric key (32byte 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 128bit symmetric key (16byte 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 384bit
(48byte) 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:P256  openssl pkcs8 topk8 outform der nocrypt > ECC_NIST_P256_PrivateKey.der
openssl genpkey algorithm ec pkeyopt ec_paramgen_curve:P384  openssl pkcs8 topk8 outform der nocrypt > ECC_NIST_P384_PrivateKey.der
openssl genpkey algorithm ec pkeyopt ec_paramgen_curve:P521  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
Examples of encrypting key
material with OpenSSL
The following examples show how to use OpenSSL
to encrypt your key material with the public key that you downloaded.
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.
 RSAES_OAEP_SHA_1

Amazon KMS supports the RSAES_OAEP_SHA_1 for symmetric encryption keys
(SYMMETRIC_DEFAULT), elliptic curve (ECC) 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:

WrappingPublicKey.bin
is the file that
contains the downloaded wrapping public key.

PlaintextKeyMaterial.bin
is the file
that contains the key material that you are encrypting, such as
PlaintextKeyMaterial.bin
, HMAC_384_PlaintextKey.bin
or
ECC_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
 RSAES_OAEP_SHA_256

Amazon KMS supports the RSAES_OAEP_SHA_256 for symmetric encryption keys
(SYMMETRIC_DEFAULT), elliptic curve (ECC) private keys, and HMAC keys.
RSAES_OAEP_SHA_256 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 key or an
RSA_AES_KEY_WRAP wrapping algorithm.
The following example encrypts key material with the public key that you
downloaded and the RSAES_OAEP_SHA_256 wrapping algorithm, and saves it in the
EncryptedKeyMaterial.bin
file.
In this example:

WrappingPublicKey.bin
is the file that
contains the downloaded public wrapping key. If you downloaded the public key from
the console, this file is named
wrappingKey_KMS key_key_ID
_timestamp
(for example,
wrappingKey_f44c4e20f83c48f4adc6a1ef38829760_0809092909
).

PlaintextKeyMaterial.bin
is the file
that contains the key material that you are encrypting, such as
PlaintextKeyMaterial.bin
, HMAC_384_PlaintextKey.bin
, or
ECC_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:sha256 \
pkeyopt rsa_mgf1_md:sha256
 RSA_AES_KEY_WRAP_SHA_1

The RSA_AES_KEY_WRAP_SHA_1 wrapping algorithm involves two encryption
operations.

Encrypt your key material with an AES symmetric key that you generate and an AES
symmetric encryption algorithm.

Encrypt the AES symmetric key that you used with the public key that you
downloaded and the RSAES_OAEP_SHA_1 wrapping algorithm.
Amazon KMS supports RSA_AES_KEY_WRAP_SHA_* wrapping algorithms for all supported types of
imported key material and all supported public key specs. The RSA_AES_KEY_WRAP_SHA_*
algorithms are the only wrapping algorithms supported for wrapping RSA key
material.
The RSA_AES_KEY_WRAP_SHA_1 wrapping algorithm requires OpenSSL version
3.x or later.

Generate a 256bit AES symmetric encryption key
This command generates an AES symmetric encryption key consisting of 256 random
bits, and saves it in the aeskey.bin
file
# Generate a 32byte AES symmetric encryption key
$
openssl rand out aeskey.bin 32

Encrypt your key material with the AES symmetric encryption key
This command encrypts your key material with the AES symmetric encryption key
and saves the encrypted key material in the keymaterialwrapped.bin
file.
In this example command:

PlaintextKeyMaterial.bin
is the file
that contains the key material that you are importing, such as
PlaintextKeyMaterial.bin
, HMAC_384_PlaintextKey.bin
,
RSA_3072_PrivateKey.der
, or
ECC_NIST_P521_PrivateKey.der
.

aeskey.bin
is the file that
contains 256bit AES symmetric encryption key that you generated in the previous
command.
# Encrypt your key material with the AES symmetric encryption key
$
openssl enc idaes256wrappad \
K "$(xxd p < aeskey.bin
 tr d '\n')" \
iv A65959A6 \
in PlaintextKeyMaterial.bin
\
out keymaterialwrapped.bin

Encrypt your AES symmetric encryption key with the public key
This command encrypts your AES symmetric encryption key with the public key that
you downloaded and the RSAES_OAEP_SHA_1 wrapping algorithm, DERencodes it, and save
it in the aeskeywrapped.bin
file.
In this example command:

WrappingPublicKey.bin
is the file
that contains the downloaded public wrapping key. If you downloaded the public
key from the console, this file is named
wrappingKey_KMS key_key_ID
_timestamp
(for example,
wrappingKey_f44c4e20f83c48f4adc6a1ef38829760_0809092909

aeskey.bin
is the file that
contains 256bit AES symmetric encryption key that you generated in the first
command in this example sequence.
# Encrypt your AES symmetric encryption key with the downloaded public key
$
openssl pkeyutl \
encrypt \
in aeskey.bin
\
out aeskeywrapped.bin \
inkey WrappingPublicKey.bin
\
keyform DER \
pubin \
pkeyopt rsa_padding_mode:oaep \
pkeyopt rsa_oaep_md:sha1 \
pkeyopt rsa_mgf1_md:sha1

Generate the file to import
Concatenate the file with the encrypted key material and the file with the
encrypted AES key. Save them in the EncryptedKeyMaterial.bin
file,
which is the file that you'll import in the Step 4: Import the key
material.
In this example command:
# Combine the encrypted AES key and encrypted key material in a file
$
cat aeskeywrapped.bin
keymaterialwrapped.bin
> EncryptedKeyMaterial.bin
 RSA_AES_KEY_WRAP_SHA_256

The RSA_AES_KEY_WRAP_SHA_256 wrapping algorithm involves two encryption
operations.

Encrypt your key material with an AES symmetric key that you generate and an AES
symmetric encryption algorithm.

Encrypt the AES symmetric key that you used with the public key that you
downloaded and the RSAES_OAEP_SHA_256 wrapping algorithm.
Amazon KMS supports RSA_AES_KEY_WRAP_SHA_* wrapping algorithms for all supported types of
imported key material and all supported public key specs. The RSA_AES_KEY_WRAP_SHA_*
algorithms are the only wrapping algorithms supported for wrapping RSA key
material.
The RSA_AES_KEY_WRAP_SHA_256 wrapping algorithm requires OpenSSL version
3.x or later.

Generate a 256bit AES symmetric encryption key
This command generates an AES symmetric encryption key consisting of 256 random
bits, and saves it in the aeskey.bin
file
# Generate a 32byte AES symmetric encryption key
$
openssl rand out aeskey.bin 32

Encrypt your key material with the AES symmetric encryption key
This command encrypts your key material with the AES symmetric encryption key
and saves the encrypted key material in the keymaterialwrapped.bin
file.
In this example command:

PlaintextKeyMaterial.bin
is the file
that contains the key material that you are importing, such as
PlaintextKeyMaterial.bin
, HMAC_384_PlaintextKey.bin
,
RSA_3072_PrivateKey.der
, or
ECC_NIST_P521_PrivateKey.der
.

aeskey.bin
is the file that
contains 256bit AES symmetric encryption key that you generated in the previous
command.
# Encrypt your key material with the AES symmetric encryption key
$
openssl enc idaes256wrappad \
K "$(xxd p < aeskey.bin
 tr d '\n')" \
iv A65959A6 \
in PlaintextKeyMaterial.bin
\
out keymaterialwrapped.bin

Encrypt your AES symmetric encryption key with the public key
This command encrypts your AES symmetric encryption key with the public key that
you downloaded and the RSAES_OAEP_SHA_256 wrapping algorithm, DERencodes it, and
save it in the aeskeywrapped.bin
file.
In this example command:

WrappingPublicKey.bin
is the file
that contains the downloaded public wrapping key. If you downloaded the public
key from the console, this file is named
wrappingKey_KMS key_key_ID
_timestamp
(for example,
wrappingKey_f44c4e20f83c48f4adc6a1ef38829760_0809092909

aeskey.bin
is the file that
contains 256bit AES symmetric encryption key that you generated in the first
command in this example sequence.
# Encrypt your AES symmetric encryption key with the downloaded public key
$
openssl pkeyutl \
encrypt \
in aeskey.bin
\
out aeskeywrapped.bin \
inkey WrappingPublicKey.bin
\
keyform DER \
pubin \
pkeyopt rsa_padding_mode:oaep \
pkeyopt rsa_oaep_md:sha256 \
pkeyopt rsa_mgf1_md:sha256

Generate the file to import
Concatenate the file with the encrypted key material and the file with the
encrypted AES key. Save them in the
EncryptedKeyMaterial.bin
file, which is the file that
you'll import in the Step 4: Import the key
material.
In this example command:
# Combine the encrypted AES key and encrypted key material in a file
$
cat aeskeywrapped.bin
keymaterialwrapped.bin
> EncryptedKeyMaterial.bin
Proceed to Step 4: Import the key
material.