Parameters

The parameters for CSNBKTB.

For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see Parameters common to all verbs.

key_token

Direction:

Input/Output

Type:

String

The key_token parameter is a pointer to a string variable containing the assembled 64-byte fixed-length key token.

Note: This variable cannot contain a key label.

key_type

Direction:

Input

Type:

String

The key_type parameter is a pointer to a string variable containing a keyword that defines the key type. The keyword is eight bytes in length and must be left-aligned and padded on the right with space characters.

Key type	Description	Algorithm
CIPHER CIPHERXI CIPHERXL CIPHERXO	See DES key usage restrictions.	DES
CLRAES	The key_token parameter is a clear AES DATA key token. The rule_array must contain the keyword INTERNAL and one of the optional keywords: KEYLN16, KEYLN24, or KEYLN32. A key value parameter must also be provided.	AES
CLRDES	The key_token parameter is a clear DES DATA key token. The rule_array must contain the keyword INTERNAL and one of the optional keywords: KEYLN8, KEYLN16, or KEYLN24. A key value parameter must also be provided.	DES
CVARDEC CVARENC CVARPINE CVARXCVL CVARXCVR	See DES key usage restrictions.	DES
DATA	Valid for AES and DES keys and must be specified with the rule_array keyword AES to build an encrypted AES key token.	AES and DES
DATAC DATAM DATAMV DECIPHER DKYGENKY ENCIPHER EXPORTER IKEYXLAT IMPORTER	See DES key usage restrictions.	DES
KEYGENKY	CLR8-ENC or UKPT must be coded in rule_array parameter.	DES
IPINENC MAC MACVER OKEYXLAT OPINENC PINGEN PINVER	See DES key usage restrictions.	DES
SECMSG	SMKEY or SMPIN must be specified in the rule_array parameter.	DES
USE-CV	A user-supplied control vector, supplied in the control_vector parameter, is used to build the token. The CV rule array keyword should be specified if USE-CV is specified. When the key type is USE-CV, control vector keywords in the rule array are ignored. The number of bytes of the control vector copied into the output key token depends on the DES key length keyword specified in the rule array: If no keyword is specified, 16 bytes are copied. If KEYLN8 or SINGLE is specified, 8 bytes are copied. If KEYLN16, DOUBLE, or DOUBLE-0 is specified, 16 bytes are copied. If KEYLN24, TRIPLE, or TRIPLE-O is specified, 16 bytes are copied. A DES key wrapping method keyword may be required to match the CCA control vector and key length specified. When the KEY keyword is specified, the default length is 16 bytes. The key length keywords for DES keys are used to change the length to 8 or 24.	DES

rule_array_count

Direction:

Input/Output

Type:

Integer

A pointer to an integer variable containing the number of elements in the rule_array variable. This value must be 1, 2, 3, 4, 5, or 6.

rule_array

Direction:

Output

Type:

String array

One to four keywords that provide control information to the verb. The keywords must be in contiguous storage with each of the keywords left-aligned in its own 8-byte location and padded on the right with blanks. For any key type, there are no more than four valid rule_array values. The rule_array keywords are described in Table 1.

Table 1. Keywords for Key Token Build control information
Keyword	Description
*Token type* (One required)
EXTERNAL	An external key token. Valid only for DES keys.
INTERNAL	An internal key token. Valid for both AES and DES keys.
*Token algorithm* (One, optional)
AES	An AES key. Only valid for CLRAES or DATA. If CLRAES is specified, this is the default token algorithm.
DES	A DES key. Not valid for CLRAES. If CLRAES is not specified, this is the default token algorithm.
*Key status* (One, optional).
KEY	The key token to build will contain an encrypted key. The key_value parameter identifies the field that contains the key.
NO-KEY	The key token to build will not contain a key. This is the default key status.
*Key length* (one keyword required for AES keys, one optional for DES keys)
KEYLN8	Single-length or 8-byte key. Valid only for DES keys.
KEYLN16	Specifies that the key is 16 bytes long.
KEYLN24	Specifies that the key is 24 bytes long.
KEYLN32	Specifies that the key is 32 bytes long. Valid only for AES keys.
DOUBLE	Double-length or 16-byte key. Synonymous with KEYLN16. Valid only for DES keys.
DOUBLE-O	Double-length key with guaranteed unique 8-byte key halves. The key is 16 bytes long. Valid only for DES keys.
MIXED	Double-length key. Indicates that the key can either be a replicated single-length key (both key halves equal), or a double-length key with two different 8–byte values. Valid only for DES keys.
SINGLE	Single-length or 8-byte key. Synonymous with KEYLN8. Valid only for DES keys.
TRIPLE	Specifies that the key contains three key parts and is either a replicated single-length or replicated double-length key (two or three parts equal, ignoring parity bits), or a triple-length key with three different 8-byte values, ignoring parity bits. Valid only for supported DES key types listed in Table 1.
TRIPLE-O	Specifies that the key contains three key parts and is a triple-length key that is guaranteed to have three different 8-byte values, ignoring parity bits. Valid only for supported DES key types listed in Table 1.
ZEROCV24	Specifies that the key contains three key parts and is either a replicated single-length or replicated double-length key (two or three key parts equal, ignoring parity bits), or a triple-length key with three different 8-byte values, ignoring parity bits. Only valid with DES EXTERNAL DATA keys. Not valid with XPORT-OK, ENH-ONLY, NOT31XPT, or WRAPENH2. Specifies to build Version X’01’ fixed-length DES key-token with a CV valued to binary zeros, with the exception that the KEY-PART bit can be on together with the parity bit of that byte.
*Key Part Indicator* (optional). Valid only for DES keys.
KEY-PART	This token is to be used as input to the Key Part Import service.
*CV source* (One, optional). Valid only for DES keys.
CV	The key token is built using the control vector identified by the control_vector parameter. Note: When this keyword is specified, all control vector related keywords in the rule array are ignored.
NO-CV	The control vector is to be supplied based on the key type and the control vector related keywords. This is the default.
*Control vector on the link specification* (optional). Valid only for IMPORTER and EXPORTER.
CV-KEK	This keyword indicates marking the KEK as a CV KEK. The control vector is applied to the KEK prior to its use in encrypting other keys. This is the default.
NOCV-KEK	This keyword indicates marking the KEK as a NOCV KEK. The control vector is not applied to the KEK prior to its use in encrypting other keys.
*Key-wrapping method* (One, optional). Valid only for DES keys.
WRAP-ENH	Use enhanced key wrapping method, which is compliant with the ANSI X9.24 standard.
WRAP-ECB	Use original key wrapping method, which uses ECB wrapping for DES key tokens and CBC wrapping for AES key tokens.
WRAPENH2	Specifies to wrap the key using the enhanced wrapping method and SHA-256. Valid only for TRIPLE or TRIPLE-O. This is the default for TRIPLE and TRIPLE-O.
WRAPENH3	Specifies to wrap the key using the enhanced wrapping method with TDES-CMAC and SHA-256. This method requires CV bit 56 = B’1’ (ENH-ONLY), which is the default.
*Translation control* (Optional). Valid only for DES keys.
ENH-ONLY	Restrict re-wrapping of the output_key_token. After the token has been wrapped with the enhanced method, it cannot be re-wrapped using the original method. This is the default if WRAPENH3 is specified.
*Compliance* (Optional)
COMP-TAG	Generate a compliant-tagged key. While a skeleton key token with the compliance-tag can be created at any time, the skeleton must be passed to an adapter domain that is in PCI-HSM 2016 compliance mode to be provisioned with key material (either generated or imported).
NOCMPTAG	Do not generate a compliant-tagged key. This is the default.

