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,
             hash_length,
             hash,
             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, or 3.

rule_array

Direction	Type
Input	String

Keywords that provide control information to the callable service. One keyword specifies the method for calculating the digital signature. Another keyword specifies formatting of the hash value for RSA digital signature generation. A third keyword specifies the hash method used to prepare the hash value for RSA digital signature generation. Table 1 lists the keywords. Each keyword is left-justified in an 8-byte field and padded on the right with blanks. All keywords must be in contiguous storage.

Table 1. Keywords for Digital Signature Generate Control Information

Keyword	Meaning
Digital Signature Formatting Method (optional, valid for RSA digital signature generation only)
ISO-9796	Calculate the digital signature on the hash 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 V1.5 block type 00. The text must have been hashed prior to inputting to this service. Note: Use of block-type 00 has been effectively depreciated by the industry. Rule PKCS-1.1 is recommended.
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 V1.5 block type 01. The text must have been hashed prior to inputting to this service.
ZERO-PAD	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.
X9.31	Format according to the ANSI X9.31 standard. The input text must have been previously hashed with one of these hash algorithms:
Hash Method Specification: Required with X9.31
RPMD-160	Hash the input text using the RIPEMD-160 hash method.
SHA-1	Hash the input text using the SHA-1 hash method.
Signature algorithm (optional, supported on the CEX3C or later coprocessor)
RSA	RSA processing is to occur.
ECDSA	The elliptic curve digital signature algorithm is to be used. When specified, this is the only keyword permitted in the Rule Array.

private_key_identifier_length

Direction	Type
Input	Integer

The length of the private_key_identifier field. The maximum size is 3500 bytes.

private_key_identifier

Direction	Type
Input	String

This is an internal token or label of an RSA or ECC private key or Retained key. If the signature format is X9.31, the modulus of the RSA key must have a length of at least 1024 bits.

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.

hash_length

Direction	Type
Input	Integer

The length of the hash parameter in bytes. It must be the exact length of the text to sign. The maximum size is bytes. 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, then the maximum length is 512 bytes.

The hash 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 use only keys is 512 bytes. This access control point is always disabled by default in the domain role. You must have a TKE workstation to enable it.

hash

Direction	Type
Input	String

The application-supplied text on which to generate the signature. The input text must have been previously hashed, and for PKCS formatting, it must be BER-encoded as previously described. For X9.31, the hash algorithms must have been either SHA-1 or RIPEMD-160. See the rule_array parameter for more information.

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 is 512 bytes.

Note: 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 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 is 2 * 521 bits. For brain pool curves, the maximum size is 2 * 512 bits.

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
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.

X9.31 requires the RSA token to have a modulus bit length of at least 1024 bits and the length must also be a multiple of 256 bits (or 32 bytes).

The length of the hash parameter in bytes. It must be the exact length of the text to sign. The maximum size is 512 bytes. 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, then the maximum length is 512 bytes.

For CCA RSA keys, the hash length limit is controlled by the DSG ZERO-PAD unrestricted hash length access 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 Applicationsz/OS Cryptographic Services ICSF Writing PKCS #11 Applicationsz/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.

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' inz/OS Cryptographic Services ICSF Writing PKCS #11 Applications.

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.

This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service.