Parameters

Edit online

The parameter definitions for CSNDDSG.

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 - 8.
rule_array
Direction: Input
Type: String array
Keywords that provide control information to the verb. A keyword specifies the method for calculating 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 Generate control information

Keywords for Digital Signature Generate control information
Keyword Description
Digital signature formatting method (One, optional, valid for RSA digital signature generation only).
ISO-9796 Calculate the digital signature on the data according to ISO-9796-1. Any hash method is allowed. This is the default.
PKCS-1.0 Calculate the digital signature on the BER-encoded ASN.1 value of the type DigestInfo containing the hash according to the RSA Data Security, Inc. Public Key Cryptography Standards #1 block type 00. The text must have been hashed and BER-encoded before input to this service.
PKCS-1.1 Calculate the digital signature on the BER-encoded ASN.1 value of the type DigestInfo containing the hash according to the RSA Data Security, Inc. Public Key Cryptography Standards #1 block type 01. The text must have been hashed and BER-encoded before input to this service.
PKCS-PSS Specifies to format the digital signature on the string supplied in the data parameter 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 RSA key modulus. Any supported hash function is allowed.
X9.31 Format according to the ANSI X9.31 standard. The input text must have been previously hashed with one of the hash algorithms specified below.
Data input type (One, optional.)
HASH Process the text supplied in the data parameter 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 parameter as a message that is to be hashed using the specified hashing-method to produce a hash digest, then use the resultant hash digest to produce a digital signature. The text to be hashed 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):
  • when the MESSAGE keyword is specified
  • when the HASH keyword is specified and the hash formatting method is PKCS-PSS or X9.31,
  • when the signature algorithm keyword EDDSA or CRDL-DSA is specified,
  • Required for ML-DSA pre-hash. Only SHA-512 is supported.

Otherwise such a specification is not allowed.
ED-HASH Process the text supplied in the data parameter using the hash method for the Edwards curve of the key passed in the PKA_private_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.

Only valid and required with CRYSTALS-Dilithium or pure ML-DSA keys. Not valid with the CRDL-DSA keyword.
RPMD-160 Hash the input text from the data parameter using the RIPEMD-160 hash method.

Not valid with the CRDL-DSA keyword.
SHA-1 Hash the input text from the data parameter using the SHA-1 hash method.
SHA-224 Hash the input text from the data parameter using the SHA-224 hash method. Not valid with X9.31.

Not valid with the CRDL-DSA keyword.
SHA-256 Hash the input text from the data parameter using the SHA-256 hash method.

Not valid with the CRDL-DSA keyword.
SHA-384 Hash the input text from the data parameter using the SHA-384 hash method.

Not valid with the CRDL-DSA keyword.
SHA-512 Hash the input text from the data parameter using the SHA-512 hash method.

Required with pre-hash ML-DSA keys.
SHA3-224 Hash the input text from the data parameter using the SHA3-224 hash method. Not valid with keywords X9.31, PKCS-1.0, and PKCS-PSS.
SHA3-256 Hash the input text from the data parameter using the SHA3-256 hash method. Not valid with keywords X9.31, PKCS-1.0, and PKCS-PSS.
SHA3-384 Hash the input text from the data parameter using the SHA3-384 hash method. Not valid with keywords X9.31, PKCS-1.0, and PKCS-PSS.
SHA3-512 Hash the input text from the data parameter using the SHA3-512 hash method. Not valid with keywords X9.31, PKCS-1.0, and PKCS-PSS.
Signature algorithm (One, optional)
RSA Generate an RSA digital signature. This is the default.
ECDSA Generate an ECC digital signature. When specified, this is the only keyword permitted in the rule array.
EC-SDSA Specifies to generate a digital signature using the EC-SDSA algorithm.
EDDSA Specifies to generate a digital signature using the EC Edwards algorithm.
CRDL-DSA Specifies to generate a digital signature in the ML-DSA or CRYSTALS-Dilithium digital signature scheme.
Determinacy specification (One, optional). Only valid when keyword CRDL-DSA is selected and the provided key is pure ML-DSA X’05’ or pre-hash ML-DSA X’07’.
DETER Specifies that the signature is generated deterministically. Given the same key and message, the same signature will always be produced. Not recommended due to leakage of message information.
NONDETER Specifies that the signature is generated non-deterministically. Given the same, key and message, a different signature will always be produced. This is the default and more secure.
Regeneration data option (One, optional). Valid only for ML-DSA keys X’05’ and X’07’. The DETER option cannot be selected.
RAWSEED Specifies that the data that is located after the first two bytes of the data parameter is the given raw seed and is used to seed the signature generation process. The first two bytes of the data parameter define the length of the seed. The data to be signed is located after the seed data if rule_array keyword CONTEXT is not specified, or is located after the context data if CONTEXT is specified. See also the description of the CONTEXT keyword later in this table or refer to the Restrictions.
Known answer type specification (One, optional). Valid only for pure and pre-hash 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 where the signature interface is specified as internal.
Signature context specification (One, optional). Valid only for pure and pre-hash ML-DSA keys X’05’ and X’07’.
CONTEXT Specifies that the data that is located after the first two bytes of the data parameter is the given context string, if CONTEXT is specified without the RAWSEED keyword. If CONTEXT and RAWSEED are both provided, then the seed is located after the first two bytes of the data parameter (in a length defined by the first two bytes), followed by two bytes defining the length of the context, followed by the context string. The data to be signed is then located after the context string. See also the Restrictions.
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_private_key_identifier_length
Direction: Input
Type: Integer
The length of the PKA_private_key_identifier field. If the PKA_private_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_private_key_identifier
Direction: Input
Type: String
An internal token or label of an RSA, ECC, ML-DSA or CRYSTALS-Dilithium private key or a retained RSA key. The token key usage flag must permit the generation of signatures. The format restriction field of the RSA private key token will restrict the format allowed to be used with the key.

