Random Number Generate (CSNBRNG, CSNERNG, CSNBRNGL and CSNERNGL)

CALL CSNBRNG(
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             form,
             random_number ) 

CALL CSNBRNGL(
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             rule_array_count,
             rule_array,
             key_identifier_length,
             key_identifier,
             random_number_length,
             random_number ) 

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

form

Direction	Type
Input	Character String

The 8-byte keyword for the CSNBRNG service that defines the characteristics of the random number should be left-justify and pad on the right with blanks. The keywords are listed in Table 1.

Table 1. Keywords for the Form Parameter

Keyword	Meaning
EVEN	Generate a 64-bit random number with even parity in each byte.
ODD	Generate a 64-bit random number with odd parity in each byte.
RANDOM	Generate a 64-bit random number.

Parity is calculated on the 7 high-order bits in each byte and is presented in the low-order bit in the byte.

rule_array_count

Direction	Type
Input	Integer

The number of keywords for the CSNBRNGL service you are supplying in the rule_array parameter. The value must be 1 or 2.

rule_array

Direction	Type
Input	String

The keyword for the CSNBRNGL service that provides control information to the callable service. The recovery method is the method to use to recover the symmetric key. The keyword is left-justified in an 8-byte field and padded on the right with blanks. All keywords must be in contiguous storage.

Table 2. Keywords for Random Number Generate Control Information

Keyword	Meaning
Requested service (one, required).
EVEN	Specifies that each generated random byte is adjusted for even parity.
ODD	Specifies that each generated random byte is adjusted for odd parity.
RANDOM	Specifies that each generated random byte is not adjusted for parity.
RT-KRD	Specifies that the generated random number is returned formatted as a TR-34 Key Receiving Device Random Number Token (RT-KRD). The token requires 21 additional bytes for encoding and overhead. The random number is not adjusted for parity. Note the maximum size of the token that is usable with the service that the token is planned to be used with. If the maximum size is 200 bytes, the maximum random number size is 179 bytes.
Encryption Process (one, optional). Not valid with the RT-KRD keyword.
TDES-CBC	Specifies to return the random number encrypted using the DES key specified in the key_identifier parameter. Note: A CCA Crypto Express coprocessor must be active to get encrypted output.

key_identifier_length

Direction	Type
Input	Integer

The length of the key_identifier parameter in bytes.

When the rule array keyword TDES-CBC is specified and when:

• The key_identifier parameter contains a label, the value must be 64.
• The key_identifier parameter contains a key token, the value must be between the actual length of the key token and 9992.

Otherwise, the value must be 0.

key_identifier

Direction	Type
Input	String

The identifier of the key to encrypt the random number. The key identifier is an operational token or the key label of an operational token in key storage.

When the TDES-CBC keyword is specified:

• For CCA keys, the identifier is a 64-byte DES key token of key type CIPHER or ENCIPHER and the key must be a double-length or triple-length key.
• For X9.143 keys, the identifier is a key block of a DES data-encrypting key usage D0, algorithm T, and mode of use B or E.

When the key_identifier_length parameter is 0, this parameter is ignored.

If the token supplied was encrypted under the old master key, the token will be returned encrypted under the current master key.

random_number_length

Direction	Type
Input/Output	Integer

This parameter contains the desired length of the random_number that is returned by the CSNBRNGL callable service. The minimum value is 1 byte; the maximum value is 8192 bytes.

When the requested service keyword is TDES-CBC, the value must be a multiple of 8. The maximum value is 1024.

When the requested service keyword is RT-KRD:

• On input, this value is the number of bytes of the random number requested plus 21 bytes for the DER encoding of the token. Note the maximum size of the token that is usable with the service that the token is planned to be used with. If the maximum size is 200 bytes, the maximum random number size is 179 bytes.
• On output, the value will be the actual size of the token returned.

random_number

Direction	Type
Output	String

The generated number returned by the CSNBRNG callable service is stored in an 8-byte variable.

The generated number returned by the CSNBRNGL callable service is stored in a variable that is at least random_number_length bytes long.

When the requested service keyword is RT-KRD, the TR-34 Key Receiving Device Random Number Token is returned.

If the CSF.CSFSERV.AUTH.CSFRNG.DISABLE SAF resource profile is defined in the XFACILIT SAF resource class, no SAF authorization checks will be performed against the CSFSERV class when using this service. If CSF.CSFSERV.AUTH.CSFRNG.DISABLE is not defined, the SAF authorization check will be performed. Disabling the SAF check may improve the performance of your application.

The CSNBRNG service requires that the Key Generate – SINGLE-R access control point is enabled. The CSNBRNGL service is not controlled by any access control.

The use of the TDES-CBC rule array keyword requires the Random Number Generate Long – TDES-CBC access control point is enabled.

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.