Digital Signature Generate (CSNDDSG and CSNFDSG)

CALL CSNDDSG(
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             rule_array_count,
             rule_array,
             private_key_identifier_length,
             private_key_identifier,
             data_length,
             data,
             signature_field_length,
             signature_bit_length,
             signature_field)

return_code

Direction	Type
Output	Integer

The return code specifies the general result of the callable service. ICSF and cryptographic coprocessor return/reason codes lists the return codes.

reason_code

Direction	Type
Output	Integer

The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes assigned to it that indicate specific processing problems. ICSF and cryptographic coprocessor return/reason codes lists the reason codes.

exit_data_length

Direction	Type
Input/Output	Integer

The length of the data that is passed to the installation exit. The data is identified in the exit_data parameter.

exit_data

Direction	Type
Input/Output	String

The data that is passed to the installation exit.

rule_array_count

Direction	Type
Input	Integer

The number of keywords you are supplying in the rule_array parameter. The value may be 0 1, 2, 3, or 4.

rule_array

Direction	Type
Input	String

The rule_array contains keywords that provide control information to the callable service. The keywords must be in contiguous storage with each of the keywords left-justified in its own 8-byte location and padded on the right with blanks.

Table 1. Keywords for Digital Signature Generate Control Information

Keyword	Meaning
Signature algorithm (One, optional)
CRDL-DSA	Specifies to generate a signature in the CRYSTALS-Dilithium digital signature scheme.
ECDSA	Specifies to generate a digital signature using the ECDSA algorithm.
EC-SDSA	Specifies to generate a digital signature using the EC-SDSA algorithm.
EDDSA	Specifies to generate a digital signature using the EDDSA algorithm.
RSA	Specifies to generate an RSA digital signature. This is the default.
Digital Signature Formatting Method (optional, valid for RSA digital signature generation only)
ISO-9796	Specifies to format the hash according to the ISO/IEC 9796-1 standard and generate the digital signature. Any hash method is allowed. This is the default.
PKCS-1.0	Specifies to format the digital signature on the string supplied in the hash variable as defined in the RSA PKCS #1 standard for block-type 00. The PKCS #1 v2.0 standard no longer defines this signature scheme.
PKCS-1.1	Specifies to format the digital signature on the string supplied in the hash variable as defined in the RSA PKCS #1 v2.0 standard for the RSASSA-PKCS1-v1_5 signature scheme. This was formerly known as block-type 01.
PKCS-PSS	Specifies to format the hash as defined in the RSA PKCS #1 v2.2 standard for the RSASSA-PSS signature scheme. Only valid for RSA-AESM and RSA-AESC key tokens.
X9.31	Specifies to format the hash according to the ANSI X9.31 standard. The modulus length of a key used must be one of 1024, 1280, 1536, 1792, 2048, or 4096 bits.
ZERO-PAD	Specifies to format the hash by padding it on the left with binary zeros to the length of the RSA key modulus. Any supported hash function is allowed.
Data Input Type (One, optional)
HASH	Specifies that the data parameter contains the hash that is to be signed. This is the default.
MESSAGE	Specifies that the data parameter contains the message that is to be hashed and signed. 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, or When the signature algorithm keyword EDDSA or CRDL-DSA is specified.
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_private_key_identifier parameter. For Ed25519, this is SHA-512. For Ed448, this is SHAKE-256. This keyword is required with the EDDSA keyword.
CRDLHASH	Process the text supplied in the message variable using the hash method appropriate for the CRYSTALS-Dilithium algorithm. This is SHAKE-256. Required for CRDL-DSA.
MD5	Process the text supplied in the data parameter using the MD5 hash method. Not valid with PKCS-PSS or X9.31.
RPMD-160	Process the text supplied in the data parameter using the RIPEMD-160 hash method. Not valid with PKCS-PSS.
SHA-1	Process the text supplied in the data parameter using the SHA-1 hash method.
SHA-224	Process the text supplied in the data parameter using the SHA-224 hash method. Not valid with X9.31.
SHA-256	Process the text supplied in the data parameter using the SHA-256 hash method.
SHA-384	Process the text supplied in the data parameter using the SHA-384 hash method.
SHA-512	Process the text supplied in the data parameter using the SHA-512 hash method.

private_key_identifier_length

Direction	Type
Input	Integer

Specifies the length in bytes of the private_key_identifier parameter. If the 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.

For secure PKCS #11 keys, the length must be 64.

private_key_identifier

Direction	Type
Input	String

The identifier of the private key to generate the signature. The key identifier is an RSA, EC, or CRYSTALS-Dilithium private key token, or label of such a private key identifier in key storage.