See DES key usage restrictions for the key usage keywords that can be specified for a given key type.

The difference between Key Token Parse (CSNBKTP) and Control Vector Generate (CSNBCVG) is that Key Token Parse returns the rule_array keywords that apply to a parsed token, such as EXTERNAL, INTERNAL, and so forth. These rule_array parameters are returned in addition to the key_type parameter.

AMEX-CSC          DKYL0      EPINGEN       KEYLN16       UKPT
ANSIX9.9          DKYL1      EPINGENA      LMTD-KEK      VISA-PVV
ANY               DKYL2      EPINVER       MIXED         WRAP-ECB
ANY-MAC           DKYL3      EXEX          NO-SPEC       WRAP-ENH
CLR8-ENC          DKYL4      EXPORT        NO-XPORT      XLATE
CPINENC           DKYL5      GBP-PIN       NOOFFSET      XPORT-OK
CPINGEN           DKYL6      GBP-PINO      NOT-KEK
CPINGENA          DKYL7      IBM-PIN       OPEX
CVVKEY-A          DMAC       IBM-PINO      OPIM
CVVKEY-B          DMKEY      IMEX          PIN
DALL              DMPIN      IMIM          REFORMAT
DATA              DMV        IMPORT        SINGLE
DDATA             DOUBLE     INBK-PIN      SMKEY
DEXP              DPVR       KEY-PART      SMPIN
DIMP              ENH-ONLY   KEYLN8        TRANSLAT

key_value

Direction:

Output

Type:

String

This parameter is a pointer to a string variable containing the enciphered key or AES clear-key value which is placed into the key field of the key token when you use the KEY rule_array keyword. If the KEY keyword is not specified, this parameter is ignored.

The length of this variable depends on the type of key that is provided. The length is 16 bytes for DES keys. A single-length DES key must be left-aligned and padded on the right with eight bytes of X'00'. For a clear AES key, the length is 16 bytes for KEYLN16, 24 bytes for KEYLN24, and 32 bytes for KEYLN32. An enciphered AES key is 32 bytes.

reserved_1

Direction:

Output

Type:

Integer

This parameter is a pointer to an integer variable or a 4-byte string variable. The value must be equal to an integer valued 0.

reserved_2

Direction:

Output

Type:

Integer

This parameters is a pointer to an integer variable. The value must be 0 or a null pointer.

token_data

Direction:

Input

Type:

String

This parameter is unused for DES keys and cleartext AES keys. In either of those cases it must be a null pointer or point to a string variable containing eight bytes of binary zeros. For encrypted AES keys, this parameter is a pointer to a one-byte string variable containing the LRC value for the key passed in the key_value parameter. For more information on LRC values, see CCA Basic Services Reference and Guide for the IBM 4767 and IBM 4765 PCI-X Cryptographic Coprocessors.

control_vector

Direction:

Output

Type:

String

A parameter is a pointer to a string variable. If you specify the CV keyword in the rule_array, the contents of this variable are copied to the control vector field of the fixed-length DES key token. If the CV keyword is not specified, this keyword is ignored.

reserved_4

Direction:

Output

Type:

String

This parameter is a pointer to a string variable. The value must be binary zeros or a null pointer.

reserved_5

Direction:

Output

Type:

Integer

This parameter is a pointer to an integer variable. The value must be 0 or a null pointer.

reserved_6

Direction:

Output

Type:

String

This parameter is a pointer to an 8-byte string variable. The value must eight space characters or a null pointer.

master_key_verification_pattern

Direction:

Output

Type:

String

This parameter is a pointer to a string variable containing the master-key verification pattern of the master key used to encipher the key in the internal key-token. The contents of the variable are copied into the MKVP field of the of the key token when keywords INTERNAL and KEY are specified, and key_type keyword CLRAES is not specified.