Parameters

Edit online

The parameters for CSNDDSV.

For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see Parameters common to all verbs.

rule_array_count
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of elements in the rule_array variable. This value must be in the range 0 - 9.
rule_array
Direction: Input
Type: String array
Keywords that provide control information to the verb. A keyword specifies the method to use to verify the digital signature. Each keyword is left-aligned in an 8-byte field and padded on the right with blanks. All keywords must be in contiguous storage. The rule_array keywords are described in Table 1.
Table 1. Keywords for Digital Signature Verify control information

Keywords for Digital Signature Verify control information
Keyword Description
Signature algorithm (One, optional)
CRDL-DSA Specifies to verify a signature in the ML-DSA or CRYSTALS-Dilithium digital signature scheme. This keyword is only supported with the MESSAGE rule_array keyword and data_length up to 6000 bytes.

You should only use PQC public keys whose token section type is 0x'51' and whose algorithm is ML-DSA or CRYSTALS-Dilithium. If you use a PQC private key, then the data_length is severely limited and your CSNDDSV request is likely to fail. To extract just the public key, use the CSNDPKX verb.

ECDSA Verify an ECC digital signature using the ECDSA algorithm.
EC-SDSA Verify an ECC digital signature using the Schnorr Digital Signature (SDSA) algorithm.
EDDSA Specifies to verify an EC Edwards digital signature.

The Signature Algorithm keyword EDDSA must be used with the MESSAGE keyword and the length of the message passed in the data_length parameter must be less than or equal to 8 KB.
RSA Verify an RSA digital signature. This is the default.
Digital signature formatting method (Optional and valid for RSA digital signature verification only.)
ISO-9796 Verify the digital signature on the data according to ISO-9796-1. Any hash method is allowed. This is the default.
PKCS-1.0 Verify the digital signature on the BER-encoded ASN.1 value of the type DigestInfo as specified in the RSA Data Security, Inc. Public Key Cryptography Standards #1 block type 00. The text must specify BER encoded hash text.
PKCS-1.1 Verify the digital signature on the BER-encoded ASN.1 value of the type DigestInfo as specified in the RSA Data Security, Inc. Public Key Cryptography Standards #1 block type 01. The text must specify BER encoded hash text.
PKCS-PSS Verify the digital signature on the string supplied in the data variable as defined in the RSA PKCS #1 v2.2 standard for the RSASSA-PSS signature scheme.
ZERO-PAD Format the data by padding it on the left with binary zeros to the length of the PKA key modulus. Any supported hash function is allowed.
X9.31 Format according to ANSI X9.31 standard.
Data input type (One, optional).
HASH Process the text supplied in the data variable as a hash digest that is to be digitally signed by the verb. This is the default.
MESSAGE Process the text supplied in the data variable as a message. This means, that the text is first hashed using the specified hashing-method to produce a hash digest. Then the resulting hash digest is used to produce a digital signature. The text to be hashed, identified by the data parameter, must be a multiple of eight bits and byte-aligned. This keyword is required with EDDSA, EC-SDSA, and CRDL-DSA keywords.
Hash method specification One required: (1) when the MESSAGE keyword is specified, (2) when the HASH keyword is specified and the hash formatting method is PKCS-PSS or X9.31, (3) when the signature algorithm keyword EDDSA or CRDL-DSA is specified. Otherwise such a specification is not allowed. (4) One required for ML-DSA pre-hash: Only SHA-512 is supported.
ED-HASH Process the text supplied in the data variable using the hash method for the Edwards curve of the key passed in the PKA_public_key_identifier parameter. For Ed25519, this is SHA-512. For Ed448, this is SHAKE-256. This keyword is required with the EDDSA keyword.

Not valid with the CRDL-DSA keyword.
CRDLHASH Process the text supplied in the data parameter using the hash method appropriate for the CRYSTALS-Dilithium or pure ML-DSA algorithm. This is SHAKE-256.

