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 that indicate specific processing problems. Appendix A. ICSF and TSS Return and Reason Codes lists the reason codes.

exit_data_length

Direction: Ignored

Type: Integer

This field is ignored. It is recommended to specify 0 for this parameter.

exit_data

Direction: Ignored

Type: String

This field is ignored.

rule_array_count

Direction: Input

Type: Integer

The number of keywords you supplied in the rule_array parameter. The minimum value is 3, and the maximum value is 33.

rule_array

Direction: Input

Type: Integer

The rule_array contains keywords that provide control information to the callable service. The keywords must be in contiguous storage with each of the keywords left-justified in its own 8-byte location and padded on the right with blanks.

Table 63. Keywords for Key Token Build2 Control Information
Keyword	Meaning
Token type (one required)
EXTERNAL	Specifies to build an external key token.
INTERNAL	Specifies to build an internal key token.
Token algorithm (one required)
AES	Specifies to build an AES key token.
HMAC	Specifies to build an HMAC key token.
Key status (one, optional)
KEY-CLR	Specifies to build the key token with a clear key value. This creates a key token that can be used with the Key Test2 service to generate a verification pattern for the key value.
NO-KEY	Specifies to build the key token without a key value. This creates a skeleton key token that can later be supplied to the Key Generate2 service. This is the default.
Key type (one required)
CIPHER	Specifies that this key is for an AES CIPHER key. Only valid for AES algorithm.
EXPORTER	Specifies that this key is for an AES KEK EXPORTER. Only valid for AES algorithm.
IMPORTER	Specifies that this key is for an AES KEK IMPORTER. Only valid for AES algorithm.
MAC	Specifies that this key is for message authentication code operations. Only valid for HMAC algorithm.
Key-management related keywords
Symmetric-key export control (one, optional) Key-management field 1 for all algorithms and key types.
NOEX-SYM	Prohibits the export of the key with a symmetric key.
XPRT-SYM	Permits the export of the key with a symmetric key. This is the default.
Unauthenticated asymmetric-key export control (one, optional) Key-management field 1 for all algorithms and key types.
NOEXUASY	Prohibits the export of the key with an unauthenticated asymmetric key.
XPRTUASY	Permits the export of the key with an unauthenticated asymmetric key. This is the default.
Authenticated asymmetric-key export control (one, optional) Key-management field 1 for all algorithms and key types.
NOEXAASY	Prohibits the export of the key with an authenticated asymmetric key.
XPRTAASY	Permits the export of the key with an authenticated asymmetric key. This is the default.
RAW-format export control (one, optional) Key-management field 1 for all algorithms and key types.
NOEX-RAW	Prohibits the export of the key in RAW format. This is the default.
XPRT-RAW	Permits the export of the key in RAW format.
DES-key export control (one, optional) Key-management field 1 for all algorithms, all key types.
NOEX-DES	Prohibits the export of the key using DES key.
XPRT-DES	Permits the export of the key using DES key. This is the default.
AES-key export control (one, optional) Key-management field 1 for all algorithms, all key types.
NOEX-AES	Prohibits the export of the key using AES key.
XPRT-AES	Permits the export of the key using AES key. This is the default.
RSA-key export control (one, optional) Key-management field 1 for all algorithms, all key types.
NOEX-RSA	Prohibits the export of the key using RSA key.
XPRT-RSA	Permits the export of the key using RSA key. This is the default.
Key-usage keywords (these are specific to the key type specified)
Generate control (one required) Key-usage field 1 for HMAC algorithm, MAC key type.
GENERATE	Specifies that this key can be used to generate a MAC. A key that can generate a MAC can also verify a MAC.
VERIFY	Specifies that this key cannot be used to generate a MAC. It can only be used to verify a MAC.
Encrypt control (optional, any combination) Key-usage field 1 for AES algorithm, CIPHER key type. Note: All keywords in the list below are defaults unless one or more keywords in the list are specified.
ENCRYPT	Specifies that this key can be used to encipher data using the AES algorithm.
DECRYPT	Specifies that this key can be used to decipher data using the AES algorithm.
Exporter control (any combination, optional) Key-usage field 1 for AES algorithm, EXPORTER key type. Note: All keywords in the list below are defaults unless one or more keywords in the list are specified.
EXPORT	Specifies that this key can be used for export.
TRANSLAT	Specifies that this key can be used for translate.
GEN-OPEX	Specifies that this key can be used for generate OPEX.
GEN-IMEX	Specifies that this key can be used for generate IMEX.
GEN-EXEX	Specifies that this key can be used for generate EXEX.
GEN-PUB	Specifies that this key can be used for generate PUB.
Importer control (any combination, optional) Key-usage field 1 for AES algorithm, IMPORTER key type. Note: All keywords in the list below are defaults unless one or more keywords in the list are specified.
IMPORT	Specifies that this key can be used for import.
TRANSLAT	Specifies that this key can be used for translate.
GEN-OPIM	Specifies that this key can be used for generate OPIM.
GEN-IMEX	Specifies that this key can be used for generate IMEX.
GEN-IMIM	Specifies that this key can be used for generate IMIM.
GEN-PUB	Specifies that this key can be used for generate PUB.
User-defined extension control (any combination, optional) Low-order byte of key-usage field 1 for all algorithms and key types. Note: The default is such that the key can be used in both UDXs and CCA and none of the user-defined UDX bits are set.
UDX-ONLY	Specifies that this key can only be used in UDXs.
UDX-001	Specifies that the rightmost user-defined UDX bit is set.
UDX-010	Specifies that the middle user-defined UDX bit is set.
UDX-100	Specifies that the leftmost user-defined UDX bit is set.
Hash method control (any combination, optional) Key-usage field 2 for HMAC algorithm, MAC key type. Note: All keywords in the list below are defaults unless one or more keywords in the list are specified.
SHA-1	Specifies that the SHA-1 hash method is allowed for the key.
SHA-224	Specifies that the SHA-224 hash method is allowed for the key.
SHA-256	Specifies that the SHA-256 hash method is allowed for the key.
SHA-384	Specifies that the SHA-384 hash method is allowed for the key.
SHA-512	Specifies that the SHA-512 hash method is allowed for the key.
Mode control (one, optional) Key-usage field 2 for AES algorithm, CIPHER key type.
CBC	Specifies that this key can be used for cipher block chaining. This is the default.
CFB	Specifies that this key can be used for cipher feedback.
ECB	Specifies that this key can be used for electronic code book.
GCM	Specifies that this key can be used for Galois/counter mode.
OFB	Specifies that this key can be used for output feedback.
XTS	Specifies that this key can be used for Xor-Encrypt-Xor-based Tweaked Stealing.
Key-encrypting key control (any combination, optional) Key-usage field 2 for AES algorithm, EXPORTER or IMPORTER key type. Note: The default is such that the key cannot export a RAW key nor wrap or unwrap a TR-31 key block.
KEK-RAW	Specifies that this key-encrypting key can export a RAW key. A RAW key is a key that is encrypted but does not have any associated data.
WR-TR31	Specifies that this key-encrypting key can wrap or unwrap a TR-31 key block
Key-usage wrap algorithm control (any combination, optional) Key-usage field 3 for AES algorithm, EXPORTER or IMPORTER key type. Note: Keywords WR-DES, WR-AES, and WR-HMAC are defaults unless one or more keywords are specified.
WR-DES	Specifies that this key can be used to wrap DES keys.
WR-AES	Specifies that this key can be used to wrap AES keys.
WR-HMAC	Specifies that this key can be used to wrap HMAC keys.
WR-RSA	Specifies that this key can be used to wrap RSA keys.
WR-ECC	Specifies that this key can be used to wrap ECC keys.
Key-usage wrap class control (any combination, optional) Key-usage field 4 for AES algorithm, EXPORTER or IMPORTER key type. Note: All keywords in the list below are defaults unless one or more keywords in the list are specified.
WR-DATA	Specifies that this key can be used to wrap DATA class keys.
WR-KEK	Specifies that this key can be used to wrap KEK class keys.
WR-PIN	Specifies that this key can be used to wrap PIN class keys.
WRDERIVE	Specifies that this key can be used to wrap DERIVATION class keys.
WR-CARD	Specifies that this key can be used to wrap CARD class keys.

