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 and 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 and 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)
RSA	Specifies to generate an RSA digital signature. This is the default.
ECDSA	Specifies to generate an EC digital signature.
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.
Hash Method Specification (One required when the MESSAGE keyword is specified or one required when the HASH keyword is specified and the hash formatting method is PKCS-PSS or X9.31)
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 3500.

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 operational secure token or the label of such a token in key storage.

For CCA, this is an RSA or EC 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. 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 bytes. The maximum size of ECC is 132.

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.

signature_bit_length

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