Key Generate (CSNBKGN and CSNEKGN)

CALL CSNBKGN(
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             key_form,
             key_length,
             key_type_1,
             key_type_2,
             KEK_key_identifier_1,
             KEK_key_identifier_2,
             generated_key_identifier_1,
             generated_key_identifier_2 ) 

return_code

Direction	Type
Output	Integer

The return code specifies the general result of the callable service. ICSF and cryptographic coprocessor return and 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 that indicate specific processing problems. ICSF and cryptographic coprocessor return and 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.

key_form

Direction	Type
Input	Character String

A 4-byte keyword that defines the type of key or keys 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 1 for their meanings.

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

Table 1. Key Form values for the Key Generate callable service

Keyword	Meaning
EX	One key that can be sent to another system.
EXEX	A key pair; both keys to be sent elsewhere, possibly for exporting to two different systems. The key pair has the same clear value.
IM	One key that can be locally imported. The key can be imported onto this system to make it operational at another time.
IMEX	A key pair to be imported; one key to be imported locally and one key to be sent elsewhere. Both keys have the same clear value.
IMIM	A key pair to be imported; both keys to be imported locally at another time.
OP	One operational key. The key is returned to the caller in the key token format. Specify the OP key form when generating AES keys.
OPEX	A key pair; one key that is operational and one key to be sent from this system. Both keys have the same clear value.
OPIM	A key pair; one key that is operational and one key to be imported to the local system. Both keys have the same clear value. On the other system, the external key token can be imported to make it operational.
OPOP	A key pair; normally with different control vector values.

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.

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 6 for valid key combinations.

key_length

Direction	Type
Input	Character String

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.

Table 2. Key Length values for the Key Generate callable service

Value	Description	Algorithm
SINGLE or KEYLN8	The key should be a single length (8-byte) key.	DES
SINGLE-R	The key should be a double length (16-byte) key. The two key halves will be the same. This makes the key effectively a single length key.	DES
DOUBLE or KEYLN16	The key should be a double length (16-byte or 128-bit) key	AES or DES
DOUBLE-O	The key should be a double length (16-byte) key. Each of the two key halves will be unique (not the same value).	DES
KEYLN24	The key should be a 24-byte (192-bit) key.	AES or DES
KEYLN32	The key should be a 32-byte (256-bit) key.	AES

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, DOUBLE-O 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.

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 KEYLN24. A 256-bit AES key requires a key_length of KEYLN32. All AES keys are DATA keys.

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.

Table 3. Key lengths for DES keys

Key Type	Single - KEYLN8	Single-R	Double - KEYLN16	DOUBLE-O	KEYLN24
MAC MACVER	X X	X X	X X	X X
DATA	X		X		X
DATAC* DATAM DATAMV		X X X	X X X	X X X
EXPORTER IMPORTER	Y Y	X X	X X	X X
IKEYXLAT   OKEYXLAT	Y Y	X X	X X	X X
CIPHER DECIPHER ENCIPHER	X X X	X X X	X X X	X X X
IPINENC OPINENC PINGEN PINVER	Y Y Y Y	X X X X	X X X X	X X X X
CVARDEC* CVARENC* CVARPINE* CVARXCVL* CVARXCVR*	X X X X X	X X X X X	X X X X X
DKYGENKY* KEYGENKY*		X X	X X	X X
CIPHERXI CIPHERXL CIPHERXO			X X X	X X X

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.

Table 4. Key lengths for AES keys

Key Type	128-byte	192-byte	256-byte
AESTOKEN AESDATA	X X	X X	X X

key_type_1

Direction	Type
Input	Character String

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, CIPHERXI, CIPHERXL, CIPHERXO, DATA, DATAC, DATAM, DATAMV, DECIPHER, ENCIPHER, EXPORTER, IKEYXLAT, IMPORTER, IPINENC, MAC, MACVER, OKEYXLAT, OPINENC, PINGEN and PINVER
• or the keyword TOKEN

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.

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 5 and Table 6 for valid key type and key form combinations.

key_type_2

Direction	Type
Input	Character String

Use the key_type_2 parameter for a key pair, which is shown in Table 6. 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.

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

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

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 5 and Table 6 for valid key type and key form combinations.

KEK_key_identifier_1

Direction	Type
Input/Output	String

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.

The NOCV bit is shown in Table 1.

KEK_key_identifier_1 cannot be an AES key token or label.

KEK_key_identifier_2

Direction	Type
Input/Output	String

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.

The NOCV bit is shown in Table 1.

KEK_key_identifier_2 cannot be an AES key token or label.

generated_key_identifier_1

Direction	Type
Input/Output	String

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 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.

generated_key_identifier_2

Direction	Type
Input/Output	String

This parameter specifies either a generated:

• internal DES key token or
• external DES key token enciphered under KEK_key_identifier_2.

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.

This callable service does not support version X'10' external DES key tokens (RKX key tokens).

SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS.

For key types CIPHERXI, CIPHERXL, and CIPHERXO, the key-encrypting keys in the KEK_key_identifier_1 and KEK_key_identifier_2 parameters must have a control vector with the key halves guaranteed unique flag on in the key form bits. An existing key-encrypting key can have its control vector updated using the restrict key attribute callable service.

Table 6 shows the valid key type and key form combinations for a DES key pair. Key types marked with an "*" must be requested through the specification of a proper control vector in a key token and through the use of the TOKEN keyword.

See Table 7 for an explanation of the differences between E as compared to X.

If you need to use NOCV key-encrypting keys, you need to enable NOCV IMPORTER and NOCV EXPORTER access control points

The following table shows the access control points in the domain role that control the function of this service.

To use a NOCV IMPORTER key-encrypting key with the key generate service, the NOCV KEK usage for import-related functions access control point must be enabled in addition to one or both of the access control points listed.

To use a NOCV EXPORTER key-encrypting key with the key generate service, the NOCV KEK usage for export-related functions access control point must be enabled in addition to one or both of the access control points listed.

To use the SINGLE-R rule array keyword, the Key Generate – SINGLE-R access control point must be enable.

When the Disallow 24-byte DATA wrapped with 16-byte Key access control point is enabled, this service will fail if the source key is a triple-length DATA key and the DES master key is a 16-byte key or the key-encrypting key is a double-length key.

Table 8 lists the required cryptographic hardware for each server type and describes restrictions for this callable service.