One-Way Hash Generate (CSNBOWH or CSNBOWH1 and CSNEOWH or CSNEOWH1)

Use the One-Way Hash Generate callable service to generate a one-way hash or provide an extendable-output function on specified text. This service supports the following methods:

Table 1. Blocksize and hash length for hash methods
Hash method	Blocksize (in bytes)	Hash length (in bytes)
BCRYPT	72	60
MD5	64	16
RPMD-160	64	20
SHA-1	64	20
SHA-224	64	28^{^}
SHA-256	64	32
SHA-384	128	48^{^}
SHA-512	128	64
SHA3-224	144	28
SHA3-256	136	32
SHA3-384	104	48
SHA3-512	72	64
SHAKE128	168	^*
SHAKE256	136	^*

^: See description in the hash_length parameter for additional requirements.
*: Extendable-output functions can generate any non-zero length.

The callable service names for AMODE(64) invocation are CSNEOWH and CSNEOWH1.

Format

CALL CSNBOWH(
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             rule_array_count,
             rule_array,
             text_length,
             text,
             chaining_vector_length,
             chaining_vector,
             hash_length,
             hash)

CALL CSNBOWH1(
              return_code,
              reason_code,
              exit_data_length,
              exit_data,
              rule_array_count,
              rule_array,
              text_length,
              text,
              chaining_vector_length,
              chaining_vector,
              hash_length,
              hash,
              text_id_in)

Parameters

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 must be 1 or 2.

rule_array

Direction	Type
Input	String

Keywords that provide control information to the callable service are listed in Table 2. The optional chaining flag keyword indicates whether calls to this service are chained together logically to overcome buffer size limitations. 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 2. Keywords for One-Way Hash Generate Rule Array Control Information
Keyword	Meaning
*Hash Method (required)*
BCRYPT	Hash algorithm is BCRYPT version 2b. May not be specified with a chaining rule.
MD5	Hash algorithm is MD5 algorithm. Use this hash method for PKCS-1.0 and PKCS-1.1.
MD5-LG	Hash algorithm is similar to the MD5 algorithm. Legacy hash values from release HCR7751 and lower prior to APAR OA33657 will be generated for verification purposes with previously archived hash values.
RPMD-LG	Hash algorithm is similar to the RIPEMD-160. Legacy hash values from release HCR7751 and lower prior to APAR OA33657 will be generated for verification purposes with previously archived hash values.
RPMD-160	Hash algorithm is RIPEMD-160.
SHA-1	Hash algorithm is SHA-1 algorithm. Use this hash method for DSS.
SHA-224	Hash algorithm is SHA-224 algorithm.
SHA-256	Hash algorithm is SHA-256 algorithm.
SHA-384	Hash algorithm is SHA-384 algorithm.
SHA-512	Hash algorithm is SHA-512 algorithm.
SHA3-224	Hash algorithm is SHA3-224 algorithm.
SHA3-256	Hash algorithm is SHA3-256 algorithm.
SHA3-384	Hash algorithm is SHA3-384 algorithm.
SHA3-512	Hash algorithm is SHA3-512 algorithm.
SHAKE128	Extendable-output function is SHAKE-128.
SHAKE256	Extendable-output function is SHAKE-256.
SHA1LG	Hash algorithm is similar to the SHA-1 algorithm. Use only when text_length is greater than or equal to 256 megabytes (512 megabytes on IBM Z 990, IBM Z 890, or later hardware on HCR7770). Legacy hash values from release HCR7770 and higher prior to APAR OA43937 will be generated for verification purposes with previously archived hash values.
SHA224LG	Hash algorithm is similar to the SHA-224 algorithm. Use only when text_length is greater than or equal to 256 megabytes (512 megabytes on IBM Z 990,IBM Z 890, or later hardware on HCR7770). Legacy hash values from release HCR7770 and higher prior to APAR OA43937 will be generated for verification purposes with previously archived hash values.
SHA256LG	Hash algorithm is similar to the SHA-256 algorithm. Use only when text_length is greater than or equal to 256 megabytes (512 megabytes on IBM Z 990, IBM Z 890, or later hardware on HCR7770). Legacy hash values from release HCR7770 and higher prior to APAR OA43937 will be generated for verification purposes with previously archived hash values.
SHA384LG	Hash algorithm is similar to the SHA-384 algorithm. Use only when text_length is greater than or equal to 256 megabytes (512 megabytes on IBM Z 990, IBM Z 890, or later hardware on HCR7770). Legacy hash values from release HCR7770 and higher prior to APAR OA43937 will be generated for verification purposes with previously archived hash values.
SHA512LG	Hash algorithm is similar to the SHA-512 algorithm. Use only when text_length is greater than or equal to 256 megabytes (512 megabytes on IBM Z 990, IBM Z 890, or later hardware on HCR7770). Legacy hash values from release HCR7770 and higher prior to APAR OA43937 will be generated for verification purposes with previously archived hash values.
*Chaining Flag (optional)*
FIRST	Specifies this is the first call in a series of chained calls. For hash method keywords other than the SHA3 family or SHAKE family, intermediate results are stored in the hash field.
LAST	Specifies this is the last call in a series of chained calls.
MIDDLE	Specifies this is a middle call in a series of chained calls. For hash method keywords other than the SHA3 family or SHAKE family, intermediate results are stored in the hash field.
ONLY	Specifies this is the only call and the call is not chained. This is the default.
*Salt Flag (required with BCRYPT)*
GENERATE	Generates hash from random salt.
VERIFY	Verifies input hash parameter.

