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

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.

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.

The data that is passed to the installation exit.

A 4-byte keyword that defines the type of key(s) you want to generate. This parameter also specifies if each key should be returned for either operational, importable, or exportable use. The keyword must be in a 4-byte field, left-justified, and padded with blanks.

The first two characters refer to key_type_1. The next two characters refer to key_type_2.

These keywords are allowed: OP, IM, EX, OPIM, OPEX, IMEX, EXEX, OPOP, and IMIM. See Table 27 for their meanings.

If the key_form is OP, EX or IM, the KEK_key_identifier_2, generated_key_identifier_1 and generated_key_identifier_2 should be set to NULL.

The key forms are defined as follows:

Operational (OP)

The key value is enciphered under a master key. The result is placed into an internal key token. The key is then operational at the local system. For AKEKs, the result is placed in a skeleton token created by the key token build callable service. AES AKEKs are not supported.

Importable (IM)

The key value is enciphered under an importer key-encrypting key. The result is placed into an external key token.

Exportable (EX)

The key value is enciphered under an exporter key-encrypting key. The result is placed into an external key token. The key can then be transported or exported to another system and imported there for use. This key form cannot be used by any ICSF callable service.

The keys are placed into tokens that the generated_key_identifier_1 and generated_key_identifier_2 parameters identify.

Valid key type combinations depend on the key form. See Table 34 for valid key combinations.

An 8-byte value that defines the length of the key. The keyword must be left-justified and padded on the right with blanks. You must supply one of the key length values in the key_length parameter.

DES Keys: Double-length (16-byte) keys have an 8-byte left half and an 8-byte right half. Both halves can have identical clear values or not. If you want the same value to be used in both key halves (refered to as replicated key values), specify key_length as SINGLE, SINGLE-R or KEYLN8. If you want different values to be the basis of each key half, specify key_length as DOUBLE or KEYLN16.

Triple-length (24-byte) keys have three 8-byte key parts. This key length is valid for DATA keys only. To generate a triple-length DATA key with three different values to be the basis of each key part, specify key_length as KEYLN24.

Use SINGLE/SINGLE-R if you want to create a DES transport key that you would use to exchange DATA keys with a PCF system. Because PCF does not use double-length transport keys, specify SINGLE so that the effects of multiple encipherment are nullified. When generating an AKEK, the key_length parameter is ignored. The AKEK key length (8-byte or 16-byte) is determined by the skeleton token created by the key token build callable service and provided in the generated_key_identifier_1 parameter.

Note:

SINGLE-R is not supported on IBM zSeries 900 servers.

AES Keys: AES only allows KEYLN16, KEYLN24, KEYLN32. To generate a 128-bit AES key, specify key_length as KEYLN16. For 192-bit AES keys specify key_length as KENLN24. A 256-bit AES key requires a key_length of KEYLN32. All AES keys are DATA keys.

Systems with CCFs (with or without PCICCs): This table shows the valid key lengths for each key type supported by DES keys. An X indicates that a key length is permitted for a key type. A Y indicates that the key generated will be a double-length key with replicated key values.

Systems with PCIXCCs/CEX2C/CEX3C: This table shows the valid key lengths for each key type supported by DES keys. An X indicates that a key length is permitted for a key type. A Y indicates that the key generated will be a double-length key with replicated key values. It is preferred that SINGLE-R be used for this result.

This table shows the valid key lengths for each key type supported by AES keys. An X indicates that a key length is permitted for that key type.

Use the key_type_1 parameter for the first, or only key, that you want generated. The keyword must be left-justified and padded with blanks. Valid type combinations depend on the key form.

The 8-byte keyword for the key_type_1 parameter can be one of the following:

• AESDATA, AESTOKEN, CIPHER, DATA, DATAC, DATAM, DATAMV, DATAXLAT, DECIPHER, ENCIPHER, EXPORTER, IKEYXLAT, IMPORTER, IPINENC, MAC, MACVER, OKEYXLAT, OPINENC, PINGEN and PINVER
• or the keyword TOKEN

For information on the meaning of the key types, see Table 3.

If key_type_1 is TOKEN, ICSF examines the control vector (CV) field in the generated_key_identifier_1 parameter to derive the key type. When key_type_1 is TOKEN, ICSF does not check for the length of the key for DATA keys. Instead, ICSF uses the key_length parameter to determine the length of the key.

To generate a DES AKEK, specify a key_type_1 of TOKEN. The generated_key_identifier_1 parameter must be a skeleton token of an AKEK created by the Key Token Build callable service. The token cannot be a partially notarized AKEK or an AKEK key part.

If key_type_1 is AESDATA or AESTOKEN, the key generated will be an AES key of type DATA. When key_type_1 is AESTOKEN, ICSF uses the key_length parameter to determine the length of the key.

See Table 33 and Table 34 for valid key type and key form combinations.

Use the key_type_2 parameter for a key pair, which is shown in Table 34. The keyword must be left-justified and padded with blanks. Valid type combinations depend on the key form. key_type_2 is only used when DES keys are generated.

key_type_2 is only use when DES keys are generated. The 8-byte keyword for the key_type_2 parameter can be one of the following:

