# The crypto sign category in CloudHSM CLI In the CloudHSM CLI, **crypto sign** is a parent category for a group of commands that, when combined with the parent category, uses a chosen private key in your AWS CloudHSM cluster to generate a signature. **crypto sign** has the following subcommands: + [Generate a signature with the ECDSA mechanism in CloudHSM CLI](cloudhsm_cli-crypto-sign-ecdsa.md) + [Generate a signature with the HashEdDSA mechanism in CloudHSM CLI](cloudhsm_cli-crypto-sign-ed25519ph.md) + [Generate a signature with the RSA-PKCS mechanism in CloudHSM CLI](cloudhsm_cli-crypto-sign-rsa-pkcs.md) + [Generate a signature with the RSA-PKCS-PSS mechanism in CloudHSM CLI](cloudhsm_cli-crypto-sign-rsa-pkcs-pss.md) To use **crypto sign**, you must have a private key in your HSM. You can generate a private key with the following commands: + [key generate-asymmetric-pair ec](cloudhsm_cli-key-generate-asymmetric-pair-ec.md) + [key generate-asymmetric-pair rsa](cloudhsm_cli-key-generate-asymmetric-pair-rsa.md) # Generate a signature with the ECDSA mechanism in CloudHSM CLI Use the **crypto sign ecdsa** command in CloudHSM CLI to generate a signature using an EC private key and the ECDSA signing mechanism. To use the **crypto sign ecdsa** command, you must first have an EC private key in your AWS CloudHSM cluster. You can generate an EC private key using the [Generate an asymmetric EC key pair with CloudHSM CLI](cloudhsm_cli-key-generate-asymmetric-pair-ec.md) command with the `sign` attribute set to `true`. The resulting ECDSA signature is generated in the format `r||s`, where the r and s components are concatenated as raw binary data and returned in base64 encoded format. **Note** Signatures can be verified in AWS CloudHSM with [The crypto verify category in CloudHSM CLI](cloudhsm_cli-crypto-verify.md) subcommands. ## 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 crypto sign ecdsa Sign with the ECDSA mechanism Usage: crypto sign ecdsa --key-filter [>...] --hash-function <--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 --key-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 matching key --hash-function [possible values: sha1, sha224, sha256, sha384, sha512] --data-path The path to the file containing the data to be signed --data Base64 Encoded data to be signed --approval Filepath of signed quorum token file to approve operation --data-type The type of data passed in, either raw or digest [possible values: raw, digest] -h, --help Print help ``` ## Example These examples show how to use **crypto sign ecdsa** to generate a signature using the ECDSA signing mechanism and `SHA256` hash function. This command uses a private key in the HSM. **Example: Generate a signature for base 64 encoded data** ``` aws-cloudhsm > crypto sign ecdsa --key-filter attr.label=ec-private --hash-function sha256 --data YWJjMTIz { "error_code": 0, "data": { "key-reference": "0x00000000007808dd", "signature": "4zki+FzjhP7Z/KqoQvh4ueMAxQQVp7FQguZ2wOS3Q5bzk+Hc5irV5iTkuxQbropPttVFZ8V6FgR2fz+sPegwCw==" } } ``` **Example: Generate a signature for a data file** ``` aws-cloudhsm > crypto sign ecdsa --key-filter attr.label=ec-private --hash-function sha256 --data-path data.txt { "error_code": 0, "data": { "key-reference": "0x00000000007808dd", "signature": "4zki+FzjhP7Z/KqoQvh4ueMAxQQVp7FQguZ2wOS3Q5bzk+Hc5irV5iTkuxQbropPttVFZ8V6FgR2fz+sPegwCw==" } } ``` ## Arguments ****** The ID of the cluster to run this operation on. Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) ****** Base64 encoded data to be signed. Required: Yes (unless provided through data path) ****** Specifies the location of the data to be signed. Required: Yes (unless provided through data path) ****** Specifies the hash function. Valid values: + sha1 + sha224 + sha256 + sha384 + sha512 Required: Yes ****** Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of attr.KEY\$1ATTRIBUTE\$1NAME=KEY\$1ATTRIBUTE\$1VALUE to select a matching key. For a listing of supported CloudHSM CLI key attributes, see Key attributes for CloudHSM CLI. Required: Yes ****** Specifies the file path to a signed quorum token file to approve operation. Only required if the key usage service quorum value of the private key is greater than 1. ****** Specifies whether the value of the data parameter should be hashed as part of the signing algorithm. Use `raw` for unhashed data; use `digest` for digests, which are already hashed. Valid values: + raw + digest ## Related topics + [The crypto sign category in CloudHSM CLI](cloudhsm_cli-crypto-sign.md) + [The crypto verify category in CloudHSM CLI](cloudhsm_cli-crypto-verify.md) # Generate a signature with the HashEdDSA mechanism in CloudHSM CLI **Important** HashEdDSA signing operations are only supported on hsm2m.medium instances in non-FIPS mode. Use the **crypto sign ed25519ph** command in CloudHSM CLI to generate a signature using an Ed25519 private key and the HashEdDSA signing mechanism. For additional information on HashEdDSA, see [NIST SP 186-5, Section 7.8](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf). To use the **crypto sign ed25519ph** command, you must first have an Ed25519 private key in your AWS CloudHSM cluster. You can generate an Ed25519 private key using the [Generate an asymmetric EC key pair with CloudHSM CLI](cloudhsm_cli-key-generate-asymmetric-pair-ec.md) command with the `curve` parameter set to `ed25519` and the `sign` attribute set to `true`. **Note** Signatures can be verified in AWS CloudHSM with [The crypto verify category in CloudHSM CLI](cloudhsm_cli-crypto-verify.md) subcommands. ## 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. + HashEdDSA signing operations are only supported on hsm2m.medium instances in non-FIPS mode. ## Syntax ``` aws-cloudhsm > help crypto sign ed25519ph Sign with the Ed25519ph mechanism Usage: crypto sign ed25519ph [OPTIONS] --key-filter [...] --data-type --hash-function <--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 --key-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 matching key --data-path The path to the file containing the data to be signed --data Base64 Encoded data to be signed --approval Filepath of signed quorum token file to approve operation --data-type The type of data passed in, either raw or digest [possible values: raw, digest] --hash-function Hash function [possible values: sha512] -h, --help Print help ``` ## Example These examples show how to use **crypto sign ed25519ph** to generate a signature using the Ed25519ph signing mechanism and `sha512` hash function. This command uses a private key in the HSM. **Example: Generate a signature for base 64 encoded data** ``` aws-cloudhsm > crypto sign ed25519ph \ --key-filter attr.label=ed25519-private \ --data-type raw \ --hash-function sha512 \ --data YWJj { "error_code": 0, "data": { "key-reference": "0x0000000000401cdf", "signature": "mKcCIvC4Ehqp0w+BPWg/gJ5GK0acf/h2OUmbuU5trkEx+FBCRjwqNVogA9BirfWqoQuMYeY2Biqq0RwqJgg0Bg==" } } ``` **Example: Generate a signature for a data file** ``` aws-cloudhsm > crypto sign ed25519ph \ --key-filter attr.label=ed25519-private \ --data-type raw \ --hash-function sha512 \ --data-path data.txt { "error_code": 0, "data": { "key-reference": "0x0000000000401cdf", "signature": "mKcCIvC4Ehqp0w+BPWg/gJ5GK0acf/h2OUmbuU5trkEx+FBCRjwqNVogA9BirfWqoQuMYeY2Biqq0RwqJgg0Bg==" } } ``` ## Arguments ****** The ID of the cluster to run this operation on. Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) ****** Base64 encoded data to be signed. Required: Yes (unless provided through data path) ****** Specifies the location of the data to be signed. Required: Yes (unless provided through data parameter) ****** Specifies the hash function. Ed25519ph only supports SHA512. Valid values: + sha512 Required: Yes ****** Key reference (for example, `key-reference=0xabc`) or space separated list of key attributes in the form of attr.KEY\$1ATTRIBUTE\$1NAME=KEY\$1ATTRIBUTE\$1VALUE to select a matching key. For a list of supported CloudHSM CLI key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md). Required: Yes ****** Specifies the file path to a signed quorum token file to approve operation. Only required if the key usage service quorum value of the private key is greater than 1. ****** Specifies whether the value of the data parameter should be hashed as part of the signing algorithm. Use `raw` for unhashed data; use `digest` for digests, which are already hashed. Valid values: + raw + digest Required: Yes ## Related topics + [The crypto sign category in CloudHSM CLI](cloudhsm_cli-crypto-sign.md) + [The crypto verify category in CloudHSM CLI](cloudhsm_cli-crypto-verify.md) # Generate a signature with the RSA-PKCS mechanism in CloudHSM CLI Use the **crypto sign rsa-pkcs** command in CloudHSM CLI to generate a signature using an RSA private key and the RSA-PKCS signing mechanism. To use the **crypto sign rsa-pkcs** command, you must first have a RSA private key in your AWS CloudHSM cluster. You can generate an RSA private key using the [Generate an asymmetric RSA key pair with CloudHSM CLI](cloudhsm_cli-key-generate-asymmetric-pair-rsa.md) command with the `sign` attribute set to `true`. **Note** Signatures can be verified in AWS CloudHSM with [The crypto verify category in CloudHSM CLI](cloudhsm_cli-crypto-verify.md) subcommands. ## 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 crypto sign rsa-pkcs Sign with the RSA-PKCS mechanism Usage: crypto sign rsa-pkcs --key-filter [>...] --hash-function <--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 --key-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 matching key --hash-function [possible values: sha1, sha224, sha256, sha384, sha512] --data-path The path to the file containing the data to be signed --data Base64 Encoded data to be signed --approval Filepath of signed quorum token file to approve operation --data-type The type of data passed in, either raw or digest [possible values: raw, digest] -h, --help Print help ``` ## Example These examples show how to use **crypto sign rsa-pkcs** to generate a signature using the RSA-PKCS signing mechanism and `SHA256` hash function. This command uses a private key in the HSM. **Example: Generate a signature for base 64 encoded data** ``` aws-cloudhsm > crypto sign rsa-pkcs --key-filter attr.label=rsa-private --hash-function sha256 --data YWJjMTIz { "error_code": 0, "data": { "key-reference": "0x00000000007008db", "signature": "XJ7mRyHnDRYrDWTQuuNb+5mhoXx7VTsPMjgOQW4iMN7E42eNHj2Q0oovMmBdHUEH0F4HYG8FBJOBhvGuM8J/z6y41GbowVpUT6WzjnIQs79K9i7i6oR1TYjLnIS3r/zkimuXcS8/ZxyDzru+GO9BUT9FFU/of9cvu4Oyn6a5+IXuCbKNQs19uASuFARUTZ0a0Ny1CB1MulxUpqGTmI91J6evlP7k/2khwDmJ5E8FEar5/Cvbn9t21p3Uj561ngTXrYbIZ2KHpef9jQh/cEIvFLG61sexJjQi8EdTxeDA+I3ITO0qrvvESvA9+Sj7kdG2ceIicFS8/8LwyxiIC31UHQ==" } } ``` **Example: Generate a signature for a data file** ``` aws-cloudhsm > crypto sign rsa-pkcs --key-filter attr.label=rsa-private --hash-function sha256 --data-path data.txt { "error_code": 0, "data": { "key-reference": "0x00000000007008db", "signature": "XJ7mRyHnDRYrDWTQuuNb+5mhoXx7VTsPMjgOQW4iMN7E42eNHj2Q0oovMmBdHUEH0F4HYG8FBJOBhvGuM8J/z6y41GbowVpUT6WzjnIQs79K9i7i6oR1TYjLnIS3r/zkimuXcS8/ZxyDzru+GO9BUT9FFU/of9cvu4Oyn6a5+IXuCbKNQs19uASuFARUTZ0a0Ny1CB1MulxUpqGTmI91J6evlP7k/2khwDmJ5E8FEar5/Cvbn9t21p3Uj561ngTXrYbIZ2KHpef9jQh/cEIvFLG61sexJjQi8EdTxeDA+I3ITO0qrvvESvA9+Sj7kdG2ceIicFS8/8LwyxiIC31UHQ==" } } ``` ## Arguments ****** The ID of the cluster to run this operation on. Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) ****** Base64 encoded data to be signed. Required: Yes (unless provided through data path) ****** Specifies the location of the data to be signed. Required: Yes (unless provided through data) ****** Specifies the hash function. Valid values: + sha1 + sha224 + sha256 + sha384 + sha512 Required: Yes ****** 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 matching key. For a listing of supported CloudHSM CLI key attributes, see Key attributes for CloudHSM CLI. Required: Yes ****** Specifies the file path to a signed quorum token file to approve operation. Only required if the key usage service quorum value of the private key is greater than 1. ****** Specifies whether the value of the data parameter should be hashed as part of the signing algorithm. Use `raw` for unhashed data; use `digest` for digests, which are already hashed. For RSA-PKCS, the data must be passed in DER encoded format as specified in [RFC 8017, Section 9.2](https://www.rfc-editor.org/rfc/rfc8017#section-9.2) Valid values: + raw + digest ## Related topics + [The crypto sign category in CloudHSM CLI](cloudhsm_cli-crypto-sign.md) + [The crypto verify category in CloudHSM CLI](cloudhsm_cli-crypto-verify.md) # Generate a signature with the RSA-PKCS-PSS mechanism in CloudHSM CLI Use the **crypto sign rsa-pkcs-pss** command in CloudHSM CLI to generate a signature using an RSA private key and the `RSA-PKCS-PSS` signing mechanism. To use the **crypto sign rsa-pkcs-pss** command, you must first have a RSA private key in your AWS CloudHSM cluster. You can generate an RSA private key using the [Generate an asymmetric RSA key pair with CloudHSM CLI](cloudhsm_cli-key-generate-asymmetric-pair-rsa.md) command with the `sign` attribute set to `true`. **Note** Signatures can be verified in AWS CloudHSM with [The crypto verify category in CloudHSM CLI](cloudhsm_cli-crypto-verify.md) subcommands. ## 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 crypto sign rsa-pkcs-pss Sign with the RSA-PKCS-PSS mechanism Usage: crypto sign rsa-pkcs-pss [OPTIONS] --key-filter [...] --hash-function --mgf --salt-length <--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 --key-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 matching key --hash-function [possible values: sha1, sha224, sha256, sha384, sha512] --data-path The path to the file containing the data to be signed --data Base64 Encoded data to be signed --mgf The mask generation function [possible values: mgf1-sha1, mgf1-sha224, mgf1-sha256, mgf1-sha384, mgf1-sha512] --salt-length The salt length --approval Filepath of signed quorum token file to approve operation --data-type The type of data passed in, either raw or digest [possible values: raw, digest] -h, --help Print help ``` ## Example These examples show how to use **crypto sign rsa-pkcs-pss** to generate a signature using the `RSA-PKCS-PSS` signing mechanism and `SHA256` hash function. This command uses a private key in the HSM. **Example: Generate a signature for base 64 encoded data** ``` aws-cloudhsm > crypto sign rsa-pkcs-pss --key-filter attr.label=rsa-private --hash-function sha256 --data YWJjMTIz --salt-length 10 --mgf mgf1-sha256 { "error_code": 0, "data": { "key-reference": "0x00000000007008db", "signature": "H/z1rYVMzNAa31K4amE5MTiwGxDdCTgQXCJXRBKVOVm7ZuyI0fGE4sT/BUN+977mQEV2TqtWpTsiF2IpwGM1VfSBRt7h/g4o6YERm1tTQLl7q+AJ7uGGK37zCsWQrAo7Vy8NzPShxekePo/ZegrB1aHWN1fE8H3IPUKqLuMDI9o1Jq6kM986ExS7YmeOIclcZkyykTWqHLQVL2C3+A2bHJZBqRcM5XoIpk8HkPypjpN+m4FNUds30GAemoOMl6asSrEJSthaZWV53OBsDOqzA8Rt8JdhXS+GZp3vNLdL1OTBELDPweXVgAu4dBX0FOvpw/gg6sNvuaDK4YOBv2fqKg==" } } ``` **Example: Generate a signature for a data file** ``` aws-cloudhsm > crypto sign rsa-pkcs-pss --key-filter attr.label=rsa-private --hash-function sha256 --data-path data.txt --salt-length 10 --mgf mgf1-sha256 { "error_code": 0, "data": { "key-reference": "0x00000000007008db", "signature": "H/z1rYVMzNAa31K4amE5MTiwGxDdCTgQXCJXRBKVOVm7ZuyI0fGE4sT/BUN+977mQEV2TqtWpTsiF2IpwGM1VfSBRt7h/g4o6YERm1tTQLl7q+AJ7uGGK37zCsWQrAo7Vy8NzPShxekePo/ZegrB1aHWN1fE8H3IPUKqLuMDI9o1Jq6kM986ExS7YmeOIclcZkyykTWqHLQVL2C3+A2bHJZBqRcM5XoIpk8HkPypjpN+m4FNUds30GAemoOMl6asSrEJSthaZWV53OBsDOqzA8Rt8JdhXS+GZp3vNLdL1OTBELDPweXVgAu4dBX0FOvpw/gg6sNvuaDK4YOBv2fqKg==" } } ``` ## Arguments ****** The ID of the cluster to run this operation on. Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md) ****** Base64 encoded data to be signed. Required: Yes (unless provided through data path) ****** Specifies the location of the data to be signed. Required: Yes (unless provided through data) ****** Specifies the hash function. Valid values: + sha1 + sha224 + sha256 + sha384 + sha512 Required: Yes ****** 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 matching key. For a listing of supported CloudHSM CLI key attributes, see Key attributes for CloudHSM CLI. 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 ****** Specifies the salt length. Required: Yes ****** Specifies the file path to a signed quorum token file to approve operation. Only required if the key usage service quorum value of the private key is greater than 1. ****** Specifies whether the value of the data parameter should be hashed as part of the signing algorithm. Use `raw` for unhashed data; use `digest` for digests, which are already hashed. Valid values: + raw + digest ## Related topics + [The crypto sign category in CloudHSM CLI](cloudhsm_cli-crypto-sign.md) + [The crypto verify category in CloudHSM CLI](cloudhsm_cli-crypto-verify.md) ## Related topics + [The crypto verify category in CloudHSM CLI](cloudhsm_cli-crypto-verify.md)