One-Way Hash Generate (CSNBOWH or CSNBOWH1 and CSNEOWH or CSNEOWH1)
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
-
The application-supplied text on which this service performs the hash.
Direction Type Input String - 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.
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.
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
|