For CCA, this is an RSA, EC, 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 formatting method PKCS-PSS is specified, the RSA key token must have an AES object protection key (private key section identifiers X'30' and X'31'), which can be created with key type RSA-AESM and RSA-AESC in PKA Key Token Build (CSNDPKB and CSNFPKB).

For secure PKCS #11 keys, this is the 44-byte handle of the private key, prefixed with an EBCDIC equal sign character (‘=’ or X’7E’), and padded on the right with spaces for a total length of 64 bytes.

data_length

Direction	Type
Input	Integer

The length of the data parameter in bytes. See Usage Notes for details of the formatting methods and the length requirements.

When the data input type keyword is MESSAGE, 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 value is 8192. When CRDL-DSA is specified, the maximum data_length for the data passed with a CRYSTALS-Dilithium (6,5) private key is 5000 bytes on Crypto Express7 CCA Coprocessor. The maximum data_length for the data passed with a CRYSTALS-Dilithium private key is 15000 bytes on a Crypto Express8 CCA or later coprocessor. A hash method rule array keyword must be specified.

When the data input type keyword is HASH, the value must be the exact length of the hash to be signed. The maximum value is 516 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 Generate callable service or the MDC Generate callable service to generate the hash.

For the PKCS-PSS formatting rule, the first four bytes must be 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.

For the ZERO-PAD format rule, the length is restricted to 36 for RSA keys that permit key management in the key usage field. For RSA keys that permit signature only in the key usage field, the maximum value is 512. This hash length limit is controlled by an access control point. Only RSA keys that permit key management are affected by this access control point. See the restrictions section of this service for details.

data

Direction	Type
Input	String

The application-supplied data to be signed. The data can be the message to be hashed and signed or the hash of the message. See Usage Notes for details of the formatting methods and the data requirements.

The data must be in the caller's primary address space.

For the PKCS-PSS formatting rule, the first four bytes must be the salt length. The remaining bytes of the parameter must contain the hash or message.

signature_field_length

Direction	Type
Input/Output	Integer

The length in bytes of the signature_field to contain the generated digital signature. Upon return, this field contains the actual length of the generated signature. The maximum size for RSA is 512. The maximum size of ECC is 132. For CRYSTALS-Dilithium, the maximum size is 5000.

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

For ECDSA NIST prime curves, the maximum is 2 * 521 bits. For brain pool curves, the maximum size is 2 * 512 bits. For Koblitz secp256k1 curves, the maximum is 64 bytes.

signature_bit_length

Direction	Type
Output	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	Type
Input/Output	String

The digital signature generated is returned in this field. The digital signature is in the low-order bits (right-justified) of a string whose length is the minimum number of bytes that can contain the digital signature. This string is left-justified within the signature_field. Any unused bytes to the right are undefined.

Although ISO-9796 does not require the input hash to be an integral number of bytes in length, this service requires you to specify the hash_length in bytes.

For CCA RSA keys, the hash length limit is controlled by the DSG ZERO-PAD unrestricted hash length access control point. If enabled, the maximum hash length limit for ZERO-PAD is the modulus length of the PKA private key. If disabled, the maximum hash length limit for ZERO-PAD is 36 bytes. Only RSA key management keys are affected by this access control point. The limit for RSA signature use only keys is 512 bytes. This access control point is disabled in the domain role. You must have a TKE workstation to enable it.

To use this service with a secure PKCS #11 private key that is a public object, the caller must have SO (READ) authority or USER (READ) authority (any access) to the containing PKCS #11 token.

To use this service with a secure PKCS #11 private key that is a private object, the caller must have USER (READ) authority (user access) to the containing PKCS #11 token.

See z/OS Cryptographic Services ICSF Writing PKCS #11 Applications for more information on the SO and User PKCS #11 roles.

SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS, PKDS, or TKDS.

The Digital Signature Generate callable service can take advantage of a PKCS#11 private key object stored in the TKDS, but you should check if using PKCS #11 Private Key Sign (CSFPPKS and CSFPPKS6) aligns better with the overall design of your application.

For PKA private keys, the Digital Signature Generate access control point controls the function of this service.

The length of the hash for ZERO-PAD is restricted to 36 bytes. If the DSG ZERO-PAD unrestricted hash length access control point is enabled in the domain role, the length of the hash is not restricted. This access control is disabled by default.

For the PKCS-PSS formatting method, ICSF requires the salt length specified in the data parameter to be zero or the length of the hash specified. When the Digital Signature Generate – PKCS-PSS allow small salt access control is enabled in the domain role, the salt length may be less than the length of the hash.

For secure PKCS #11 private keys, the Sign with private keys access control point controls the function of this service. For more information on the access control points of the Enterprise PKCS #11 coprocessor, see 'PKCS #11 Access Control Points' in z/OS Cryptographic Services ICSF Writing PKCS #11 Applications.

This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. The CCA releases used in the table are described in CCA release levels.