Required with CRYSTALS-Dilithium or pure ML-DSA keys, that is, required and only valid with CRDL-DSA.
RPMD-160 The input value supplied in the data parameter is processed using the RIPEMD-160 hash method. Not valid with the PKCS-1.0, PKCS-1.1, or PKCS-PSS signature methods.

Not valid with the CRDL-DSA keyword.
SHA-1 The input value supplied in the data parameter is processed using the SHA-1 hash method.

Not valid with the CRDL-DSA keyword.
SHA-224 The input value supplied in the data parameter is processed using the 224 hash method. Not valid with the X9.31 signature method.

Not valid with the CRDL-DSA keyword.
SHA-256 The input value supplied in the data parameter is processed using the SHA-256 hash method.

Not valid with the CRDL-DSA keyword.
SHA-384 The input value supplied in the data parameter is processed using the SHA-384 hash method.

Not valid with the CRDL-DSA keyword.
SHA-512 The input value supplied in the data parameter is processed using the SHA-512 hash method.

Not valid with the CRDL-DSA keyword.
SHA3-224 The input value supplied in the data parameter is processed using the SHA3-224 hash method. Not valid with the X9.31, PKCS-1.0, and PKCS-PSS keywords.
SHA3-256 The input value supplied in the data parameter is processed using the SHA3-256 hash method. Not valid with the X9.31, PKCS-1.0, and PKCS-PSS keywords.
SHA3-384 The input value supplied in the data parameter is processed using the SHA3-384 hash method. Not valid with the X9.31, PKCS-1.0, and PKCS-PSS keywords.
SHA3-512 The input value supplied in the data parameter is processed using the SHA3-512 hash method. Not valid with the X9.31, PKCS-1.0, and PKCS-PSS keywords.
Signature checking rule (One optional. Valid only with the PKCS-PSS digital signature hash formatting method.)
EXMATCH Specifies that the 4-byte salt length prepended to the data identified by the data parameter must be an exact match to the salt length derived from the signature. This is the default.
NEXMATCH Specifies that the 4-byte salt length prepended to the data identified by the data parameter does not have to be an exact match to the salt length derived from the signature.
Note: The derived salt length cannot be less than the prepended length.
Trusted public key restriction (Optional. Not valid with ECDSA, EC-SDSA, EDDSA, or CRDL-DSA keywords. Valid only with trusted blocks. See Trusted blocks.)
TPK-ONLY Permits the use of only public keys contained in trusted blocks. By specifying this keyword, the use of regular CCA RSA key tokens is rejected and only the use of a (trusted) public key supplied by the PKA_public_key_identifier parameter can be used to verify the digital signature, thus assuring a sensitive signature verification operation is limited to trusted public keys.

If TPK-ONLY is specified, the PKA_public_key_identifier parameter must identify a trusted block that contains two sections after the trusted block token header: (1) trusted block trusted RSA public key (section X'11'), and (2) trusted block information (section X'14'). Section X'14' is required for all trusted blocks. Section X'11' contains the trusted public key, and its usage rules must indicate it can be used in digital signature operations.
Certificate validation method (One required if the token or label in PKA_public_key_identifier is a certificate. Otherwise, a validation method must not be specified.)
RFC-2459 Validate the certificate using the semantics of RFC-2459.
RFC-3280 Validate the certificate using the semantics of RFC-3280.
RFC-5280 Validate the certificate using the semantics of RFC-5280.
RFC-ANY Attempt to validate the certificate by first using the semantics of RFC-2459, then the semantics of RFC-3280, and finally, the semantics of RFC-5280.
Public key infrastructure usage (One optional when the input is an X.509 certificate. Otherwise, must not be specified.)
PKI-CHK Specifies that the X.509 certificate is to be validated against the trust chain of the PKI hosted in the adapter. This requires that the CA credentials have been installed into all coprocessors using the Trusted Key Entry workstation. This is the default.
PKI-NONE Specifies that the X.509 certificate is not to be validated against the trust chain of the PKI hosted in the adapter. This is suitable if the certificate has been validated using host-based PKI services or if using a self-signed certificate.
Known answer type specification (One, optional). Valid only for ML-DSA keys X’05’ and X’07’. This rule is only for known-answer tests, so either RAWSEED or DETER must be selected.
ACVP Specifies that the request is for NIST Automated Crypto Validation Protocol (ACVP) testing.
Signature context specification (One, optional). Valid only for ML-DSA keys X’05’ and X’07’.
CONTEXT Specifies that the given context string is located after the first two bytes of the data parameter. The data to be signed is located after the context data.

