# The key unwrap command in CloudHSM CLI The **key unwrap** parent command in CloudHSM CLI imports an encrypted (wrapped) symmetric or asymmetric private key from a file and into the HSM. This command is designed to import encrypted keys that were wrapped by the [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md) command, but it can also be used to unwrap keys that were wrapped with other tools. However, in those situations, we recommend using the PKCS\$111 or JCE software libraries to unwrap the key. + [aes-gcm](cloudhsm_cli-key-unwrap-aes-gcm.md) + [aes-no-pad](cloudhsm_cli-key-unwrap-aes-no-pad.md) + [aes-pkcs5-pad](cloudhsm_cli-key-unwrap-aes-pkcs5-pad.md) + [aes-zero-pad](cloudhsm_cli-key-unwrap-aes-zero-pad.md) + [cloudhsm-aes-gcm](cloudhsm_cli-key-unwrap-cloudhsm-aes-gcm.md) + [rsa-aes](cloudhsm_cli-key-unwrap-rsa-aes.md) + [rsa-oaep](cloudhsm_cli-key-unwrap-rsa-oaep.md) + [rsa-pkcs](cloudhsm_cli-key-unwrap-rsa-pkcs.md) # Unwrap a key with AES-GCM using CloudHSM CLI Use the **key unwrap aes-gcm** command in CloudHSM CLI to unwrap a payload key into the cluster using the AES wrapping key and the `AES-GCM` unwrapping mechanism. Unwrapped keys can be used in the same ways as the keys generated by AWS CloudHSM. To indicate that they were not generated locally, their `local` attribute is set to `false`. To use the **key unwrap aes-gcm** command, you must have the AES wrapping key in your AWS CloudHSM cluster, and its `unwrap` attribute must be set to `true`. ## User type The following types of users can run this command. + Crypto users (CUs) ## Requirements + To run this command, you must be logged in as a CU. ## Syntax ``` aws-cloudhsm > help key unwrap aes-gcm Usage: key unwrap aes-gcm [OPTIONS] --filter [...] --tag-length-bits --key-type-class --label --iv <--data-path |--data > Options: --cluster-id Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error --filter [...] Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a key to unwrap with --data-path Path to the binary file containing the wrapped key data --data Base64 encoded wrapped key data --attributes [...] Space separated list of key attributes in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE for the unwrapped key --share-crypto-users [ Aes GCM Additional Authenticated Data (AAD) value, in hex --tag-length-bits Aes GCM tag length in bits --key-type-class Key type and class of wrapped key [possible values: aes, des3, ec-private, generic-secret, rsa-private] --label Label for the unwrapped key --session Creates a session key that exists only in the current session. The key cannot be recovered after the session ends --iv Initial value used to wrap the key, in hex --approval Filepath of signed quorum token file to approve operation -h, --help Print help ``` ## Examples These examples show how to use the **key unwrap aes-gcm** command using an AES key with the `unwrap` attribute value set to `true`. **Example: Unwrap a payload key from Base64 encoded wrapped key data** ``` aws-cloudhsm > key unwrap aes-gcm --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --tag-length-bits 64 --aad 0x10 --iv 0xf90613bb8e337ec0339aad21 --data xvslgrtg8kHzrvekny97tLSIeokpPwV8 { "error_code": 0, "data": { "key": { "key-reference": "0x00000000001808e4", "key-info": { "key-owners": [ { "username": "cu1", "key-coverage": "full" } ], "shared-users": [], "key-quorum-values": { "manage-key-quorum-value": 0, "use-key-quorum-value": 0 }, "cluster-coverage": "full" }, "attributes": { "key-type": "aes", "label": "aes-unwrapped", "id": "0x", "check-value": "0x8d9099", "class": "secret-key", "encrypt": false, "decrypt": false, "token": true, "always-sensitive": false, "derive": false, "destroyable": true, "extractable": true, "local": false, "modifiable": true, "never-extractable": false, "private": true, "sensitive": true, "sign": true, "trusted": false, "unwrap": false, "verify": true, "wrap": false, "wrap-with-trusted": false, "key-length-bytes": 16 } } } } ``` **Example: Unwrap a payload key provided through a data path** ``` aws-cloudhsm > key unwrap aes-gcm --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --tag-length-bits 64 --aad 0x10 --iv 0xf90613bb8e337ec0339aad21 --data-path payload-key.pem { "error_code": 0, "data": { "key": { "key-reference": "0x00000000001808e4", "key-info": { "key-owners": [ { "username": "cu1", "key-coverage": "full" } ], "shared-users": [], "key-quorum-values": { "manage-key-quorum-value": 0, "use-key-quorum-value": 0 }, "cluster-coverage": "full" }, "attributes": { "key-type": "aes", "label": "aes-unwrapped", "id": "0x", "check-value": "0x8d9099", "class": "secret-key", "encrypt": false, "decrypt": false, "token": true, "always-sensitive": false, "derive": false, "destroyable": true, "extractable": true, "local": false, "modifiable": true, "never-extractable": false, "private": true, "sensitive": true, "sign": true, "trusted": false, "unwrap": false, "verify": true, "wrap": false, "wrap-with-trusted": false, "key-length-bytes": 16 } } } } ``` ## Arguments ****** The ID of the cluster to run this operation on. Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) ****** Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a key to unwrap with. Required: Yes ****** Path to the binary file containing the wrapped key data. Required: Yes (unless provided through Base64 encoded data) ****** Base64 encoded wrapped key data. Required: Yes (unless provided through data path) ****** Space separated list of key attributes in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` for the wrapped key. Required: No ****** Aes GCM Additional Authenticated Data (AAD) value, in hex. Required: No ****** Aes GCM tag length in bits. Required: Yes ****** Key type and class of wrapped key [possible values: `aes`, `des3`, `ec-private`, `generic-secret`, `rsa-private`]. Required: Yes ****** Label for the unwrapped key. Required: Yes ****** Creates a session key that exists only in the current session. The key cannot be recovered after the session ends. Required: No ****** Initial value used to wrap the key, in hex. Required: No ****** Specifies the file path to a signed quorum token file to approve operation. Only required if the key management service quorum value of the unwrapping key is greater than 1. ## Related topics + [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md) + [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md) # Unwrap a key with AES-NO-PAD using CloudHSM CLI Use the **key unwrap aes-no-pad** command in CloudHSM CLI to unwrap a payload key into the AWS CloudHSM cluster using the AES wrapping key and the `AES-NO-PAD` unwrapping mechanism. Unwrapped keys can be used in the same ways as the keys generated by AWS CloudHSM. To indicate that they were not generated locally, their `local` attribute is set to `false`. To use the **key unwrap aes-no-pad** command, you must have the AES wrapping key in your AWS CloudHSM cluster, and its `unwrap` attribute must be set to `true`. ## User type The following types of users can run this command. + Crypto users (CUs) ## Requirements + To run this command, you must be logged in as a CU. ## Syntax ``` aws-cloudhsm > help key unwrap aes-no-pad Usage: key unwrap aes-no-pad [OPTIONS] --filter [...] --key-type-class --label <--data-path |--data > Options: --cluster-id Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error --filter [...] Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a key to unwrap with --data-path Path to the binary file containing the wrapped key data --data Base64 encoded wrapped key data --attributes [...] Space separated list of key attributes in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE for the unwrapped key --share-crypto-users [ Key type and class of wrapped key [possible values: aes, des3, ec-private, generic-secret, rsa-private] --label Label for the unwrapped key --session Creates a session key that exists only in the current session. The key cannot be recovered after the session ends --approval Filepath of signed quorum token file to approve operation -h, --help Print help ``` ## Examples These examples show how to use the **key unwrap aes-no-pad** command using an AES key with the `unwrap` attribute value set to `true`. **Example: Unwrap a payload key from Base64 encoded wrapped key data** ``` aws-cloudhsm > key unwrap aes-no-pad --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --data eXK3PMAOnKM9y3YX6brbhtMoC060EOH9 { "error_code": 0, "data": { "key": { "key-reference": "0x00000000001c08ec", "key-info": { "key-owners": [ { "username": "cu1", "key-coverage": "full" } ], "shared-users": [], "key-quorum-values": { "manage-key-quorum-value": 0, "use-key-quorum-value": 0 }, "cluster-coverage": "full" }, "attributes": { "key-type": "aes", "label": "aes-unwrapped", "id": "0x", "check-value": "0x8d9099", "class": "secret-key", "encrypt": false, "decrypt": false, "token": true, "always-sensitive": false, "derive": false, "destroyable": true, "extractable": true, "local": false, "modifiable": true, "never-extractable": false, "private": true, "sensitive": true, "sign": true, "trusted": false, "unwrap": false, "verify": true, "wrap": false, "wrap-with-trusted": false, "key-length-bytes": 16 } } } } ``` **Example: Unwrap a payload key provided through a data path** ``` aws-cloudhsm > key unwrap aes-no-pad --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --data-path payload-key.pem { "error_code": 0, "data": { "key": { "key-reference": "0x00000000001c08ec", "key-info": { "key-owners": [ { "username": "cu1", "key-coverage": "full" } ], "shared-users": [], "key-quorum-values": { "manage-key-quorum-value": 0, "use-key-quorum-value": 0 }, "cluster-coverage": "full" }, "attributes": { "key-type": "aes", "label": "aes-unwrapped", "id": "0x", "check-value": "0x8d9099", "class": "secret-key", "encrypt": false, "decrypt": false, "token": true, "always-sensitive": false, "derive": false, "destroyable": true, "extractable": true, "local": false, "modifiable": true, "never-extractable": false, "private": true, "sensitive": true, "sign": true, "trusted": false, "unwrap": false, "verify": true, "wrap": false, "wrap-with-trusted": false, "key-length-bytes": 16 } } } } ``` ## Arguments ****** The ID of the cluster to run this operation on. Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) ****** Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a key to unwrap with. Required: Yes ****** Path to the binary file containing the wrapped key data. Required: Yes (unless provided through Base64 encoded data) ****** Base64 encoded wrapped key data. Required: Yes (unless provided through data path) ****** Space separated list of key attributes in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` for the wrapped key. Required: No ****** Key type and class of wrapped key [possible values: `aes`, `des3`, `ec-private`, `generic-secret`, `rsa-private`]. Required: Yes ****** Label for the unwrapped key. Required: Yes ****** Creates a session key that exists only in the current session. The key cannot be recovered after the session ends. Required: No ****** Specifies the file path to a signed quorum token file to approve operation. Only required if the key management service quorum value of the unwrapping key is greater than 1. ## Related topics + [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md) + [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md) # Unwrap a key with AES-PKCS5-PAD using CloudHSM CLI Use the **key unwrap aes-pkcs5-pad** command in CloudHSM CLI to unwrap a payload key using the AES wrapping key and the `AES-PKCS5-PAD` unwrapping mechanism. Unwrapped keys can be used in the same ways as the keys generated by AWS CloudHSM. To indicate that they were not generated locally, their `local` attribute is set to `false`. To use the **key unwrap aes-pkcs5-pad** command, you must have the AES wrapping key in your AWS CloudHSM cluster, and its `unwrap` attribute must be set to `true`. ## User type The following types of users can run this command. + Crypto users (CUs) ## Requirements + To run this command, you must be logged in as a CU. ## Syntax ``` aws-cloudhsm > help key unwrap aes-pkcs5-pad Usage: key unwrap aes-pkcs5-pad [OPTIONS] --filter [...] --key-type-class --label <--data-path |--data > Options: --cluster-id Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error --filter [...] Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a key to unwrap with --data-path Path to the binary file containing the wrapped key data --data Base64 encoded wrapped key data --attributes [...] Space separated list of key attributes in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE for the unwrapped key --share-crypto-users [ Key type and class of wrapped key [possible values: aes, des3, ec-private, generic-secret, rsa-private] --label Label for the unwrapped key --session Creates a session key that exists only in the current session. The key cannot be recovered after the session ends --approval Filepath of signed quorum token file to approve operation -h, --help Print help ``` ## Examples These examples show how to use the **key unwrap aes-pkcs5-pad** command using an AES key with the `unwrap` attribute value set to `true`. **Example: Unwrap a payload key from Base64 encoded wrapped key data** ``` aws-cloudhsm > key unwrap aes-pkcs5-pad --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --data MbuYNresfOKyGNnxKWen88nSfX+uUE/0qmGofSisicY= { "error_code": 0, "data": { "key": { "key-reference": "0x00000000001c08e3", "key-info": { "key-owners": [ { "username": "cu1", "key-coverage": "full" } ], "shared-users": [], "key-quorum-values": { "manage-key-quorum-value": 0, "use-key-quorum-value": 0 }, "cluster-coverage": "full" }, "attributes": { "key-type": "aes", "label": "aes-unwrapped", "id": "0x", "check-value": "0x8d9099", "class": "secret-key", "encrypt": false, "decrypt": false, "token": true, "always-sensitive": false, "derive": false, "destroyable": true, "extractable": true, "local": false, "modifiable": true, "never-extractable": false, "private": true, "sensitive": true, "sign": true, "trusted": false, "unwrap": false, "verify": true, "wrap": false, "wrap-with-trusted": false, "key-length-bytes": 16 } } } } ``` **Example: Unwrap a payload key provided through a data path** ``` aws-cloudhsm > key unwrap aes-pkcs5-pad --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --data-path payload-key.pem { "error_code": 0, "data": { "key": { "key-reference": "0x00000000001c08e3", "key-info": { "key-owners": [ { "username": "cu1", "key-coverage": "full" } ], "shared-users": [], "key-quorum-values": { "manage-key-quorum-value": 0, "use-key-quorum-value": 0 }, "cluster-coverage": "full" }, "attributes": { "key-type": "aes", "label": "aes-unwrapped", "id": "0x", "check-value": "0x8d9099", "class": "secret-key", "encrypt": false, "decrypt": false, "token": true, "always-sensitive": false, "derive": false, "destroyable": true, "extractable": true, "local": false, "modifiable": true, "never-extractable": false, "private": true, "sensitive": true, "sign": true, "trusted": false, "unwrap": false, "verify": true, "wrap": false, "wrap-with-trusted": false, "key-length-bytes": 16 } } } } ``` ## Arguments ****** The ID of the cluster to run this operation on. Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) ****** Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a key to unwrap with. Required: Yes ****** Path to the binary file containing the wrapped key data. Required: Yes (unless provided through Base64 encoded data) ****** Base64 encoded wrapped key data. Required: Yes (unless provided through data path) ****** Space separated list of key attributes in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` for the wrapped key. Required: No ****** Key type and class of wrapped key [possible values: `aes`, `des3`, `ec-private`, `generic-secret`, `rsa-private`]. Required: Yes ****** Label for the unwrapped key. Required: Yes ****** Creates a session key that exists only in the current session. The key cannot be recovered after the session ends. Required: No ****** Specifies the file path to a signed quorum token file to approve operation. Only required if the key management service quorum value of the unwrapping key is greater than 1. ## Related topics + [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md) + [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md) # Unwrap a key with AES-ZERO-PAD using CloudHSM CLI Use the **key unwrap aes-zero-pad** command in CloudHSM CLI to unwrap a payload key into the AWS CloudHSM cluster using the AES wrapping key and the `AES-ZERO-PAD` unwrapping mechanism. Unwrapped keys can be used in the same ways as the keys generated by AWS CloudHSM. To indicate that they were not generated locally, their `local` attribute is set to `false`. To use the **key unwrap aes-no-pad** command, you must have the AES wrapping key in your AWS CloudHSM cluster, and its `unwrap` attribute must be set to `true`. ## User type The following types of users can run this command. + Crypto users (CUs) ## Requirements + To run this command, you must be logged in as a CU. ## Syntax ``` aws-cloudhsm > help key unwrap aes-zero-pad Usage: key unwrap aes-zero-pad [OPTIONS] --filter [...] --key-type-class --label <--data-path |--data > Options: --cluster-id Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error --filter [...] Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a key to unwrap with --data-path Path to the binary file containing the wrapped key data --data Base64 encoded wrapped key data --attributes [...] Space separated list of key attributes in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE for the unwrapped key --share-crypto-users [ Key type and class of wrapped key [possible values: aes, des3, ec-private, generic-secret, rsa-private] --label Label for the unwrapped key --session Creates a session key that exists only in the current session. The key cannot be recovered after the session ends --approval Filepath of signed quorum token file to approve operation -h, --help Print help ``` ## Examples These examples show how to use the **key unwrap aes-zero-pad** command using an AES key with the `unwrap` attribute value set to `true`. **Example: Unwrap a payload key from Base64 encoded wrapped key data** ``` aws-cloudhsm > key unwrap aes-zero-pad --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --data L1wVlL/YeBNVAw6Mpk3owFJZXBzDLONt { "error_code": 0, "data": { "key": { "key-reference": "0x00000000001c08e7", "key-info": { "key-owners": [ { "username": "cu1", "key-coverage": "full" } ], "shared-users": [], "key-quorum-values": { "manage-key-quorum-value": 0, "use-key-quorum-value": 0 }, "cluster-coverage": "full" }, "attributes": { "key-type": "aes", "label": "aes-unwrapped", "id": "0x", "check-value": "0x8d9099", "class": "secret-key", "encrypt": false, "decrypt": false, "token": true, "always-sensitive": false, "derive": false, "destroyable": true, "extractable": true, "local": false, "modifiable": true, "never-extractable": false, "private": true, "sensitive": true, "sign": true, "trusted": false, "unwrap": false, "verify": true, "wrap": false, "wrap-with-trusted": false, "key-length-bytes": 16 } } } } ``` **Example: Unwrap a payload key provided through a data path** ``` aws-cloudhsm > key unwrap aes-zero-pad --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --data-path payload-key.pem { "error_code": 0, "data": { "key": { "key-reference": "0x00000000001c08e7", "key-info": { "key-owners": [ { "username": "cu1", "key-coverage": "full" } ], "shared-users": [], "key-quorum-values": { "manage-key-quorum-value": 0, "use-key-quorum-value": 0 }, "cluster-coverage": "full" }, "attributes": { "key-type": "aes", "label": "aes-unwrapped", "id": "0x", "check-value": "0x8d9099", "class": "secret-key", "encrypt": false, "decrypt": false, "token": true, "always-sensitive": false, "derive": false, "destroyable": true, "extractable": true, "local": false, "modifiable": true, "never-extractable": false, "private": true, "sensitive": true, "sign": true, "trusted": false, "unwrap": false, "verify": true, "wrap": false, "wrap-with-trusted": false, "key-length-bytes": 16 } } } } ``` ## Arguments ****** The ID of the cluster to run this operation on. Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) ****** Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a key to unwrap with. Required: Yes ****** Path to the binary file containing the wrapped key data. Required: Yes (unless provided through Base64 encoded data) ****** Base64 encoded wrapped key data. Required: Yes (unless provided through data path) ****** Space separated list of key attributes in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` for the wrapped key. Required: No ****** Key type and class of wrapped key [possible values: `aes`, `des3`, `ec-private`, `generic-secret`, `rsa-private`]. Required: Yes ****** Label for the unwrapped key. Required: Yes ****** Creates a session key that exists only in the current session. The key cannot be recovered after the session ends. Required: No ****** Specifies the file path to a signed quorum token file to approve operation. Only required if the key management service quorum value of the unwrapping key is greater than 1. ## Related topics + [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md) + [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md) # Unwrap a key with CLOUDHSM-AES-GCM using CloudHSM CLI Use the **key unwrap cloudhsm-aes-gcm** command in CloudHSM CLI to unwrap a payload key into the AWS CloudHSM cluster using the AES wrapping key and the `CLOUDHSM-AES-GCM` unwrapping mechanism. Unwrapped keys can be used in the same ways as the keys generated by AWS CloudHSM. To indicate that they were not generated locally, their `local` attribute is set to `false`. To use the **key unwrap cloudhsm-aes-gcm** command, you must have the AES wrapping key in your AWS CloudHSM cluster and its `unwrap` attribute must be set to `true`. ## User type The following types of users can run this command. + Crypto users (CUs) ## Requirements + To run this command, you must be logged in as a CU. ## Syntax ``` aws-cloudhsm > help key unwrap cloudhsm-aes-gcm Usage: key unwrap cloudhsm-aes-gcm [OPTIONS] --filter [...] --tag-length-bits --key-type-class --label <--data-path |--data > Options: --cluster-id Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error --filter [...] Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a key to unwrap with --data-path Path to the binary file containing the wrapped key data --data Base64 encoded wrapped key data --attributes [...] Space separated list of key attributes in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE for the unwrapped key --share-crypto-users [ Aes GCM Additional Authenticated Data (AAD) value, in hex --tag-length-bits Aes GCM tag length in bits --key-type-class Key type and class of wrapped key [possible values: aes, des3, ec-private, generic-secret, rsa-private] --label Label for the unwrapped key --session Creates a session key that exists only in the current session. The key cannot be recovered after the session ends --approval Filepath of signed quorum token file to approve operation -h, --help Print help ``` ## Examples These examples show how to use the **key unwrap cloudhsm-aes-gcm** command using an AES key with the `unwrap` attribute value set to `true`. **Example: Unwrap a payload key from Base64 encoded wrapped key data** ``` aws-cloudhsm > key unwrap cloudhsm-aes-gcm --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --tag-length-bits 64 --aad 0x10 --data 6Rn8nkjEriDYlnP3P8nPkYQ8hplOEJ899zsrF+aTB0i/fIlZ { "error_code": 0, "data": { "key": { "key-reference": "0x00000000001408e8", "key-info": { "key-owners": [ { "username": "cu1", "key-coverage": "full" } ], "shared-users": [], "key-quorum-values": { "manage-key-quorum-value": 0, "use-key-quorum-value": 0 }, "cluster-coverage": "full" }, "attributes": { "key-type": "aes", "label": "aes-unwrapped", "id": "0x", "check-value": "0x8d9099", "class": "secret-key", "encrypt": false, "decrypt": false, "token": true, "always-sensitive": false, "derive": false, "destroyable": true, "extractable": true, "local": false, "modifiable": true, "never-extractable": false, "private": true, "sensitive": true, "sign": true, "trusted": false, "unwrap": false, "verify": true, "wrap": false, "wrap-with-trusted": false, "key-length-bytes": 16 } } } } ``` **Example: Unwrap a payload key provided through a data path** ``` aws-cloudhsm > key unwrap cloudhsm-aes-gcm --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --tag-length-bits 64 --aad 0x10 --data-path payload-key.pem { "error_code": 0, "data": { "key": { "key-reference": "0x00000000001408e8", "key-info": { "key-owners": [ { "username": "cu1", "key-coverage": "full" } ], "shared-users": [], "key-quorum-values": { "manage-key-quorum-value": 0, "use-key-quorum-value": 0 }, "cluster-coverage": "full" }, "attributes": { "key-type": "aes", "label": "aes-unwrapped", "id": "0x", "check-value": "0x8d9099", "class": "secret-key", "encrypt": false, "decrypt": false, "token": true, "always-sensitive": false, "derive": false, "destroyable": true, "extractable": true, "local": false, "modifiable": true, "never-extractable": false, "private": true, "sensitive": true, "sign": true, "trusted": false, "unwrap": false, "verify": true, "wrap": false, "wrap-with-trusted": false, "key-length-bytes": 16 } } } } ``` ## Arguments ****** The ID of the cluster to run this operation on. Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) ****** Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a key to unwrap with. Required: Yes ****** Path to the binary file containing the wrapped key data. Required: Yes (unless provided through Base64 encoded data) ****** Base64 encoded wrapped key data. Required: Yes (unless provided through data path) ****** Space separated list of key attributes in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` for the wrapped key. Required: No ****** Aes GCM Additional Authenticated Data (AAD) value, in hex. Required: No ****** Aes GCM tag length in bits. Required: Yes ****** Key type and class of wrapped key [possible values: `aes`, `des3`, `ec-private`, `generic-secret`, `rsa-private`]. Required: Yes ****** Label for the unwrapped key. Required: Yes ****** Creates a session key that exists only in the current session. The key cannot be recovered after the session ends. Required: No ****** Specifies the file path to a signed quorum token file to approve operation. Only required if the key management service quorum value of the unwrapping key is greater than 1. ## Related topics + [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md) + [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md) # Unwrap a key with RSA-AES using CloudHSM CLI Use the **key unwrap rsa-aes** command in CloudHSM CLI to unwrap a payload key using an RSA private key and the `RSA-AES` unwrapping mechanism. Unwrapped keys can be used in the same ways as the keys generated by AWS CloudHSM. To indicate that they were not generated locally, their `local` attribute is set to `false`. To use the **key unwrap rsa-aes**, you must have the RSA private key of the RSA public wrapping key in your AWS CloudHSM cluster, and its `unwrap` attribute must be set to `true`. **Note** This command is only available with CloudHSM CLI 5.11\$1. ## User type The following types of users can run this command. + Crypto users (CUs) ## Requirements + To run this command, you must be logged in as a CU. ## Syntax ``` aws-cloudhsm > help key unwrap rsa-aes Usage: key unwrap rsa-aes [OPTIONS] --filter [...] --hash-function --mgf --key-type-class --label <--data-path |--data > Options: --cluster-id Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error --filter [...] Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a key to unwrap with --data-path Path to the binary file containing the wrapped key data --data Base64 encoded wrapped key data --attributes [...] Space separated list of key attributes in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE for the unwrapped key --share-crypto-users [ Hash algorithm [possible values: sha1, sha224, sha256, sha384, sha512] --mgf Mask Generation Function algorithm [possible values: mgf1-sha1, mgf1-sha224, mgf1-sha256, mgf1-sha384, mgf1-sha512] --key-type-class Key type and class of wrapped key [possible values: aes, des3, ec-private, generic-secret, rsa-private] --label Label for the unwrapped key --session Creates a session key that exists only in the current session. The key cannot be recovered after the session ends --approval Filepath of signed quorum token file to approve operation -h, --help Print help ``` ## Example These examples show how to use the **key unwrap rsa-aes** command using the RSA private key with the `unwrap` attribute value set to `true`. **Example: Unwrap a payload key from Base64 encoded wrapped key data** ``` aws-cloudhsm > key unwrap rsa-aes --key-type-class aes --label aes-unwrapped --filter attr.label=rsa-private-key-example --hash-function sha256 --mgf mgf1-sha256 --data HrSE1DEyLjIeyGdPa9R+ebiqB5TIJGyamPker31ZebPwRA+NcerbAJO8DJ1lXPygZcI21vIFSZJuWMEiWpe1R9D/5WSYgxLVKex30xCFqebtEzxbKuv4DOmU4meSofqREYvtb3EoIKwjyxCMRQFgoyUCuP4y0f0eSv0k6rSJh4NuCsHptXZbtgNeRcR4botN7LlzkEIUcq4fVHaatCwd0J1QGKHKyRhkol+RL5WGXKe4nAboAkC5GO7veI5yHL1SaKlssSJtTL/CFpbSLsAFuYbv/NUCWwMY5mwyVTCSlw+HlgKK+5TH1MzBaSi8fpfyepLT8sHy2Q/VRl6ifb49p6m0KQFbRVvz/OWUd6l4d97BdgtaEz6ueg== { "error_code": 0, "data": { "key": { "key-reference": "0x00000000001808e2", "key-info": { "key-owners": [ { "username": "cu1", "key-coverage": "full" } ], "shared-users": [], "key-quorum-values": { "manage-key-quorum-value": 0, "use-key-quorum-value": 0 }, "cluster-coverage": "full" }, "attributes": { "key-type": "aes", "label": "aes-unwrapped", "id": "0x", "check-value": "0x8d9099", "class": "secret-key", "encrypt": false, "decrypt": false, "token": true, "always-sensitive": false, "derive": false, "destroyable": true, "extractable": true, "local": false, "modifiable": true, "never-extractable": false, "private": true, "sensitive": true, "sign": true, "trusted": false, "unwrap": false, "verify": true, "wrap": false, "wrap-with-trusted": false, "key-length-bytes": 16 } } } } ``` **Example: Unwrap a payload key provided through a data path** ``` aws-cloudhsm > key unwrap rsa-aes --key-type-class aes --label aes-unwrapped --filter attr.label=rsa-private-key-example --hash-function sha256 --mgf mgf1-sha256 --data-path payload-key.pem { "error_code": 0, "data": { "key": { "key-reference": "0x00000000001808e2", "key-info": { "key-owners": [ { "username": "cu1", "key-coverage": "full" } ], "shared-users": [], "key-quorum-values": { "manage-key-quorum-value": 0, "use-key-quorum-value": 0 }, "cluster-coverage": "full" }, "attributes": { "key-type": "aes", "label": "aes-unwrapped", "id": "0x", "check-value": "0x8d9099", "class": "secret-key", "encrypt": false, "decrypt": false, "token": true, "always-sensitive": false, "derive": false, "destroyable": true, "extractable": true, "local": false, "modifiable": true, "never-extractable": false, "private": true, "sensitive": true, "sign": true, "trusted": false, "unwrap": false, "verify": true, "wrap": false, "wrap-with-trusted": false, "key-length-bytes": 16 } } } } ``` ## Arguments ****** The ID of the cluster to run this operation on. Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) ****** Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a key to unwrap with. Required: Yes ****** Path to the binary file containing the wrapped key data. Required: Yes (unless provided through Base64 encoded data) ****** Base64 encoded wrapped key data. Required: Yes (unless provided through data path) ****** Space separated list of key attributes in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` for the wrapped key. Required: No ****** Key type and class of wrapped key [possible values: `aes`, `des3`, `ec-private`, `generic-secret`, `rsa-private`]. Required: Yes ****** Specifies the hash function. Valid values: + sha1 + sha224 + sha256 + sha384 + sha512 Required: Yes ****** Specifies the mask generation function. The mask generation function hash function must match the signing mechanism hash function. Valid values: + mgf1-sha1 + mgf1-sha224 + mgf1-sha256 + mgf1-sha384 + mgf1-sha512 Required: Yes ****** Label for the unwrapped key. Required: Yes ****** Creates a session key that exists only in the current session. The key cannot be recovered after the session ends. Required: No ****** Specifies the file path to a signed quorum token file to approve operation. Only required if the key management service quorum value of the unwrapping key is greater than 1. ## Related topics + [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md) + [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md) # Unwrap a key with RSA-OAEP using CloudHSM CLI Use the **key unwrap rsa-oaep** command in CloudHSM CLI to unwrap a payload key using the RSA private key and the `RSA-OAEP` unwrapping mechanism. Unwrapped keys can be used in the same ways as the keys generated by AWS CloudHSM. To indicate that they were not generated locally, their `local` attribute is set to `false`. To use the **key unwrap rsa-oaep** command, you must have the RSA private key of the RSA public wrapping key in your AWS CloudHSM cluster, and its `unwrap` attribute must be set to `true`. ## User type The following types of users can run this command. + Crypto users (CUs) ## Requirements + To run this command, you must be logged in as a CU. ## Syntax ``` aws-cloudhsm > help key unwrap rsa-oaep Usage: key unwrap rsa-oaep [OPTIONS] --filter [...] --hash-function --mgf --key-type-class --label <--data-path |--data Options: --cluster-id Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error --filter [...] Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a key to unwrap with --data-path Path to the binary file containing the wrapped key data --data Base64 encoded wrapped key data --attributes [...] Space separated list of key attributes in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE for the unwrapped key --share-crypto-users [ Hash algorithm [possible values: sha1, sha224, sha256, sha384, sha512] --mgf Mask Generation Function algorithm [possible values: mgf1-sha1, mgf1-sha224, mgf1-sha256, mgf1-sha384, mgf1-sha512] --key-type-class Key type and class of wrapped key [possible values: aes, des3, ec-private, generic-secret, rsa-private] --label Label for the unwrapped key --session Creates a session key that exists only in the current session. The key cannot be recovered after the session ends --approval Filepath of signed quorum token file to approve operation -h, --help Print help ``` ## Examples These examples show how to use the **key unwrap rsa-oaep** command using the RSA private key with the `unwrap` attribute value set to `true`. **Example: Unwrap a payload key from Base64 encoded wrapped key data** ``` aws-cloudhsm > key unwrap rsa-oaep --key-type-class aes --label aes-unwrapped --filter attr.label=rsa-private-example-key --hash-function sha256 --mgf mgf1-sha256 --data OjJe4msobPLz9TuSAdULEu17T5rMDWtSlLyBSkLbaZnYzzpdrhsbGLbwZJCtB/jGkDNdB4qyTAOQwEpggGf6v+Yx6JcesNeKKNU8XZal/YBoHC8noTGUSDI2qr+u2tDc84NPv6d+F2KOONXsSxMhmxzzNG/gzTVIJhOuy/B1yHjGP4mOXoDZf5+7f5M1CjxBmz4Vva/wrWHGCSG0yOaWblEvOiHAIt3UBdyKmU+/My4xjfJv7WGGu3DFUUIZ06TihRtKQhUYU1M9u6NPf9riJJfHsk6QCuSZ9yWThDT9as6i7e3htnyDhIhGWaoK8JU855cN/YNKAUqkNpC4FPL3iw== { "data": { "key": { "key-reference": "0x00000000001808e9", "key-info": { "key-owners": [ { "username": "cu1", "key-coverage": "full" } ], "shared-users": [], "key-quorum-values": { "manage-key-quorum-value": 0, "use-key-quorum-value": 0 }, "cluster-coverage": "full" }, "attributes": { "key-type": "aes", "label": "aes-unwrapped", "id": "0x", "check-value": "0x8d9099", "class": "secret-key", "encrypt": false, "decrypt": false, "token": true, "always-sensitive": false, "derive": false, "destroyable": true, "extractable": true, "local": false, "modifiable": true, "never-extractable": false, "private": true, "sensitive": true, "sign": true, "trusted": false, "unwrap": false, "verify": true, "wrap": false, "wrap-with-trusted": false, "key-length-bytes": 16 } } } } ``` **Example: Unwrap a payload key provided through a data path** ``` aws-cloudhsm > key unwrap rsa-oaep --key-type-class aes --label aes-unwrapped --filter attr.label=rsa-private-example-key --hash-function sha256 --mgf mgf1-sha256 --data-path payload-key.pem { "error_code": 0, "data": { "key": { "key-reference": "0x00000000001808e9", "key-info": { "key-owners": [ { "username": "cu1", "key-coverage": "full" } ], "shared-users": [], "key-quorum-values": { "manage-key-quorum-value": 0, "use-key-quorum-value": 0 }, "cluster-coverage": "full" }, "attributes": { "key-type": "aes", "label": "aes-unwrapped", "id": "0x", "check-value": "0x8d9099", "class": "secret-key", "encrypt": false, "decrypt": false, "token": true, "always-sensitive": false, "derive": false, "destroyable": true, "extractable": true, "local": false, "modifiable": true, "never-extractable": false, "private": true, "sensitive": true, "sign": true, "trusted": false, "unwrap": false, "verify": true, "wrap": false, "wrap-with-trusted": false, "key-length-bytes": 16 } } } } ``` ## Arguments ****** The ID of the cluster to run this operation on. Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) ****** Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a key to unwrap with. Required: Yes ****** Path to the binary file containing the wrapped key data. Required: Yes (unless provided through Base64 encoded data) ****** Base64 encoded wrapped key data. Required: Yes (unless provided through data path) ****** Space separated list of key attributes in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` for the wrapped key. Required: No ****** Key type and class of wrapped key [possible values: `aes`, `des3`, `ec-private`, `generic-secret`, `rsa-private`]. Required: Yes ****** Specifies the hash function. Valid values: + sha1 + sha224 + sha256 + sha384 + sha512 Required: Yes ****** Specifies the mask generation function. The mask generation function hash function must match the signing mechanism hash function. Valid values: + mgf1-sha1 + mgf1-sha224 + mgf1-sha256 + mgf1-sha384 + mgf1-sha512 Required: Yes ****** Label for the unwrapped key. Required: Yes ****** Creates a session key that exists only in the current session. The key cannot be recovered after the session ends. Required: No ****** Specifies the file path to a signed quorum token file to approve operation. Only required if the key management service quorum value of the unwrapping key is greater than 1. ## Related topics + [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md) + [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md) # Unwrap a key with RSA-PKCS using CloudHSM CLI Use the **key unwrap rsa-pkcs** command in CloudHSM CLI to unwrap a payload key using the RSA private key and the `RSA-PKCS` unwrapping mechanism. Unwrapped keys can be used in the same ways as the keys generated by AWS CloudHSM. To indicate that they were not generated locally, their `local` attribute is set to `false`. To use the key **unwrap rsa-pkcs** command, you must have the RSA private key of the RSA public wrapping key in your AWS CloudHSM cluster, and its `unwrap` attribute must be set to `true`. ## User type The following types of users can run this command. + Crypto users (CUs) ## Requirements + To run this command, you must be logged in as a CU. ## Syntax ``` aws-cloudhsm > help key unwrap rsa-pkcs Usage: key unwrap rsa-pkcs [OPTIONS] --filter [...] --key-type-class --label <--data-path |--data > Options: --cluster-id Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error --filter [...] Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a key to unwrap with --data-path Path to the binary file containing the wrapped key data --data Base64 encoded wrapped key data --attributes [...] Space separated list of key attributes in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE for the unwrapped key --share-crypto-users [ Key type and class of wrapped key [possible values: aes, des3, ec-private, generic-secret, rsa-private] --label Label for the unwrapped key --session Creates a session key that exists only in the current session. The key cannot be recovered after the session ends --approval Filepath of signed quorum token file to approve operation -h, --help Print help ``` ## Examples These examples show how to use the **key unwrap rsa-oaep** command using an AES key with the `unwrap` attribute value set to `true`. **Example: Unwrap a payload key from Base64 encoded wrapped key data** ``` aws-cloudhsm > key unwrap rsa-pkcs --key-type-class aes --label aes-unwrapped --filter attr.label=rsa-private-key-example --data am0Nc7+YE8FWs+5HvU7sIBcXVb24QA0l65nbNAD+1bK+e18BpSfnaI3P+r8Dp+pLu1ofoUy/vtzRjZoCiDofcz4EqCFnGl4GdcJ1/3W/5WRvMatCa2d7cx02swaeZcjKsermPXYRO1lGlfq6NskwMeeTkV8R7Rx9artFrs1y0DdIgIKVaiFHwnBIUMnlQrR2zRmMkfwU1jxMYmOYyD031F5VbnjSrhfMwkww2la7uf/c3XdFJ2+0Bo94c6og/yfPcpOOobJlITCoXhtMRepSdO4OggYq/6nUDuHCtJ86pPGnNahyr7+sAaSI3a5ECQLUjwaIARUCyoRh7EFK3qPXcg== { "error_code": 0, "data": { "key": { "key-reference": "0x00000000001c08ef", "key-info": { "key-owners": [ { "username": "cu1", "key-coverage": "full" } ], "shared-users": [], "key-quorum-values": { "manage-key-quorum-value": 0, "use-key-quorum-value": 0 }, "cluster-coverage": "full" }, "attributes": { "key-type": "aes", "label": "aes-unwrapped", "id": "0x", "check-value": "0x8d9099", "class": "secret-key", "encrypt": false, "decrypt": false, "token": true, "always-sensitive": false, "derive": false, "destroyable": true, "extractable": true, "local": false, "modifiable": true, "never-extractable": false, "private": true, "sensitive": true, "sign": true, "trusted": false, "unwrap": false, "verify": true, "wrap": false, "wrap-with-trusted": false, "key-length-bytes": 16 } } } } ``` **Example: Unwrap a payload key provided through a data path** ``` aws-cloudhsm > key unwrap rsa-pkcs --key-type-class aes --label aes-unwrapped --filter attr.label=rsa-private-key-example --data-path payload-key.pem { "error_code": 0, "data": { "key": { "key-reference": "0x00000000001c08ef", "key-info": { "key-owners": [ { "username": "cu1", "key-coverage": "full" } ], "shared-users": [], "key-quorum-values": { "manage-key-quorum-value": 0, "use-key-quorum-value": 0 }, "cluster-coverage": "full" }, "attributes": { "key-type": "aes", "label": "aes-unwrapped", "id": "0x", "check-value": "0x8d9099", "class": "secret-key", "encrypt": false, "decrypt": false, "token": true, "always-sensitive": false, "derive": false, "destroyable": true, "extractable": true, "local": false, "modifiable": true, "never-extractable": false, "private": true, "sensitive": true, "sign": true, "trusted": false, "unwrap": false, "verify": true, "wrap": false, "wrap-with-trusted": false, "key-length-bytes": 16 } } } } ``` ## Arguments ****** The ID of the cluster to run this operation on. Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) ****** Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of `attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` to select a key to unwrap with. Required: Yes ****** Path to the binary file containing the wrapped key data. Required: Yes (unless provided through Base64 encoded data) ****** Base64 encoded wrapped key data. Required: Yes (unless provided through data path) ****** Space separated list of key attributes in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` for the wrapped key. Required: No ****** Key type and class of wrapped key [possible values: `aes`, `des3`, `ec-private`, `generic-secret`, `rsa-private`]. Required: Yes ****** Label for the unwrapped key. Required: Yes ****** Creates a session key that exists only in the current session. The key cannot be recovered after the session ends. Required: No ****** Specifies the file path to a signed quorum token file to approve operation. Only required if the key management service quorum value of the unwrapping key is greater than 1. ## Related topics + [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md) + [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)