If the signature format is X9.31, the modulus of the RSA key must have a minimum length of 1024 bits or greater. If the signature algorithm is ECDSA, this parameter must be a token or label of an ECC private key. The token key usage flag must permit the generation of signatures. The format restriction field of the RSA private key token will restrict the format allowed to be used with the key.

If the digital-signature hash formatting method is PKCS-PSS, the RSA key-token must have must have an AES object protection key (a private key section ID of X'30' or X'31' which can be created with key type RSA-AESM and RSA-AESC in PKA Key Token Build (CSNDPKB). Also refer to PKA Key Translate (CSNDPKT) to translate an RSA key-token as needed to the format desired.

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.

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 512 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 length is in the range 64 bytes - 32 MB.

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

  • on a Crypto Express7 CCA coprocessor and 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) and CRYSTALS-Dilithium (6,5) Round 2 and 3:

      the message limit is 18.000 bytes.

    • with pure and pre-hash ML-DSA (8,7) and CRYSTALS-Dilithium (8,7) Round 2 and 3:

      the message limit is 16.000 bytes.

The CRDLHASH rule_array keyword must be specified.

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.

When ZERO-PAD is specified, 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.

When PKCS-PSS is specified, the first 4 bytes must contain the salt length. The remaining bytes of the data parameter must contain the hash or message. The value will be 4 + length of the hash or message.

If the RAWSEED rule_array keyword is selected, this value is the summation of the message to be signed (<a> bytes), a two-byte seed length field, and the seed of <b> bytes as indicated in the seed length field, a+2+b. Currently the only accepted seed length is 32 bytes.

data
Direction: Input
Type: String
A pointer to a string variable containing the application-supplied text on which to generate the signature.

The parameter can identify the hash to be signed or the message to be hashed and signed, depending on the specified rule-array keyword. If the MESSAGE keyword is specified, the input data is treated as data that must be hashed by the verb and then signed. Otherwise, if HASH is specified, the input data is treated as hash digest that is to be signed.

For PKCS formatting, it must be BER-encoded as previously described. For X9.31, the hash algorithms must have been either SHA-1 or RPMD-160. See the rule_array parameter for more information.

If PKCS-PSS is specified, the data parameter includes an additional 4 byte field that contains the salt length in big endian format. This length must be attached to the beginning of the hash or message. To allow use of a salt length less than the hash length, but not zero, enable the Digital Signature Generate - PKCS-PSS allow small salt command (offset X'033C') in the active role. A salt length value can be either 0, or be in the range from 20 through the size allowed by the RSA modulus in bytes. The size of the data to be signed is still governed by the size of the RSA modulus. 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.

Also, if PKCS-PSS is specified, you must specify the hashing method specification keyword indicating the hash algorithm used for the hash data identified by the data parameter.

If the RAWSEED rule_array keyword is specified, the first two bytes of the data parameter are interpreted as the length (n) of the raw seed to be used in the signing process. The seed is located after the seed length field. The data to be signed is located after both the two-byte length field and n number of seed bytes.

signature_field_length
Direction: Input/Output
Type: Integer
The length in bytes of the signature_field to contain the generated digital signature. The maximum size for RSA is 1024. The maximum size of ECC is 132. For ML-DSA or CRYSTALS-Dilithium, the maximum size is 5000.

For RSA, this must be at least the RSA modulus size (rounded up to a multiple of 32 bytes for the X9.31 signature format, or one byte for all other signature formats).

For RSA, this field is updated with the minimum byte length of the digital signature.

For the ECDSA signature algorithm, R concatenated with S is the digital signature. The maximum output value will be 1042 bits (131 bytes). The size of the signature is determined by the size of P. Both R and S will have size P. For prime curves, the maximum size is 2 * 521 bits. For Brainpool curves, the maximum size is 2 * 512 bits. For Koblitz secp256k1 curves, the maximum is 64 bytes.

signature_bit_length
Direction: Output
Type: Integer
The bit length of the digital signature generated. For ISO-9796 this is 1 less than the modulus length. For other RSA processing methods, this is the modulus length.
signature_field
Direction: Output
Type: String
The digital signature generated is returned in this field. 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. Any unused bytes to the right are undefined.