If the CONTEXT rule_array keyword is specified, the first two bytes of the data parameter are interpreted as the length of the context string to be used in the signature verification process.

The context string must be in the range 1 - 255 bytes if the CONTEXT rule_array is specified. CONTEXT can be specified for either pure ML-DSA X'05' or pre-hash ML-DSA X'07'. For pre-hash, currently only SHA-512 is supported.

Tip:
  • Use the SHA-1, SHA-224, SHA-256, SHA-384, or SHA-512 hashing method to create the hash digest for PKCS-1.0 or PKCS-1.1.

    Also, use one of these hashing methods to create the hash digest for ECDSA and PKCS-PSS.

  • Use any hashing method to create the hash digest for ISO-9796 and ZERO-PAD.
  • Use RIPEMD-160, SHA-1, SHA-256, SHA-384, or SHA-512 hashing method to create the hash digest for X9.31.
  • Use MESSAGE and CRDLHASH with CRDL-DSA.
  • Use MESSAGE and ED-HASH with EDDSA.
  • Use MESSAGE and SHA-256 (with secp256r1) or SHA-512 (with secp521r1) with EC-SDSA.
  • Refer to Formatting hashes and keys in public-key cryptography for a discussion of hash formatting methods.
PKA_public_key_identifier_length
Direction: Input
Type: Integer
The length in bytes of the PKA_public_key_identifier parameter containing the public key token or label. If the PKA_public_key_identifier contains a label, the value must be 64. Otherwise, the value must be between the actual length of the token and 8000.
PKA_public_key_identifier
Direction: Input
Type: String
The identifier of the public key to verify the signature. The key identifier is an RSA, ECC, CRYSTALS-Dilithium, or ML-DSA public key token, an internal trusted block, an X.509 certificate, or the label of such a public key identifier in key storage.

If this parameter contains a token or the label of an internal trusted block, the rule_array parameter must specify TPK-ONLY.

If the signature algorithm is ECDSA, this must be a token label or an ECC public key.

For the EC-SDSA algorithm, the key is restricted to secp256r1 (P256) and secp521r1 (P521) curves. The hash method for P256 keys is SHA-256. The hash method for P521 keys is SHA-512.

data_length
Direction: Input
Type: Integer
The length of the data parameter in bytes. It must be the exact length of the text to sign. If you specify ZERO-PAD in the rule_array parameter, the length is restricted to 36 bytes unless the RSA key is a signature-only key. In this case, the maximum length is 1024 bytes.

The data length limit is controlled by an access control point. Only RSA key management keys are affected by this access control point. The limit for RSA signature-only keys is 1024 bytes. This access control point is always disabled in the default role. You must have a TKE workstation to enable it.

When EDDSA or EC-SDSA is specified as signature algorithm, the maximum value is 8192 and the MESSAGE rule is required.

If you specify PKCS-PSS, the first four bytes must contain the salt length. The remaining bytes of the parameter must contain the hash or message. The value will be 4 + length of the hash or message.