text_length

Direction	Type
Input	Integer

The length of the text parameter in bytes. For more information, see Table 1.

Note: If you specify the FIRST or MIDDLE keyword, then the text length must be a multiple of the blocksize of the hash method. For MD5, RPMD-160, SHA-1, SHA-224 and SHA-256, this is a multiple of 64 bytes. For SHA-384 and SHA-512, this is a multiple of 128 bytes.

For ONLY and LAST, this service performs the required padding according to the algorithm specified.

text

Direction	Type
Input	String

The application-supplied text on which this service performs the hash.

chaining_vector_length

Direction	Type
Input	Integer

The byte length of the chaining_vector parameter. For hash method keywords other than the SHA3 family or SHAKE family, this must be 128 bytes. For hash method keywords in the SHA3 family or SHAKE family, this must be 256 bytes.

For hash method BCRYPT, this must be 1 byte when the GENERATE rule is used and must be 0 bytes when the VERIFY rule is used.

chaining_vector

Direction	Type
Input/Output	String

This field is a 128-byte or 256-byte work area. Your application must not change the data in this string. The chaining vector permits chaining data from one call to another.

For hash method BCRYPT, the first byte of the chaining vector contains the cost of the hash when GENERATE rule is used. The cost value must be between 4 and 31, inclusive and must be empty when VERIFY rule is used.

hash_length

Direction	Type
Input	Integer

The length of the hash field in bytes. See Table 1 for the minimum lengths. For SHAKE128 and SHAKE256, the length can be any non-zero value. On ONLY or LAST, the length specified here is generated into the hash parameter.

Note: The length of the SHA-224 hash is 28 bytes and the length of the SHA-384 hash is 48 bytes. The extra bytes (4 bytes for SHA-224 and 16 bytes for SHA-384) are used during the generation of the hash value. The final hash value is left-justified and padded with zeroes.

hash

Direction	Type
Input/Output	String

This field contains the hash or extended-output-function (XOF) message digest, left-justified. For hash method keywords other than the SHA3 family or SHAKE family, if you specify the FIRST or MIDDLE keyword, this field contains the intermediate hash value. Your application must not change the data in this field between the sequence of FIRST, MIDDLE, and LAST calls for a specific message.

For SHAKE128 and SHAKE256, when ONLY or LAST is specified, the extended-output-function (XOF) message digest generates the number of bytes specified for hash_length.

For BCRYPT, when using the VERIFY keyword, this field is expected to be an ASCII string containing a cost, salt, and hash in a shadow password format. See Table 3 for more information about the structure of shadow password format.

text_id_in

Direction	Type
Input	Integer

For CSNBOWH1 only, the ALET for the data space containing the text for which to generate the hash.

Usage notes

Although some hashing methods allow it, bit length text is not supported for any hashing method.

If the CSF.CSFSERV.AUTH.CSFOWH.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.CSFOWH.DISABLE is not defined, the SAF authorization check will be performed. Disabling the SAF check may improve the performance of your application.

For hash method BCRYPT, the UNIX shadow password format, also known as the Modular Crypt Format, is used for the hash being generated or verified. This is a string of ASCII character that has the following structure:

Table 3. Shadow password format for BCRYPT
Offset	Length	Description
0	4	Hash algorithm identifier.
4	2	Cost.
6	1	Single-character delimiter, always '$'.
7	22	Base64 encoding of the salt.
29	31	Base64 encoding of the hash.

Required hardware

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.

Table 4. One-Way Hash Generate required hardware
Server	Required cryptographic hardware	Restrictions
IBM z14 IBM z14 ZR1	CP Assist for Cryptographic Functions
IBM z15 IBM z15 T02	CP Assist for Cryptographic Functions
IBM z16 IBM z16 A02	CP Assist for Cryptographic Functions