clear_key_bit_length

Direction: Input

Type: Integer

The length of the clear key in bits. Specify 0 when no key value is supplied (Key status rule NO-KEY). Specify a valid key bit length when a key value is supplied (Key status rule KEY-CLR):

For HMAC algorithm, MAC key type, this is a value between 80 and 2048.
For AES algorithm, CIPHER/EXPORTER/IMPORTER key types, this is a value of 128, 192, or 256.

clear_key_value

Direction: Input

Type: String

This parameter is used when the KEY-CLR keyword is specified. This parameter is the clear key value to be put into the token being built.

key_name_length

Direction: Input

Type: Integer

The length of the key_name parameter. Valid values are 0 and 64.

key_name

Direction: Input

Type: String

A 64-byte key store label to be stored in the associated data structure of the token.

user_associated_data_length

Direction: Input

Type: Integer

The length of the user-associated data. The valid values are 0 to 255 bytes.

user_associated_data

Direction: Input

Type: String

User-associated data to be stored in the associated data structure.

token_data_length

Direction: Input

Type: Integer

This parameter is reserved. The value must be zero.

token_data

Direction: Ignored

Type: String

This parameter is ignored.

reserved_length

Direction: Input

Type: Integer

This parameter is reserved. The value must be zero.

reserved

Direction: Ignored

Type: String

This parameter is ignored because reserved_length must be zero.

target_key_token_length

Direction: Input/Output

Type: Integer

On input, the length of the target_key_token parameter supplied to receive the token. On output, the actual length of the token returned to the caller. Maximum length is 725 bytes.

target_key_token

Direction: Output

Type: String

The key token built by this service.

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