Parameters

z/OS Cryptographic Services ICSF Application Programmer's Guide

Parameters

z/OS Cryptographic Services ICSF Application Programmer's Guide
SA22-7522-16

return_code

Direction: Output

Type: Integer

The return code specifies the general result of the callable service. Appendix A. ICSF and TSS Return and Reason Codes lists the return codes.

reason_code

Direction: Output

Type: 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. Appendix A. ICSF and TSS Return and Reason Codes lists the reason codes.

exit_data_length

Direction: Input/Output

Type: Integer

The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter.

exit_data

Direction: Input/Output

Type: String

The data that is passed to the installation exit.

rule_array_count

Direction: Input

Type: Integer

The number of keywords you are supplying in the rule_array parameter. The rule_array_count parameter must be 3, 4, or 5.

rule_array

Direction: Input

Type: String

The rule_array contains keywords that provide control information to the callable service. The keywords are 8 bytes in length and must be left-aligned and padded on the right with space characters. The rule_array keywords for this callable service are shown in the following table.

Table 115. Keywords for TR-31 Export Rule Array Control Information
Keyword	Meaning
TR-31 key block protection method - one required
VARXOR-A	Use the variant method corresponding to a TR-31 Key Block Version ID of “A" (0x41)
VARDRV-B	Use the key derivation method corresponding to a TR-31 Key Block Version ID of “B" (0x42)
VARXOR-C	Use the variant method corresponding to a TR-31 Key Block Version ID of “C" (0x43)
TR-31 key usage values for output key - one required Note: If ATTR-CV is specified from the Control Vector Transport group, then usage keyword must not be specified. The proprietary usage ‘10' will be used.
BDK	Base Derivation Key (BDK) - ( B0 )
CVK	Card Verification Key (CVK) - ( C0 )
ENC	Data encryption key - ( D0 )
EMVACMK	EMV application cryptogram master key - ( E0 )
EMVSCMK	EMV secure messaging for confidentiality master key - ( E1 )
EMVSIMK	EMV secure messaging for integrity master key - ( E2 )
EMVDAMK	EMV data authentication code key - ( E3 )
EMVDNMK	EMV dynamic numbers master key - ( E4 )
EMVCPMK	EMV card personalization master key - ( E5 )
KEK	Key-encrypting key - ( K0 )
KEK-WRAP	Key-encrypting key for wrapping TR-31 blocks (for ‘B' and ‘C' TR-31 Key Block Version IDs only) - ( K1 )
ISOMAC0	Key for ISO 16609 MAC algorithm 1 using TDES - ( M0 )
ISOMAC1	Key for ISO 9797-1 MAC algorithm 1- ( M1 )
ISOMAC3	Key for ISO 9797-1 MAC algorithm 3- ( M3 )
PINENC	PIN encryption key - ( P0 )
PINVO	PIN verification key, “other" algorithm - ( V0 )
PINV3624	PIN verification key for IBM 3624 algorithm - ( V1 )
VISAPVV	PIN verification key, VISA PVV algorithm - ( V2 )
TR-31 modes of key use - one required Note: If ATTR-CV is specified from the Control Vector Transport group, then mode keyword must not be specified. The proprietary mode ‘1' will be used.
ENCDEC	Encrypt and decrypt - ( B )
DEC-ONLY	Decrypt only - ( D )
ENC-ONLY	Encrypt only - ( E )
GENVER	MAC or PIN generate and verify - ( C ) MAC key must have Gen and Ver bits on PIN key must have any PINGEN bit and EPINVER bit on
GEN-ONLY	MAC or PIN generate only - ( G ) MAC key must have only Gen bit on PIN key must have any PINGEN bit on and EPINVER bit off
VER-ONLY	MAC or PIN verify only- ( V ) MAC key must have only Ver bit on PIN key must have all PINGEN bits off and EPINVER bit on
DERIVE	Key Derivation(for ‘B' and ‘C' TR-31 Key Block Version IDs only) - ( X )
ANY	Any mode allowed - ( N )
Export control to set export field in TR-31 key block - optional
EXP-ANY	Export allowed using any key-encrypting key. This is the default.
EXP-TRST	Export allowed using a trusted key-encrypting key, as defined in TR-31. Note: A CCA key wrapped in the X9.24 compliant CCA key block is considered a trusted key.
EXP-NONE	Export prohibited
Control vector transport control - optional Note: If no keyword from this group is supplied, the CV in the `source_key_identifier` is still verified to agree with the ‘key usage' and ‘mode of use' keywords specified from the groups above.
INCL-CV	Include the CCA Control Vector as an optional field in the TR-31 key block header. The TR-31 usage and mode of use fields will indicate the key attributes, and those attributes (derived from the keywords passed from the above groups) will be verified by the callable service to be compatible with the ones in the included control vector.
ATTR-CV	Include the CCA Control Vector as an optional field in the TR-31 key block header. The TR-31 usage will be set to the proprietary ASCII value “10" (‘3130'x) to indicate usage information is specified in the included CV, and the mode of use will be set to the proprietary ASCII value “1" (‘31'x) to indicate that mode is likewise specified in the CV. Note: If this keyword is specified, then usage and mode keywords from the preceding groups must not be specified. The proprietary values will be used.

key_version_number

Direction: Input

Type: String

The two bytes from this parameter are copied into the Key Version Number field of the output TR-31 key block. If no key version number is needed, the value must be 0x3030 (“00"). If the CCA key in parameter source_key_identifier is a key part (CV bit 44 is 1) then the key version number in the TR-31 key block is set to “c0" (0x6330) according to the TR-31 standard, which indicates that the TR-31 block contains a key part. In this case, the value passed to the callable service in the key_version_number parameter is ignored.

key_field_length

Direction: Input

Type: Integer

This parameter specifies the length of the key field which is encrypted in the TR-31 block. The length must be a multiple of 8, the DES cipher block size, and it must be greater than or equal to the length of the cleartext key passed with parameter source_key_identifier plus the length of the 2-byte key length that precedes this key in the TR-31 block. For example, if the source key is a double-length TDES key of length 16 bytes, then the key field length must be greater than or equal to (16+2) bytes, and must also be a multiple of 8. This means that the minimum key_field_length in this case would be 24. TR-31 allows a variable number of padding bytes to follow the cleartext key, and the caller may choose to pad with more than the minimum number of bytes needed to form a block that is a multiple of 8. This is generally done to hide the length of the cleartext key from those who cannot decipher that key. Most often, all keys - single, double, or triple length - are padded to the same length so that it is not possible to determine which length is carried in the TR-31 block by examining the encrypted block.

Note that this parameter is not expected to allow for ASCII encoding of the encrypted data stored in the key field according to the TR-31 specification. For example when the user passes a value of 24 here, following the minimum example above, the length of the final ASCII-encoded encrypted data in the key field in the output TR-31 key block will be 48 Bytes.

source_key_identifier_length

Direction: Input

Type: Integer

This parameter specifies the length of the source_key_identifier parameter, in bytes. The value in this parameter must currently be 64, since only CCA key tokens are supported for the source key parameter.

source_key_identifier

Direction: Input/Output

Type: String

This parameter contains either the label or the key token for the key that is to be exported. The key must be a CCA internal or external token. If the source key is an external token, an identifier for the KEK that wraps the source key must be passed in the unwrap_kek_identifier parameter. Only DES/TDES keys are supported. If a key token is passed which is wrapped under the old master key, it will be updated on output so that it is wrapped under the current master key.

unwrap_kek_identifier_length

Direction: Input

Type: Integer

This parameter specifies the length of the unwrap_kek_identifier parameter, in bytes. If the source_key_identifier is an external CCA token, then this parameter must be 64. Otherwise, this parameter must be 0.

unwrap_kek_identifier

Direction: Input/Output

Type: String

When the source_key_identifier is an external CCA token, this parameter contains either the label or the key token for the KEK which the source_key_identifier is currently wrapped under. It must be a CCA internal DES KEK token of type EXPORTER or OKEYXLAT. If the source_key_identifier is not an external CCA token, this parameter is ignored. If a key token is passed which is wrapped under the old master key, it will be updated on output so that it is wrapped under the current master key.

wrap_kek_identifier_length

Direction: Input

Type: Integer

This parameter specifies the length of the wrap_kek_identifier parameter, in bytes. If the unwrap_kek_identifier is also to be used to wrap the output TR-31 key block, specify 0 for this parameter. Otherwise, this parameter must be 64.

wrap_kek_identifier

Direction: Input/Output

Type: String

When wrap_kek_identifier_length is 0, this parameter is ignored and the unwrap_kek_identifier is also to be used to wrap the output TR-31 key block . Otherwise, this parameter contains either the label or the key token for the KEK to use for wrapping the output TR-31 key block. It must be a CCA internal token for a KEK EXPORTER or OKEYXLAT type and must have the same clear key as the unwrap_kek_identifier. If a key token is passed which is wrapped under the old master key, it will be updated on output so that it is wrapped under the current master key.

Note:

ECB-mode wrapped DES keys (CCA legacy wrap mode) cannot be used to wrap/unwrap TR-31 version ‘B'/'C' key blocks that have/will have ‘E' exportability, because ECB-mode does not comply with ANSI X9.24 Part 1.

This parameter exists to allow for KEK separation, it is possible that KEKs will be restricted as to what they can wrap, such that a KEK for wrapping CCA external keys may not be usable for wrapping TR-31 external keys, or vice versa.

opt_blks_length

Direction: Input

Type: Integer

This parameter specifies the length of parameter opt_blocks in bytes. If no optional data is to be included in the TR-31 key block, this parameter must be set to zero.

opt_blocks

Direction: Input

Type: String

This parameter contains optional block data which is to be included in the output TR-31 key block. The optional block data is prepared using the TR-31 Optional Data Build callable service, and must be in ASCII. This parameter is ignored if opt_blks_length is zero.

TR31_key_block_length

Direction: Input/Output

Type: Integer

This parameter specifies the length of the TR31_key_block parameter, in bytes. On input, it must specify the size of the buffer available for the output TR-31 key block, and on return it is updated to contain the actual length of that returned key block. If the provided buffer is not large enough for the output TR-31 key block an error is returned. The maximum size of the output TR-31 key block is 9992 bytes.

TR31_key_block

Direction: Output

Type: String

This parameter specifies the location of the exported TR-31 key block wrapped with the export key provided in the wrap_kek_identifier parameter.

Notices | Terms of use | Support | Contact z/OS | zFavorites