• CIPHER, DATA, DATAC, DATAM, DATAMV, DATAXLAT, DECIPHER, ENCIPHER, EXPORTER, IKEYXLAT, IMPORTER, IPINENC, MAC, MACVER, OKEYXLAT, OPINENC, PINGEN and PINVER
• or the keyword TOKEN

For information on the meaning of the key types, see Description of Key Types, Table 3.

If key_type_2 is TOKEN, ICSF examines the control vector (CV) field in the generated_key_identifier_2 parameter to derive the key type. When key_type_2 is TOKEN, ICSF does not check for the length of the key for DATA keys. Instead, ICSF uses the key_length parameter to determine the length of the key.

If only one key is to be generated, key_type_2 and KEK_key_identifier_2 are ignored.

See Table 33 and Table 34 for valid key type and key form combinations.

A 64-byte string of a DES internal key token containing the importer or exporter key-encrypting key, or a key label. If you supply a key label that is less than 64-bytes, it must be left-justified and padded with blanks. KEK_key_identifier_1 is required for a key_form of IM, EX, IMEX, EXEX, or IMIM.

When key_form OP is used, parameters KEK_key_identifier_1 and KEK_key_identifier_2 are ignored. In this case, it is recommended that the parameters are initialized to 64-bytes of X'00'.

If the NOCV bit is on in the internal key token containing the key-encrypting key, the key-encrypting key itself (not the key-encrypting key variant) is used to encipher the generated key. For example, the key has been installed in the cryptographic key data set through the key generator utility program or the key entry hardware using the NOCV parameter; or you are passing the key-encrypting key in the internal key token with the NOCV bit on and your program is running in supervisor state or key 0-7.

Control vectors are explained in Control Vector for DES Keys and the NOCV bit is shown in Table 333.

KEK_key_identifier_1 cannot be an AES key token or label.

A 64-byte string of a DES internal key token containing the importer or exporter key-encrypting key, or a key label of an internal token. If you supply a key label that is less than 64-bytes, it must be left-justified and padded with blanks. KEK_key_identifier_2 is required for a key_form of OPIM, OPEX, IMEX, IMIM, or EXEX. This field is ignored for key_form keywords OP, IM and EX. When key_form OP is used, parameter KEK_key_identifier_2 is ignored. In this case, it is recommended that the parameter is initialized to 64-bytes of X'00'.

If the NOCV bit is on in the internal key token containing the key-encrypting key, the key-encrypting key itself (not the key-encrypting key variant) is used to encipher the generated key. For example, the key has been installed in the cryptographic key data set through the key generator utility program or the key entry hardware using the NOCV parameter; or you are passing the key-encrypting key in the internal key token with the NOCV bit on and your program is running in supervisor state or in key 0-7.

Control vectors are explained in Control Vector for DES Keys and the NOCV bit is shown in Table 333.

KEK_key_identifier_2 cannot be an AES key token or label.

This parameter specifies either a generated:

• Internal DES or AES key token for an operational key form, or
• External DES key tokens containing a key enciphered under the KEK_key_identifier_1 parameter.

If you specify a key_type_1 of TOKEN, then this field contains a valid DES token of the key type you want to generate. Otherwise, on input, this parameter must be binary zeros. See key_type_1 for a list of valid key types.

If you specify a key_type_1 of IMPORTER or EXPORTER and a key_form of OPEX, and if the generated_key_identifier_1 parameter contains a valid DES internal token of the SAME type, the NOCV bit, if on, is propagated to the generated key token.

When generating an AKEK, specify the skeleton key token created by the Key Token Build callable service as input for this parameter.

When key_type_1 parameter is AESDATA, then generated_key_identifier_1 is ignored. In this case, it is recommended that the parameter be initialized to 64-bytes of X'00'. If you specify a key_type_1 of AESTOKEN, the generated_key_identifier_1 parameter must be an internal AES key token or a clear AES key token. Information in this token can be used to determine the key type:

• The key_type_1 parameter overrides the type in the token.
• The key_length parameter overrides the length value in the generated key token.

ICSF supports two methods of wrapping the key value in a symmetric key token: the original ECB wrapping and an enhanced CBC wrapping method which is ANSI X9.24 compliant. The output generated_key_identifier_1 will use the default wrapping method unless a skeleton token is supplied as input. If a skeleton token is supplied as input, the wrapping method in the skeleton token will be used.

This parameter specifies a generated external key token containing a key enciphered under the KEK_key_identifier_2 parameter.

When key_type_1 parameter is AESDATA or AESTOKEN, then generated_key_identifier_2 is ignored. In this case, it is recommended that the parameters are initialized to 64-bytes of X'00'.

If you specify a key_type_2 of TOKEN, then this field contains a valid token of the key type you want to generate. Otherwise, on input, this parameter must be binary zeros. See key_type_1 for a list of valid key types.

The token can be an internal or external token.

ICSF supports two methods of wrapping the key value in a symmetric key token: the original ECB wrapping and an enhanced CBC wrapping method which is ANSI X9.24 compliant. The output generated_key_identifier_2 will use the default wrapping method unless a skeleton token is supplied as input. If a skeleton token is supplied as input, the wrapping method in the skeleton token will be used.