If MESSAGE is not specified, the maximum length is 68 bytes. If MESSAGE is specified, the value is the length of the message to be hashed. The maximum value is 2147483647 bytes. When the signature algorithm keyword is EDDSA or EC-SDSA, the maximum length is 8192. When CRDL-DSA is specified, the maximum data_length depends on whether you use a private key (which includes the public-private pair) or only the public key. A hash method rule array keyword must be specified.

When CRDL-DSA is specified, the maximum data length for the data passed is as follows:

  • on a Crypto Express7 CCA coprocessor: for a CRYSTALS-Dilithium (6,5): the message limit is 6000 bytes.
  • on a Crypto Express8 CCA coprocessor:
    • with pure and pre-hash ML-DSA (4,4) and (6,5): the message limit is 18.000 bytes.
    • with pure and pre-hash ML-DSA (8,7): the message limit is 16.000 bytes.

The maximum data_length value for the data passed with an ML-DSA or CRYSTALS-Dilithium private key is 15000 bytes on a Crypto Express8 CCA coprocessor.

Note: If a CRYSTALS-Dilithium-6,5 private key token (which contains the public key) is passed in the PKA_public_key_identifier parameter, the maximum data length is reduced to 2700 bytes. Consider using the CSNDPKX verb to extract the public key to use here when your original data is larger than this.

When HASH is specified (this is the default), the value must be the exact length of the hash to be signed. The maximum value is 512 bytes. The length of the hash for the supported hashing method is 16 for MD5, 20 for SHA-1 and RPMD-160, 28 for SHA-224, 32 for SHA-256, 48 for SHA-384, and 64 for SHA-512. You can use either the One-Way Hash service or the MDC Generate service to generate the hash.

See Usage notes for more information on the allowed length of the text to be verified according to the applied digital signature formatting method.

data
Direction: Input
Type: String

A pointer to a string variable containing the text to be verified. This variable can identify the hash to be verified or the message to be hashed and verified, depending on whether the HASH or MESSAGE input type keyword specified. If MESSAGE is specified, the input data is treated as data that must be hashed by the verb and then verified, otherwise the input data is treated as hash information that is to be verified.

If PKCS-PSS is specified, the data variable includes an additional 4 byte field that contains the salt length in big endian format. This length must be prefixed to the hash or message. To allow use of a salt length less than the hash length, but not zero, enable the Allow Small Salt command (offset X'033C') in the active role. A salt length value can be 0 and 20 through the size allowed by the RSA modulus in bytes. Please note that the size of the data to be signed is still governed by the size of the RSA modulus. Currently, the salt length cannot exceed 1002 bytes. The modulus size and hash length affect the maximum salt length for a given key modulus size and specified hash. The maximum salt length equals modulus_size/8 – hash_length - 2. For example, with a 8192 bit modulus key and SHA-1 hash, the maximum salt length becomes (8192/8) – 20 - 2 = 1002.

If PKCS-PSS is specified for verification with normal processing, the salt length derived from the signature must be an exact match (keyword EXMATCH, the default) for the 4-byte salt length that is prepended in big endian format to the beginning of this parameter. With the Allow Not Exact Salt Length command (offset X'033B') enabled in the active role, keyword NEXMATCH can be specified to allow signature verification when the salt length derived from the signature is not an exact match for the salt length specified with the data parameter. Salt lengths derived from the signature are not allowed to be less than the value specified with the data parameter. Specifying the keyword and enabling the access control point in the active role will allow an additional level of checking. Currently, the salt length cannot exceed 490 bytes.

signature_field_length
Direction: Input
Type: Integer
The length in bytes of the signature_field parameter. The maximum size for RSA is 1024. The maximum size for ECC is 132. The maximum size for CRYSTALS-Dilithium and ML-DSA specified with the CRDL-DSA keyword is 5000.
signature_field
Direction: Input
Type: String
This field contains the digital signature to verify. The digital signature is in the low-order bits (right-aligned) of a string whose length is the minimum number of bytes that can contain the digital signature. This string is left-aligned within the signature_field.