Using CloudHSM CLI to generate keys - AWS CloudHSM
Generate symmetric keysGenerate asymmetric keysRelated topics

Using CloudHSM CLI to generate keys

Before you can generate a key, you must start CloudHSM CLI and log in as a crypto user (CU). To generate keys on the HSM, use the command that corresponds to the type of key that you want to generate.

Generate symmetric keys

Use the commands listed in key generate-symmetric to generate symmetric keys. To see all available options, use the help key generate-symmetric command.

Generate an AES key

Use the key generate-symmetric aes command to generate AES keys. To see all available options, use the help key generate-symmetric aes command.

The following example generates a 32-byte AES key.

aws-cloudhsm > key generate-symmetric aes \
    --label aes-example \
    --key-length-bytes 32

Arguments

<LABEL>

Specifies a user-defined label for the AES key.

Required: Yes

<KEY-LENGTH-BYTES>

Specifies the key length in bytes.

Valid values:

  • 16, 24, and 32

Required: Yes

<KEY_ATTRIBUTES>

Specifies a space separated list of key attributes to set for the generated AES key in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE (for example, token=true)

For a list of supported AWS CloudHSM key attributes, see Key attributes for CloudHSM CLI.

Required: No

<SESSION>

Creates a key that exists only in the current session. The key cannot be recovered after the session ends. Use this parameter when you need a key only briefly, such as a wrapping key that encrypts, and then quickly decrypts, another key. Do not use a session key to encrypt data that you might need to decrypt after the session ends.

To change a session key to a persistent (token) key, use key set-attribute.

By default, when keys are generated they are persistent/token keys. Using <SESSION> changes this, ensuring a key generated with this argument is a session/ephemural

Required: No

Generate generic secret key

Use the key generate-symmetric generic-secret command to generate generic secret keys. To see all available options, use the help key generate-symmetric generic-secret command.

The following example generates a 32-byte generic secret key.

aws-cloudhsm > key generate-symmetric generic-secret \
    --label generic-secret-example \
    --key-length-bytes 32
Arguments
<LABEL>

Specifies a user-defined label for the generic secret key.

Required: Yes

<KEY-LENGTH-BYTES>

Specifies the key length in bytes.

Valid values:

  • 1 to 800

Required: Yes

<KEY_ATTRIBUTES>

Specifies a space separated list of key attributes to set for the generated generic secret key in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE (for example, token=true)

For a list of supported AWS CloudHSM key attributes, see Key attributes for CloudHSM CLI.

Required: No

<SESSION>

Creates a key that exists only in the current session. The key cannot be recovered after the session ends. Use this parameter when you need a key only briefly, such as a wrapping key that encrypts, and then quickly decrypts, another key. Do not use a session key to encrypt data that you might need to decrypt after the session ends.

To change a session key to a persistent (token) key, use key set-attribute.

By default, when keys are generated they are persistent/token keys. Using <SESSION> changes this, ensuring a key generated with this argument is a session/ephemural

Required: No

Generate asymmetric keys

Use the commands listed in key generate-asymmetric-pair to generate asymmetric key pairs.

Generate an RSA key

Use the key generate-asymmetric-pair rsa command to generate an RSA key pair. To see all available options, use the help key generate-asymmetric-pair rsa command.

The following example generates an RSA 2048-bit key pair.

aws-cloudhsm > key generate-asymmetric-pair rsa \
    --public-exponent 65537 \
    --modulus-size-bits 2048 \
    --public-label rsa-public-example \
    --private-label rsa-private-example

Arguments

<PUBLIC_LABEL>

Specifies a user-defined label for the public-key.

Required: Yes

<PRIVATE_LABEL>

Specifies a user-defined label for the private-key.

Required: Yes

<MODULUS_SIZE_BITS>

Specifies the length of the modulus in bits. The minimum value is 2048.

Required: Yes

<PUBLIC_EXPONENT>

Specifies the public exponent. The value must be an odd number greater than or equal to 65537.

Required: Yes

<PUBLIC_KEY_ATTRIBUTES>

Specifies a space-separated list of key attributes to set for the generated RSA public key in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE (for example, token=true).

For a list of supported AWS CloudHSM key attributes, see Key attributes for CloudHSM CLI.

Required: No

<SESSION>

Creates a key that exists only in the current session. The key cannot be recovered after the session ends. Use this parameter when you need a key only briefly, such as a wrapping key that encrypts, and then quickly decrypts, another key. Do not use a session key to encrypt data that you might need to decrypt after the session ends.

To change a session key to a persistent (token) key, use key set-attribute.

By default, when keys are generated they are persistent/token keys. Using <SESSION> changes this, ensuring a key generated with this argument is a session/ephemural

Required: No

Generate EC (elliptic curve cryptography) key pairs

Use the key generate-asymmetric-pair ec command to generate an EC key pair. To see all available options,including a list of the supported elliptic curves, use the help key generate-asymmetric-pair ec command.

The following example generates an EC key pair using the Secp384r1 elliptic curve.

aws-cloudhsm > key generate-asymmetric-pair ec \
    --curve secp384r1 \
    --public-label ec-public-example \
    --private-label ec-private-example
Arguments
<PUBLIC_LABEL>

Specifies a user-defined label for the public-key. The maximum size allowable for label is 127 characters for Client SDK 5.11 and after. Client SDK 5.10 and before has a limit of 126 characters.

Required: Yes

<PRIVATE_LABEL>

Specifies a user-defined label for the private-key. The maximum size allowable for label is 127 characters for Client SDK 5.11 and after. Client SDK 5.10 and before has a limit of 126 characters.

Required: Yes

<CURVE>

Specifies the identifier for the elliptic curve.

Valid values:

  • prime256v1

  • secp256r1

  • secp224r1

  • secp384r1

  • secp256k1

  • secp521r1

Required: Yes

<PUBLIC_KEY_ATTRIBUTES>

Specifies a space-separated list of key attributes to set for the generated EC public key in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE (for example, token=true).

For a list of supported AWS CloudHSM key attributes, see Key attributes for CloudHSM CLI.

Required: No

<PRIVATE_KEY_ATTRIBUTES>

Specifies a space-separated list of key attributes to set for the generated EC private key in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE (for example, token=true).

For a list of supported AWS CloudHSM key attributes, see Key attributes for CloudHSM CLI.

Required: No

<SESSION>

Creates a key that exists only in the current session. The key cannot be recovered after the session ends. Use this parameter when you need a key only briefly, such as a wrapping key that encrypts, and then quickly decrypts, another key. Do not use a session key to encrypt data that you might need to decrypt after the session ends.

To change a session key to a persistent (token) key, use key set-attribute.

By default, keys that are generated are persistent (token) keys. Passing in <SESSION> changes this, ensuring a key generated with this argument is a session (ephemeral) key.

Required: No

Related topics