Parameters

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

rule_array_count

Direction:	Input
Type:	Integer

A pointer to an integer variable containing the number of elements in the rule_array variable. The value can be 1 or in the range 6 - 13.

rule_array

Direction:	Input
Type:	String array

A pointer to a string variable containing an array of keywords. 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 verb are shown in Table 1.

Table 1. Keywords for TR31 Translate control information

Keywords for TR31 Translate control information

Keyword	Meaning
Source key algorithm (one optional).
SKEY-AES	Specifies that the source_key_identifier parameter identifies a CCA or TR-31 AES key token or the label of a key record in AES key-storage. Only valid with keyword VARDRV-D.
SKEY-DES	Specifies that the source_key_identifier parameter identifies a CCA or TR-31 DES key token or the label of a key record in DES key-storage. This is the default.
SKEYHMAC	Specifies that the source_key_identifier parameter identifies a CCA or TR-31 HMAC key token or the label of a key record in HMAC key-storage. Only valid with keyword VARDRV-D.
Key block protection method (one required). Specifies which version of the TR-31 key block to use for translating the source_key_identifier key. The version defines the method by which the key block is cryptographically protected and the content and layout of the block.
VARXOR-A	Specifies to use the DES Key Variant Binding Method 2005 Edition. Sets the byte at offset 0 of the header to ASCII “A”. This method uses a TDES key-encrypting key to wrap a DES or TDES key. Note: This legacy method is deprecated and should not be used in new applications.
VARDRV-B	Specifies to use the Key Derivation Binding Method 2010 Edition. Sets the byte at offset 0 of the header to ASCII B. This method uses a TDES key-encrypting key to wrap a DES or TDES key.
VARXOR-C	Specifies to use the Key Variant Binding Method 2010 Edition. Sets the byte at offset 0 of the header to ASCII C. This method uses a TDES key-encrypting key to wrap a DES or TDES key.
VARDRV-D	Specifies to use the Key Derivation Binding Method 2017 Edition. Sets the byte at offset 0 of the header to ASCII D. This method uses an AES key-encrypting key to wrap an AES, DES, TDES, or HMAC key.
Compliance tagging rules
COMP-TAG	Convert the input key token into a PCI-HSM compliant-tagged token. This requires that the domain at first is in full PCI-HSM 2016 compliance mode and from there enters into the migration mode, which is a temporary reduced mode of an active PCI-HSM mode. See Migration mode. Requires source key identifier to be an internal TR-31 key token. Not valid if the input token has Exportability S. Not valid with any other keywords.
COMP-CHK	Check if the key token to be translated or reformatted can have the PCI-HSM 2016 compliance mode tag. Requires the source_key_identifier parameter to be an internal or external TR-31 key token. Not valid with any other keywords.
Key Context (one optional).
STOREXCH	Either storage or key exchange context. This allows interoperability with legacy Key Blocks. This does not imply that the wrapping key for a Key Block can be used for both storage and key exchange, merely that the storage or exchange of this Key Block is determined by the properties of the wrapping key. Sets the byte at offset 14 of the header to ’0’ (0x30). This is seen as external in CCA. This is the default.
INTERNAL	Key storage context only. The Key Block is internal and can be used as an operational key but not a transport key. Sets the byte at offset 14 of the header to ’1’ (0x31). Only valid with wrapping methods VARDRV-B and VARDRV-D. NOT valid with ATTR-CV or INCL-CV.
EXCHANGE	Key exchange context only. The Key Block is wrapped by a transport key for exchange between a communicating pair. Sets the byte at offset 14 of the header to ’2’ (0x32).
CPACF Control (one optional, if building an internal token or keyword OB-IBM is set).
XPRTCPAC	Allow export to CPACF protected key format.
NOEXCPAC	Prohibit export to CPACF protected key format. This is the default.
DK PIN Enable (one optional, if building an internal token or keyword OB-IBM is set).
DKPINOP	Allow the key to be used for DK operations.
Optional blocks for internal and external tokens (multiple optional). The following keywords must be specified to include the associated optional block in the token that is being built. If the input key is a TR-31 token, OB-XX must be specified for each optional block that should be taken from the input token and should be added to the output token. If the input token does not have the specified OB-XX keyword, it is automatically set if allowed. If the keyword is specified and the OB cannot be added, the keyword is ignored.
OB-DA	Specifies to add a DA optional block to the TR-31 key block. This optional block contains information on the derivations allowed for a derivation key. This keyword does not build a new DA optional block, it can only take an existing DA block from the source_key_identifier parameter. If the source_key_identifier parameter does not contain a DA optional block, this keyword is ignored. If you want to add a DA optional block, you can build one using the CSNBT31O service and send it in via the opt_blocks parameter. Only valid with TR-31 key usage B3.
OB-LB	Specifies to add an LB optional block to the TR-31 key block. This optional block contains a user-defined label. This does not need to correlate with the key label which is used to store the token in combined key storage. Instead, it is in the user's responsibility to ensure that these match if desired. If the input token is an X’05’ CCA token, this parameter takes the stored label and uses it to build an LB optional block if it is printable ASCII. For any other input token, this keyword will not build a new LB optional block. It can only take an existing LB optional block from the source_key_identifier parameter. If the source_key_identifier parameter does not contain an LB optional block, or is any other CCA token, this keyword is ignored. If you want to add an LB optional block, you can build one using the CSNBT31O service and send it in via the opt_blocks parameter.
Optional blocks for external tokens only (multiple optional). If the input key is a TR-31 token, OB-XX must be specified for each optional block that should be taken from the input token and should be added to the external output token. If the input token does not have the specified OB-XX, it is automatically set if allowed. Some of these tokens must be built on the initial creation of the key, such as TC. So if the keyword is specified and they cannot be added, the keyword is ignored. Note: If translating to an internal TR-31 token, these optional blocks are all added if possible. These keywords result in an error if keyword INTERNAL is in the rule array. If keyword OB-XX is specified in the rule array, do not send in the same optional block via the opt_blocks parameter. OB-XX keywords are not necessary for any extra optional blocks sent in via opt_blocks and will cause an error.
OB-IBM	Specifies to add a proprietary IBM optional block to the TR-31 key block. Currently, this optional block contains a compliance tag bit and a KDF indicator.
OB-KC	Specifies to add a KC optional block to the TR-31 key block. This optional block contains a key check value of the key that is in the key block. Not valid with single length DES keys. Not valid with HMAC keys.
OB-KP	Specifies to add a KP optional block to the TR-31 key block. This optional block contains a key check value of the key that is used to wrap the key in the key block (that is, the KEK). If the key is being wrapped under a new KEK or translated to and from external, a new KP optional block is created and added to the key block.
OB-TC	Specifies to add a TC optional block to the TR-31 key block. This optional block contains the UTC time when the key block was initially created. This keyword does not build a new TC optional block. It can only take an existing TC optional block from the source_key_identifier parameter. If source_key_identifier does not contain a TC optional block, this keyword is ignored.
OB-TS	Specifies to add a TS optional block to the TR-31 key block. This optional block contains the UTC time when the current key block was created. This field changes when the key is wrapped under a new KEK or master key, such as when translating an internal token to an external token, or translating an external token to be wrapped with a different KEK.
OB-WP	Specifies to add a WP optional block to the TR-31 key block. This optional block contains the wrapping pedigree of the key. This documents if the key was ever wrapped by a key that is weaker than itself. This keyword only builds a new WP optional block, if the source_key_identifier parameter contains a CCA ’05’ token. It also checks the KUF bits to see if it was wrapped by a weaker key. Otherwise, this keyword can only take an existing WP optional block from the source_key_identifier parameter. If the source_key_identifier parameter does not contain a WP optional block, this keyword is ignored.
Control vector transport control (one, optional). If no keyword from this group is provided, or keyword INCL-CV is specified, the control vector in the CCA key token identified by the source_key_identifier parameter is verified to agree with the TR-31 key usage and mode of key use keywords specified from the groups below.
INCL-CV	Specifies to copy the control vector from the CCA key token into an optional proprietary block that is included in the TR-31 key block header. See Table 1. The TR-31 key usage and mode of use fields indicate the key attributes. Those attributes, as derived from the keywords specified, must be compatible with the ones in the included CV. In addition, the export of the key must meet the translation and ACP authorizations indicated in the export translation table for the specified keywords. A CCA key usage (that is, key type) keyword and a mode of use keyword are required when this keyword is specified.
ATTR-CV	Same as keyword INCL-CV, except that the key usage field of the TR-31 key block (byte number 5 - 6) is set to the proprietary value "10" (X'3130'), and the mode of use field (byte number 8) is set to the proprietary value "1" (X'31'). These proprietary values indicate that the key usage and mode of use attributes are specified by the CV in the optional block. For this option, only the general ACPs related to export are checked, not the ones relating to specific CCA to TR-31 translations. No key usage or mode of use keywords are allowed when this keyword is specified.

In table Table 2, the CCA usage keyword maps to the CSNBKTB and CSNBKTB2 service keywords when you build a DES CCA key. If you look for example, at the first row of this table, the KEYGENKY key usage, when used with CSNBKTB, builds a key type that is similar to the BDK key. So in this case, if you create a key with the CSNBKTB verb using the KEYGENKY keyword, you can export it to a TR-31 key using the BDK keyword.

Table 2. Keywords for TR31 Translate control information - Part 2

Keywords for TR31 Translate control information - Part 2

Keyword	TR-31 key usage	CCA usage keyword	Meaning
TR-31 key usage value for output key (one required). Not valid if ATTR-CV keyword is specified. Only those TR-31 modes of key use shown are supported.
BDK	"B0"	KEYGENKY	Specifies to export to a TR-31 base derivation key (BDK). Sets the bytes at offset 5 - 6 of the header to ASCII "B0". This keyword can be used with SKEY-AES for AES-DUKPT keys. When the source key is a DES DUKPT BDK, then the source key must be a DES KEYGENKY. When the source key is an AES DUKPT BDK, then the only valid type for the source key is AES DKYGENKY with KUF 1 LOB, left most bit set to 1. You must select one TR-31 mode of key use from Table 8 with this CCA usage keyword BDK. This table shows all of the supported translations for key usage keyword BDK. It also shows the access control commands that must be enabled in the active role in order to use the combination of inputs shown. This key is used to derive the initial PIN encryption key (IPEK) in the derived unique key per transaction (DUKPT) process defined in X9.24-1 2007 (DES DUKPT) and X9.24-3 2017 (AES DUKPT). An initial key is derived for individual devices such as PIN pads.
DUKPT	“B1”	DES KEYGENKY or AES DKYGENKY	Specifies to create an initial DUKPT key. Sets the bytes at offset 5 – 6 of the header to ASCII B1. If the input token is CCA DES, the key should be KEYGENKY UKPT. If the input token is CCA AES, this should be a DKYGENKY token. If the key is an AES token, the BDK bit (KUF1 low bit, 0x80) must not be set for a B1 token. For services requiring derivation data, such as UKD, this key usage requires X’8001’ in the derivation data. You must select one TR-31 mode of key use from Table 6 or Table 8 with this CCA usage keyword DUKPT. The table shows all of the supported translations for key usage keyword DUKPT. It also shows the access control commands that must be enabled in the active role in order to use the combination of inputs shown.
KDK	“B3”	DES DKYGENKY or AES KDKGENKY	Specifies to create a Key Derivation Key. Sets the bytes at offset 5 – 6 of the header to ASCII B3. If the input token is CCA DES, the key should be DKYGENKY. If the input token is CCA AES, this should be a KDKGENKY token. For services requiring derivation data, such as UKD, key usages B0 and B3 require X’8000’ in the derivation data. You must select one TR-31 mode of key use from Table 6 or Table 8 with this CCA usage keyword KDK. The table shows all of the supported translations for key usage keyword KDK. It also shows the access control commands that must be enabled in the active role in order to use the combination of inputs shown.
CVK	"C0"	MAC or DATA	Specifies to export to a TR-31 CVK card verification key. You must select one TR-31 mode of key use from Table 9 with this usage keyword. The table shows all of the supported translations for key usage keyword CVK. It also shows the access control commands that must be enabled in the active role in order to use the combination of inputs shown.
ENC	"D0"	ENCIPHER, DECIPHER, CIPHER, or DATA	Specifies to export to a TR-31 data encryption key. You must select one TR-31 mode of key use from Table 6 or Table 10 with this usage keyword. The table shows all of the supported translations for key usage keyword ENC. It also shows the access control commands that must be enabled in the active role in order to use the combination of inputs shown.
ENCSENS	"D3"	DES: CIPHERXO, CIPHERXI, CIPHERXL, or AES CIPHER	Specifies to create a data encryption key for sensitive data. Sets the bytes at offset 5 – 6 of the header to ASCII D3. If the input token is CCA DES, the key should be CIPHERXO (TR-31 mode of key use: E), CIPHERXI (TR-31 mode of key use D), or CIPHERXL (TR-31 mode of key use B). If the input token is CCA AES, this should be a CIPHER XLATE token. You must select one TR-31 mode of key use from Table 6 or Table 10 with this usage keyword. The table shows all of the supported translations for key usage keyword ENCSENS. It also shows the access control commands that must be enabled in the active role in order to use the combination of inputs shown.
KEK	"K0"	DES EXPORTER, DES OKEYXLAT, AES EXPORTER, or SECMSG:SMKEY	Specifies to export to a TR-31 key-encryption or wrapping key. You must select one TR-31 mode of key use from Table 6 or Table 11 with this usage keyword. The table shows all of the supported translations for key usage keyword KEK. It also shows the access control commands that must be enabled in the active role in order to use the combination of inputs shown. The SECMSG key can be used in the CSNBSKY verb.
KEK-WRAP	"K1"	DES IMPORTER, DES IKEYXLAT, or AES IMPORTER	Specifies to export to a TR-31 key block protection key. You must select one TR-31 mode of key use from Table 6 or Table 11 with this usage keyword. The table shows all of the supported translations for key usage keyword KEK-WRAP. It also shows the access control commands that must be enabled in the active role in order to use the combination of inputs shown.
KEK-WRK4	"K4"	IMPORTER, EXPORTER, IKEYXLAT, or OKEYXLAT	Specifies to export to an ISO 20038 key block protection key. With this usage keyword, you must select one TR-31 mode of key use from Table 6 (when exporting AES) or from Table 11 (when exporting DES). These tables show all of the supported translations for key usage keyword KEK-WRK4. They also show the access control commands that must be enabled in the active role in order to use the combination of inputs shown.
ISOMAC0	"M0"	MAC, MACVER, DATA, DATAM, or DATAMV	Specifies to export to a TR-31 ISO 16609 MAC algorithm 1 (using TDEA) key. You must select one TR-31 mode of key use from Table 12 with this usage keyword. The table shows all of the supported translations for key usage keyword ISOMAC0. It also shows the access control commands that must be enabled in the active role in order to use the combination of inputs shown.
ISOMAC1	"M1"	MAC, MACVER, DATA, DATAM, or DATAMV	Specifies to export to a TR-31 ISO 9797-1 MAC algorithm 1 key. You must select one TR-31 mode of key use from Table 12 with this usage keyword. The table shows all of the supported translations for key usage keyword ISOMAC1. It also shows the access control commands that must be enabled in the active role in order to use the combination of inputs shown.
ISOMAC3	"M3"	MAC, MACVER, DATA, DATAM, or DATAMV	Specifies to export to a TR-31 ISO 9797-1 MAC algorithm 3 key. You must select one TR-31 mode of key use from Table 12 with this usage keyword. The table shows all of the supported translations for key usage keyword ISOMAC3. It also shows the access control commands that must be enabled in the active role in order to use the combination of inputs shown.
ISOMAC6	"M6"	MAC	Specifies to create an ISO 9797-1:2011 MAC algorithm 5/CMAC key. When exporting AES keys, you must select one TR-31 mode of key use from Table 6. When exporting DES keys, you must select one mode of use keyword from Table 12 with this usage keyword. This table shows all of the supported translations for key usage keyword ISOMAC6. They also show the access control commands that must be enabled in the active role in order to use the combination of inputs shown.
HMAC	"M7"	MAC	Specifies to export an HMAC algorithm key. You must select one TR-31 mode of key use from Table 12 with this usage keyword. The table shows all of the supported translations for key usage keyword HMAC. It also shows the access control commands that must be enabled in the active role in order to use the combination of inputs shown.
INITVEC	"I0"	N/A	Specifies to export an initialization vector passed to the service to a TR-31 Initialization Vector key block.
PINENC	"P0"	OPINENC, IPINENC, PINPROT, or SECMSG	Specifies to export to a TR-31 PIN encryption key. You must select one TR-31 mode of key use from Table 6 or from Table 14 with this usage keyword. The table shows all of the supported translations for key usage keyword PINENC. It also shows the access control commands that must be enabled in the active role in order to use the combination of inputs shown. The SECMSG key can be used in the CSNBSPN verb.
PINVO	"V0"	PINGEN or PINVER	Specifies to export to a TR-31 PIN verification key or other algorithm. You must select one TR-31 mode of key use from Table 14 with this usage keyword. The table shows all of the supported translations for key usage keyword PINVO. It also shows the access control commands that must be enabled in the active role in order to use the combination of inputs shown.
PINV3624	"V1"	PINGEN or PINVER	Specifies to export to a TR-31 PIN verification, IBM 3624 key. You must select one TR-31 mode of key use from Table 14 with this usage keyword. The table shows all of the supported translations for key usage keyword PINV3624. It also shows the access control commands that must be enabled in the active role in order to use the combination of inputs shown.
VISAPVV	"V2"	PINGEN or PINVER	Specifies to export to a TR-31 PIN verification, VISA PVV key. You must select one TR-31 mode of key use from Table 14 with this usage keyword. The table shows all of the supported translations for key usage keyword VISAPVV. It also shows the access control commands that must be enabled in the active role in order to use the combination of inputs shown.
TYPATO11	"11"	KDKGENKY	Specifies to export an AES KDKGENKY key that has usage Entity Type A (KDKTYPEA) as its key diversification key entity type into a TR-31 proprietary external token format, as defined by the German Banking Industry Committee, Die Deutsche Kreditwirtschaft, also known as DK. The keyword requires a mode-of-use keyword from Table 17. The table shows the access controls that must be enabled in the domain role to use the combination of inputs shown.
TYPBTO10	"10"	KDKGENKY	>Specifies to export an AES KDKGENKY key that has usage Entity Type B (KDKTYPEB) as its key diversification key entity type into a TR-31 proprietary external token format, as defined by DK. The keyword requires a mode-of-use keyword from Table 17. The table shows the access controls that must be enabled in the domain role to use the combination of inputs shown.
DMP0TO12	"12"	DKYGENKY	AES DKYGENKY Specifies to export a DES DKYGENKY key that has a usage DKYL0 (CV bits 12 – 14 = B’000’) and DMPIN (CV bits 19 – 22 = B’1001’) into a TR-31 proprietary external token format, as defined by DK. The keyword requires a mode-of-use keyword from Table 17. The table shows the access controls that must be enabled in the domain role to use the combination of inputs shown.
EMVACMK	"E0"	DKYGENKY	Specifies to export to a TR-31 EMV/chip issuer master key: application cryptograms key. You must select one TR-31 mode of key use from Table 6 or from Table 16 with this usage keyword. The table shows all of the supported translations for key usage keyword EMVACMK. It also shows the access control commands that must be enabled in the active role in order to use the combination of inputs shown.
EMVSCMK	"E1"	DKYGENKY	Specifies to export to a TR-31 EMV/chip issuer master key: secure messaging for confidentiality key. You must select one TR-31 mode of key use from Table 6 or from Table 16 with this usage keyword. The table shows all of the supported translations for key usage keyword EMVSCMK. It also shows the access control commands that must be enabled in the active role in order to use the combination of inputs shown.
EMVSIMK	"E2"	DKYGENKY	Specifies to export to a TR-31 EMV/chip issuer master key: secure messaging for integrity key. You must select one TR-31 mode of key use from Table 6 or from Table 16 with this usage keyword. The table shows all of the supported translations for key usage keyword EMVSIMK. It also shows the access control commands that must be enabled in the active role in order to use the combination of inputs shown.
EMVDAMK	"E3"	DATA, MAC, CIPHER, or ENCIPHER	Specifies to export to a TR-31 EMV/chip issuer master key: data authentication code key. You must select one TR-31 mode of key use from Table 6 or from Table 16 with this usage keyword. The table shows all of the supported translations for key usage keyword EMVDAMK. It also shows the access control commands that must be enabled in the active role in order to use the combination of inputs shown.
EMVDNMK	"E4"	DKYGENKY	Specifies to export to a TR-31 EMV/chip issuer master key: dynamic numbers key. You must select one TR-31 mode of key use from Table 6 or from Table 16 with this usage keyword. The table shows all of the supported translations for key usage keyword EMVDNMK. It also shows the access control commands that must be enabled in the active role in order to use the combination of inputs shown.
EMVCPMK	"E5"	DKYGENKY	Specifies to export to a TR-31 EMV/chip issuer master key: card personalization key. You must select one TR-31 mode of key use from Table 6 or from Table 16 with this usage keyword. The table shows all of the supported translations for key usage keyword EMVCPMK. It also shows the access control commands that must be enabled in the active role in order to use the combination of inputs shown.
EMVAC-F	"F0"	DKYGENKY	Specifies to create an EMV/chip issuer master key: application cryptograms. Sets the bytes at offset 5 – 6 of the header to ASCII F0. If inputting a CCA token, the token should be type DKYGENKY. Requires TR-31 mode of key use DERIVE. You must select one TR-31 mode of key use from Table 6 or from Table 16 with this usage keyword. The table shows all of the supported translations for key usage keyword EMVAC-F. It also shows the access control commands that must be enabled in the active role in order to use the combination of inputs shown. When importing F* tokens using the CSNBT31I verb, DKYL0 is required in the rule array.
EMVSC-F	"F1"	DKYGENKY	Specifies to create an EMV/chip issuer master key: secure messaging for confidentiality. Sets the bytes at offset 5 – 6 of the header to ASCII F1. If inputting a CCA token, the token should be type DKYGENKY. Requires TR-31 mode of key use DERIVE. You must select one TR-31 mode of key use from Table 6 or from Table 16 with this usage keyword. The table shows all of the supported translations for key usage keyword EMVSC-F. It also shows the access control commands that must be enabled in the active role in order to use the combination of inputs shown. When importing F* tokens using the in CSNBT31I verb, DKYL0 is required in the rule array.
EMVSI-F	"F2"	DKYGENKY	Specifies to create an EMV/chip issuer master key: secure messaging for integrity. Sets the bytes at offset 5 – 6 of the header to ASCII F2. If inputting a CCA token, the token should be type DKYGENKY. Requires TR-31 mode of key use DERIVE. You must select one TR-31 mode of key use from Table 6 or from Table 16 with this usage keyword. The table shows all of the supported translations for key usage keyword EMVSI-F. It also shows the access control commands that must be enabled in the active role in order to use the combination of inputs shown. When importing F* tokens using the in CSNBT31I verb, DKYL0 is required in the rule array.
EMVDA-F	"F3"	DES: DATA, MAC, CIPHER, or ENCIPHER AES: CIPHER or DKYGENKY	Specifies to export an EMV/chip issuer master key: data authentication code. Sets the bytes at offset 5 – 6 of the header to ASCII F3. If inputting a CCA token, the token should be a DES DATA, MAC, CIPHER, or ENCIPHER source key, or an AES CIPHER or DKYGENKY source key. You must select one TR-31 mode of key use from Table 6 or from Table 16 with this usage keyword. The table shows all of the supported translations for key usage keyword EMVDA-F. It also shows the access control commands that must be enabled in the active role in order to use the combination of inputs shown. When importing F* tokens using the in CSNBT31I verb, DKYL0 is required in the rule array.
EMVDN-F	"F4"	DKYGENKY	Specifies to create an EMV/chip issuer master key: dynamic numbers. Sets the bytes at offset 5 – 6 of the header to ASCII F4. If inputting a CCA token, the token should be type DKYGENKY. Requires TR-31 mode of key use DERIVE. You must select one TR-31 mode of key use from Table 6 or from Table 16 with this usage keyword. The table shows all of the supported translations for key usage keyword EMVDN-F. It also shows the access control commands that must be enabled in the active role in order to use the combination of inputs shown. When importing F* tokens using the in CSNBT31I verb, DKYL0 is required in the rule array.

Table 3. Keywords for TR31 Translate control information - Part 3

Keywords for TR31 Translate control information - Part 3

Keyword	TR-31 mode of key use	TR-31 key usage keywords	Meaning
TR-31 mode of key use (one required). Not valid if ATTR-CV keyword is specified. Only those TR-31 modes shown are supported.
ENCDEC	"B"	ENC, KEK, KEK-WRAP, KEK-WRK4, PINENC	Specifies both encrypt and decrypt, wrap and unwrap.
DEC-ONLY	"D"	ENC, KEK, KEK WRAP, PINENC	Specifies to decrypt and unwrap only.
ENC-ONLY	"E"	ENC, PINENC	Specifies to encrypt and wrap only.
GENVER	"C"	CVK, HMAC, ISOMAC0, ISOMAC1, ISOMAC3, ISOMAC6, PINVO, PINV3624, VISAPVV	Specifies to both generate and verify.
GEN-ONLY	"G"	CVK, HMAC, ISOMAC0, ISOMAC1, ISOMAC3, ISOMAC6, PINVO, PINV3624, VISAPVV, EMVDA-F	Specifies to generate only.
VER-ONLY	"V"	CVK, HMAC, ISOMAC0, ISOMAC1, ISOMAC3, ISOMAC6, PINVO, PINV3624, VISAPVV	Specifies to verify only.
DERIVE	"X"	BDK, DUKPT, KDK, EMVACMK, EMVSCMK, EMVSIMK, EMVDAMK, EMVDNMK, EMVCPMK, EMVAC-F, EMVSC-F, EMVSI-F, EMVDA-F, EMVDN-F, TYPBTO10, TYPATO11, or DMP0TO12	Specifies that key is used to derive other keys. Valid for AES-DUKPT BDK.
ANY	"N"	BDK, PINVO, PINV3624, VISAPVV, EMVACMK, EMVSCMK, EMVSIMK, EMVDAMK, EMVDNMK, EMVCPMK, EMVDA-F	Specifies no special restrictions (other than restrictions implied by the key usage). Not valid for AES-DUKPT BDK.

Table 4. Keywords for TR31 Translate control information - Part 4

Keywords for TR31 Translate control information - Part 4

Keyword	TR-31 byte	Meaning
TR-31 exportability (one, optional). Use to set exportability field in TR-31 key block. Defines whether the key may be transferred outside the cryptographic domain in which the key is found.
EXP-ANY	"E"	Specifies that the key in the TR-31 key block is exportable under a key-encrypting key in a form that meets the requirements of X9.24 Parts 1 or 2. This is the default. Note: A TR-31 key block with a key block version ID of "B" or "C" and an exportability field value of "E" cannot be wrapped by a key-encrypting key that is wrapped in ECB mode (legacy wrap mode). This limitation is because ECB mode does not comply with ANSI X9.24 Part 1.
EXP-TRST	"S"	Specifies that the key in the TR-31 key block is sensitive, exportable under a key-encrypting key in a form not necessarily meeting the requirements of X9.24 parts 1 or 2.
EXP-NONE	"N"	Specifies that the key in the TR-31 key block is non-exportable.
Initialization vector algorithm (one required with INITVEC).
IV-DES	"D"	Specifies that algorithm DES is placed in the "I0" key block algorithm field.
IV-TDES	"T"	Specifies that algorithm TDES is placed in the "I0" key block algorithm field.
IV-AES	"A"	Specifies that algorithm AES is placed in the "I0" key block algorithm field.

Table 5. Keywords for TR31 Translate control information - Part 5

Keywords for TR31 Translate control information - Part 5

Keyword	Meaning
HMAC hash algorithm limit (one, required). Valid only with HMAC keys "M7". The keyword specified determines whether the format of the TR-31 key block is based on ASC X9 TR 31-2018 or ISO 20038. ISO 20038 and ANSI X9 TR-31-2018 represent the HMAC hash algorithm limit in different ways: ISO 20038 represents hash limit in the algorithm value at offset 7. An HMAC key limited to SHA-1 uses ASCII 'H', for the SHA-2 limit the value is ASCII 'I', and for the SHA-3 limit the value is ASCII 'J'. ANSI X9 TR-31-2018 always uses 'H' for the algorithm value at offset 7 and represents the hash algorithm limit in the optional block with identifier "HM" ("HM" optional block). Only valid with SKEYHMAC. Note that the input HMAC key token must allow the hash algorithm selected below in key-usage field 2, high-order byte.
ISOSHA-1	Specifies to use the SHA-1 hash algorithm with the HMAC key as defined by ISO 20038. Sets the algorithm (offset 7 of the TR-31 key block) to ASCII "H" and does not include an "HM" optional block. The source_key_identifier parameter must identify an HMAC key in a version X'05' variable-length symmetric key-token that allows a hash method of SHA-1 (KUF2 HOB = B'1xxx xxxx'). Security note: Keyword ISOSHA-1 creates a TR-31 key block with an algorithm of "H" and no "HM" optional block. Under ISO 20038, this key block allows only SHA-1 as the hash algorithm to use with the HMAC key. However, ASC X9 TR 31-2018 also allows a key block with an algorithm of "H" and no "HM" optional block, which is interpreted as an HMAC key with no hash algorithm limits. There is no limit to SHA-1. For this reason, use the ISOSHA-1 keyword only when sending a key to a partner that is known to require and understand the ISO 20038 version of the hash limit, or to have a clear understanding that the partner will receive an HMAC key with no hash algorithm limits under TR-31-2018. When possible, the SHA-1 keyword should be used instead, if the partner can receive a key block with the HM optional block that limits hash algorithm.
ISOSHA-2	Specifies to use the SHA-2 hash algorithm with the HMAC key as defined by ISO 20038. Sets the algorithm (offset 7 of the TR-31 key block) to ASCII "I" and does not include an "HM" optional block. The source_key_identifier parameter must identify an HMAC key in a Version X'05' variable-length symmetric key-token that allows a hash method of SHA-2 (KUF2 HOB = B'x1xx xxxx' for SHA-224, KUF2 HOB = B'xx1x xxxx' for SHA-256, KUF2 HOB = B'xxx1 xxxx' for SHA-384, or KUF2 HOB = B'xxxx 1xxx' for SHA-512).
SHA-1	Specifies to use the SHA-1 hash algorithm with the HMAC key as defined by ASC X9 TR 31-2018. Sets the algorithm (offset 7 of the TR-31 key block) to ASCII "H" and includes an "HM" optional block. Sets the hash algorithm used with the HMAC key (offset 4 of the optional block) to ASCII "10". The source_key_identifier parameter must identify an HMAC key in a Version X'05' variable-length symmetric key-token that allows a hash method of SHA-1 (KUF2 HOB = B'1xxx xxxx').
SHA-224	Specifies to use the SHA-224 hash algorithm with the HMAC key as defined by ASC X9 TR 31-2018. Sets the algorithm (offset 7 of the TR-31 key block) to ASCII "H" and includes an "HM" optional block. Sets the hash algorithm used with the HMAC key (offset 4 of the optional block) to ASCII "20". The source_key_identifier parameter must identify an HMAC key in a Version X'05' variable-length symmetric key-token that allows a hash method of SHA-224 (KUF2 HOB = B'x1xx xxxx').
SHA-256	Specifies to use the SHA-256 hash algorithm with the HMAC key as defined by ASC X9 TR 31-2018. Sets the algorithm (offset 7 of the TR-31 key block) to ASCII "H" and includes an "HM" optional block. Sets the hash algorithm used with the HMAC key (offset 4 of the optional block) to ASCII "21". The source_key_identifier parameter must identify an HMAC key in a Version X'05' variable-length symmetric key-token that allows a hash method of SHA-256 (KUF2 HOB = B'xx1x xxxx').
SHA-384	Specifies to use the SHA-384 hash algorithm with the HMAC key as defined by ASC X9 TR 31-2018. Sets the algorithm (offset 7 of the TR-31 key block) to ASCII "H" and includes an "HM" optional block. Sets the hash algorithm used with the HMAC key (offset 4 of the optional block) to ASCII "22". The source_key_identifier parameter must identify an HMAC key in a Version X'05' variable-length symmetric key-token that allows a hash method of SHA-384 (KUF2 HOB = B'xxx1 xxxx').
SHA-512	Specifies to use the SHA-512 hash algorithm with the HMAC key as defined by ASC X9 TR 31-2018. Sets the algorithm (offset 7 of the TR-31 key block) to ASCII "H" and includes an "HM" optional block. Sets the hash algorithm used with the HMAC key (offset 4 of the optional block) to ASCII "23". The source_key_identifier parameter must identify an HMAC key in a Version X'05' variable-length symmetric key-token that allows a hash method of SHA-512 (KUF2 HOB = B'xxxx 1xxx').

Table 6. Export translation table for an AES TR-31 key

Export translation table for an AES TR-31 key.

CCA key type (required attributes)	Key usage keyword	Key block protection method keyword	Mode of use keyword	Access control name	Offset (hex)
AES CIPHER Encrypt / decrypt modes require matching key usage	ENC ("D0")	VARDRV-D	ENC-ONLY ("E") DEC-ONLY ("D") ENCDEC ("B")	T31X - Permit AES CIPHER to D0:E/D/B	X'01D0'
AES MAC (CMAC) Generate/verify modes require matching key usage	ISOMAC6 ("M6")	VARDRV-D	GEN-ONLY ("G") VER-ONLY ("V") GENVER ("C")	T31X - Permit AES MAC: CMAC to M6:G/C/V	X'01D1'
AES PINPROT Encrypt/ decrypt modes require matching key usage	PINENC ("P0")	VARDRV-D	ENC-ONLY ("E") DEC-ONLY ("D")	T31X - Permit AES PINPROT to P0:E/D	X'01D2'
			ENCDEC ("B")	T31X – Permit AES PINPROT to P0:B	X'050A'
AES EXPORTER	KEK ("K0")	VARDRV-D	ENC-ONLY ("E") ENCDEC("B")	T31X - Permit AES EXPORTER to K0:E	X'01D3'
AES EXPORTER (EXPTT31D)	KEK-WRAP ("K1")	VARDRV-D	ENC-ONLY ("E") ENCDEC("B")	T31X - Permit AES EXPORTER to K1:E	X'01D4'
	KEK-WRK4 ("K4")		ENC-ONLY ("E")	T31X - Permit AES EXPORTER to K4:E	X'01D5'
AES IMPORTER	KEK ("K0")	VARDRV-D	DEC-ONLY ("D") ENCDEC("B")	T31X - Permit AES IMPORTER to K0:D	X'01D6'
AES IMPORTER (IMPTT31D)	KEK-WRAP ("K1")	VARDRV-D	DEC-ONLY ("D") ENCDEC("B")	T31X - Permit AES IMPORTER to K1:D	X'01D7'
	KEK-WRK4 ("K4")		DEC-ONLY ("D")	T31X - Permit AES IMPORTER to K4:D	X'01D8'
AES DKYGENKY (DKYL0 or DKYL1 or DKYL2; D-MAC or D-ALL) EMV Issuer Master Key: App Cryptograms	EMVACMK ("E0")	VARDRV-D	DERIVE ("X")	T31X - Permit AES DKYGENKY:D-ALL/DMAC to E0:X	X'01D9'
AES DKYGENKY (DKYL0 or DKYL1 or DKYL2; D-SECMSG or D-ALL) EMV Issuer Master Key: Sec Msg for Confidentiality	EMVSCMK ("E1")	VARDRV-D	DERIVE ("X")	T31X - Permit AES DKYGENKY:D-ALL/DCIPHER to E1:X	X'01DA'
AES DKYGENKY (DKYL0 or DKYL1 or DKYL2; D-MAC or D-ALL) EMV Issuer Master Key: Sec Msg for Integrity	EMVSIMK ("E2")	VARDRV-D	DERIVE ("X")	T31X - Permit AES DKYGENKY:D-ALL/D-MAC to E2:X	X'01DB'
AES CIPHER (no required attributes) or AES DKYGENKY (DKYL0 or DKYL1 or DKYL2; D-CIPHER or D-ALL) EMV Issuer Master Key: Data Auth Code. May be used directly to create DAC , or for derivation. Encrypt mode is required for CIPHER, DAC is created with encrypt.	EMVDAMK ("E3")	VARDRV-D	CIPHER: ENC-ONLY ("E") ENCDEC ("B") DKYGENKY: DERIVE ("X")	T31X - Permit AES CIPHER to E3/E/B,DKYGENKY:D-ALL/DCIP to E3:X	X'01DC'
AES DKYGENKY (DKYL0 or DKYL1 or DKYL2; D-CIPHER or D-ALL) EMV Issuer Master Key: Dynamic Numbers	EMVDNMK ("E4")	VARDRV-D	DERIVE ("X")	T31X - Permit AES DKYGENKY:D-ALL/D-CIPHER to E4:X	X'01DD'
AES DKYGENKY + (DKYL0 or DKYL1 or DKYL2l D-MAC or D-ALL) EMV Issuer Master Key: Card Personalization	EMVCPMK ("E5")	VARDRV-D	DERIVE ("X")	T31X - Permit AES DKYGENKY:D-MAC to E5:X	X'01DE'
AES DKYGENKY (DKYL0 or DKYL1 or DKYL2; D-MAC or D-ALL) EMV Issuer Master Key: App Cryptograms	EMVAC-F ("F0")	VARDRV-D	DERIVE ("X”)	TR-34 Key Receive - Allow wrapping override keywords	X'03FD'
AES DKYGENKY (DKYL0 or DKYL1 or DKYL2; DSECMSG or DALL) EMV Issuer Master Key: Sec Msg for Confidentiality	EMVSC-F ("F1")	VARDRV-D	DERIVE (“X”)	T31X - Permit AES DKYGENKY:DALL/DCIPHER to F1:X	X'03FE'
AES DKYGENKY (DKYL0 or DKYL1 or DKYL2; D-MAC or D-ALL) EMV Issuer Master Key: Sec Msg for Integrity	EMVSI-F ("F2")	VARDRV-D	DERIVE ("X")	T31X - Permit AES DKYGENKY:D-ALL/DMAC to F2:X	X'03FF'
AES CIPHER (no required attributes) or AES DKYGENKY (DKYL0 or DKYL1 or DKYL2; DCIPHER or D-ALL) EMV Issuer Master Key: Data Auth Code. May be used directly to create DAC, or for derivation. Encrypt mode is required for CIPHER, DAC is created with encrypt.	EMVDA-F ("F3")	VARDRV-D	CIPHER: ENC-ONLY ("E"), ENCDEC ("B") DKYGENKY: DERIVE ("X")	T31X - Permit AES CIPHER, DKYGENKY:DALL/DCIPHER to F3:E/B/X	X'0500'
AES DKYGENKY (DKYL0 or DKYL1 or DKYL2; D-CIPHER or D-ALL) EMV Issuer Master Key: Dynamic Numbers	EMVDN-F ("F4")	VARDRV-D	DERIVE ("X")	T31X - Permit AES DKYGENKY:DALL/DCIPHER to F4:X	X'0501'
Security considerations: Use caution when enabling any of the following access control points as this capability may give an immediate path to turn a CCA EXPORTER key into a CCA IMPORTER key and a CCA IMPORTER key into a CCA EXPORTER key. Legend: ED – Enabled by Default. DD – Disabled by Default. DES: T31X Permit EXPORTER to K0/K1:B (X'02AD') (ED) T31X Permit IMPORTER to K0/K1:B (X'02AE') (ED) TR31 Import - Permit K0:B to EXPORTER/OKEYXLAT (X'015E') (DD) TR31 Import - Permit K0:B to IMPORTER/IKEYXLAT (X'015F') (DD) TR31 Import - Permit K1:B to EXPORTER/OKEYXLAT (X'0162') (DD) TR31 Import - Permit K1:B to IMPORTER/IKEYXLAT (X'0163') (DD) AES: T31X - Permit AES EXPORTER to K0:E (X'01D3') (ED) T31X - Permit AES EXPORTER to K1:E (X'01D4') (ED) T31X - Permit AES IMPORTER to K0:D (X'01D6') (ED) T31X - Permit AES IMPORTER to K1:D (X'01D7') (ED) T31X – Permit AES PINPROT to P0:B (X'050A') (ED) T31I - Permit K1/K4:E to AES EXPORTER:EXPTT31D+VARDRV-D (X'01E5') (ED) T31I - Permit AES K1/K4:D to AES IMPORTER:IMPTT31D+VARDRV-D (X'01E6') (ED) Note: Key encryption or wrapping keys are used only to encrypt or decrypt other keys, or as a key used to derive keys that are used for that purpose. The following defines the only supported translations for this TR-31 usage. Usage must be one of: "K0" Key encryption or wrapping "K1" TR-31 key block protection key CCA mode support is the same for version IDs "B" and "C", because the distinction between TR-31 "K0" and "K1" does not exist in CCA keys. CCA does not distinguish between targeted protocols, and so there is no good way to represent the difference. Also note that most wrapping mechanisms now involve derivation or key variation steps. There is asymmetry in the SECMSG:SMKEY to K0 translation. There is no way to translate a TR-31 K0 key to a CCA SECMSG:SMKEY.

Table 7. Export translation table for an initialization vector

Export translation table for an initialization vector.

Key usage keyword	Key block protection method keyword	Initialization vector algorithm	TR-31 exportability	TR-31 mode of key use
INITVEC ("I0")	VARXOR-A, VARDRV-B, VARXOR-C, VARDRV-D	IV-DES, IV-TDES, IV-AES	EXP-ANY, EXP-TRST, EXP-NONE	ANY ("N")

For export translation for a TR-31 PIN encryption or PIN verification key, note the following:

key_version_number

Direction:	Input
Type:	String

A pointer to a string variable containing two numeric ASCII bytes that are copied into the key version number field of the output TR-31 key block. Use a value of 00 (X'3030') if no key version number is needed.

This value is ignored if the key identified by the source_key_identifier parameter contains a partial key, that is, the KEY-PART bit (CV bit 44) is on in the control vector. When a partial key is passed, the verb sets the key version number field in the TR-31 key block to C0 (X'6330'). According to TR-31, this value indicates that the TR-31 key block contains a component of a key (key part).

key_field_length

Direction:	Input
Type:	Integer

A pointer to an integer variable containing the length of the key field that is encrypted in the TR-31 block. The length must be a multiple the DES cipher block size, which is eight. It must also be greater than or equal to the length of the cleartext key passed using the source_key_identifier parameter plus the length of the key length field (two bytes) that precedes this key in the TR-31 block. For example, if the source key is a double-length TDES key (its length is 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.

For internal TR-31 keys, this parameter is ignored, and the key_field_length parameter uses the recommended value for the algorithm (32 for DES, 48 for AES, 272 for HMAC).

TR-31 allows a variable number of padding bytes to follow the cleartext key, and the application designer can choose to pad with more than the minimum number of bytes needed to form a block that is a multiple of 8. This padding 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: 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 a value of 24 is passed 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 is 48 bytes.

Table 18 shows the recommended values for the key_field_length parameter. They are determined based on the cipher block size of the underlying algorithm used to wrap the key block and the minimum number of pad bytes for the maximum key size that can be wrapped (32 bytes for DES, 48 bytes for AES, and 272 bytes for HMAC).

Table 18. Recommended values for the key_field_length parameter

Recommended values for the key_field_length parameter. This table has four columns: Key block version ID, Cipher block size in bytes, Key algorithm, and Recommended key_field_length value, and four rows: "A" (DES wrap KEK), "B" (DES wrap KEK), "C" (DES wrap KEK), and "D" (AES wrap KEK).

Key block version ID	Cipher block size in bytes	Key algorithm	Recommended key_field_length value
"A" (DES wrap KEK)	8	DES	32
"B" (DES wrap KEK)
"C" (DES wrap KEK)
"D" (AES wrap KEK)	16	DES	32
		AES	48
		HMAC	272

source_key_identifier_length

Direction:	Input
Type:	Integer

A pointer to an integer variable containing the length in bytes of the source_key_identifier variable. Set this value to the length of the AES, DES, or HMAC key-token or label. A key label must be at least 64 bytes, and only the first 64 bytes of a key label are used.

source_key_identifier

Direction:	Input
Type:	String

A pointer to a string variable containing a CCA or TR-31 external or internal key token.

For a CCA key this can be:

• a variable-length AES key-token, or the label of such a record in AES key-storage
• a fixed-length DES key-token, or the label of such a record in DES key-storage
• a variable-length HMAC key-token, or the label of such a record in AES key-storage.

For a TR-31 key this can be:

• any type of TR-31 key-token, or the label of such a record in Combined key-storage.
  Note: If a TR-31 token is sent into this parameter, the TR-31 key usage and TR-31 mode of key use rule array keywords must match the input token. Key usage, mode of key use, and key algorithm can not be changed.

The key token contains the source key along with its attributes to be exported to an internal or external TR-31 key block. If the key identified by this parameter is contained in an external key-token, use the unwrap_kek_identifier parameter to identify the operational key-encrypting key that is required to unwrap the source key.

If the COMP-TAG or COMP-CHK keyword is specified, the source key identifier must specify a token of with algorithm A (AES) or T (TDES), and the token must have Exportability E or N.

unwrap_kek_identifier_length

Direction:	Input
Type:	Integer

A pointer to an integer variable containing the length in bytes of the unwrap_kek_identifier variable. Set this value to the length of the AES or DES key-token or label. The value must be greater than or equal to 0. A key label must be at least 64 bytes, and only the first 64 bytes of a key label are used.

unwrap_kek_identifier

Direction:	Input
Type:	String

A pointer to a string variable containing a fixed-length DES key-token, a null key-token, or the label of such a record in DES key-storage. It can also be a pointer to a string variable containing a variable-length AES key-token, a null key-token, or the label of such a record in key storage. Beginning with CCA release 8.1, this can be a TR-31 or CCA token. The use of this parameter depends on whether the source key identifier parameter identifies an internal or an external key-token.

If the value in the source_key_identifier parameter is an internal key-token, then it is wrapped by a master key and not by a key-encrypting key. Either set the wrap_kek_identifier_length variable to 0 or use this unwrap_kek_identifier parameter to identify a null key token. If this parameter identifies a key-encrypting key, it must meet the requirements for when a source key is in an external key-token but is otherwise ignored.

If the source_key_identifier is an external key-token, then it is wrapped by a key-encrypting key. Use the unwrap_kek_identifier parameter to identify the operational key-token containing the key needed to unwrap the source_key_identifier. This key-encrypting key is also used to wrap the output TR-31 key block when the wrap_kek_identifier_length variable is 0 or the wrap_kek_identifier parameter identifies a null key-token. The source key is either a DES key or an AES key in a CCA or TR-31 token:

• If the source_key_identifier is an external TR-31 token, this parameter can contain a valid CCA EXPORTER key token, or a TR-31 token with key usage K0 or K1 and mode of use E.
• If the source_key_identifier is an external CCA token, this parameter can contain a valid CCA EXPORTER key token, or a TR-31 token with key usage K0 and mode of use E.
• If the source_key_identifier is an external DES key (keyword SKEY-AES or SKEYHMAC is not specified in the rule array), then you must consider the following cases:
  • If using a CCA KEK token, this parameter must identify an operational fixed-length CCA DES key-token with a key type of OKEYXLAT or EXPORTER with CV bits 35 – 37 = B’000’ (ANY). An EXPORTER key must also have CV bit 21 = B'1' (EXPORT).
    Note: A DES key wrapped in ECB mode (CCA legacy wrap mode) does not comply with ANS X9.24 Part 1 or Part 2. Therefore, such a key cannot be used to wrap or unwrap TR- 31 method "B", "C", or "D" key blocks that have or will have Exportability E.
  • If using a TR-31 KEK token, this parameter must identify an operational TR-31 DES key-token with the following attributes:
    • TR-31 key usage: K0 or K1
    • Algorithm: T or A
    • TR-31 mode of key use: E
• If the source_key_identifier is an external AES key (keyword SKEY-AES is specified in the rule array), then you must consider the following cases:
  • If using a CCA KEK token, this parameter must identify an operational variable-length CCA AES key-token with a key type of EXPORTER. In addition, the key usage fields must allow the key to be used to export a key to an AES-wrapped TR-31 key block version ID "D" (EXPTT31D). If the wrap_kek_identifier_length variable is 0 or the wrap_kek_identifier parameter identifies a null key-token, the key usage fields of the unwrap KEK must have the following usages:
    • EXPORTER key can wrap a key contained in a CCA key-token using TR-31 key block with version ID (protection method) "D" (VARDRV-D),
    • key can wrap or unwrap AES keys or initialization vectors (WR-AES),
    • wrap or unwrap derivation class keys (WRDERIVE) when key usage value keyword EMVACMK, EMVSCMK, EMVSIMK, EMVDAMK, EMVDNMK, EMVCPMK, TYPBTO10, or TYPATO11 is specified in the rule array,
    • wrap or unwrap data class keys (WR-DATA) when key usage value keyword ENC or ISOMAC6 is specified in the rule array,
    • wrap or unwrap KEK class keys (WR-KEK) when key usage value keyword KEK, KEKWRAP, or KEK-WRK4 is specified in the rule array.
  • If using a TR-31 KEK token, this parameter must identify an operational TR-31 AES key-token with the following attributes:
    • TR-31 key usage: K0 or K1
    • Algorithm: A
    • TR-31 mode of key use: E
• If the source_key_identifier is an external HMAC key (keyword SKEYHMAC is specified in the rule array), then you must consider the following cases:
  • If using a CCA KEK token, parameter must identify an operational variable-length AES key-token with a key type of EXPORTER. In addition, the key usage fields must allow the key to be used to export a key to an AES-wrapped TR-31 key block version ID "D" (EXPTT31D).

    If the wrap_kek_identifier_length parameter is 0 or the wrap_kek_identifier parameter identifies a null key-token, the key usage fields of the unwrap KEK must also allow the key to:

    • EXPORTER key can wrap a key contained in a CCA key-token using TR-31 key block with version ID (protection method) "D" (VARDRV-D),
    • key can wrap or unwrap HMAC keys (WR-HMAC),
    • wrap or unwrap data class keys (WR-DATA) when key usage value keyword HMAC is specified in the rule array.
  • If using a TR-31 KEK token, this parameter must identify an operational TR-31 AES key-token with the following attributes:
    • TR-31 key usage: K0 or K1
    • Algorithm: A
    • TR-31 mode of key use: E

wrap_kek_identifier_length

Direction:	Input
Type:	Integer

A pointer to an integer variable containing the length in bytes of the wrap_kek_identifier variable. Set this value to the length of the AES or DES key-token or label. The value must be greater than or equal to 0. A key label must be at least 64 bytes, and only the first 64 bytes of a key label are used.

wrap_kek_identifier

Direction:	Input
Type:	String

A pointer to a string variable containing a fixed-length DES key-token, a null key-token, or the label of such a record in key-storage. It can also be a pointer to a string variable containing a variable-length AES key-token, a null key-token, or the label of such a record in key storage. Beginning with CCA release 8.1, this can be a TR-31 or CCA token.

This parameter identifies the key-token containing the key-encrypting key to use to wrap the output TR-31 key block. This parameter will be ignored if the Key Context is 0x31 (1), indicating an internal token is to be created.

This parameter can contain a valid CCA EXPORTER key token, a TR-31 token with key usage K0 or K1 and mode of key use E, or a NULL key token.

If using a CCA KEK, this parameter must identify either:

• an operational fixed-length DES key-token with a key type of EXPORTER or OKEYXLAT
• or for key block protection method VARDRV-D, the key is an AES key-encrypting key of type of EXPORTER with key usage EXPTT31D and with WR-DES, WR-AES, or WR-HMAC capability, matching the wrapped key.

If using a TR-31 KEK token, this parameter must identify an operational TR-31 key-token with the following attributes:

• For SKEY-DES:
  • TR-31 key usage: K0 or K1
  • Algorithm: T or A
  • TR-31 mode of key use: E
• For SKEY-AES or SKEYHMAC:
  • TR-31 key usage: K0 or K1
  • Algorithm: A
  • TR-31 mode of key use: E

If this parameter identifies a null key-token or its buffer length is 0 and the Key Context is either 0x30 (0) or 0x32 (2), indicating an external token is to be created, then the key-encrypting key identified by the unwrap_kek_identifier parameter is used to wrap the output TR-31 key block.

Note: ECB-mode wrapped DES keys (CCA legacy wrap mode) cannot be used to wrap or unwrap TR-31 "B" or "C" key blocks that have or will have Exportability "E", 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 are restricted as to what they can wrap, such that a KEK for wrapping CCA external keys might not be usable for wrapping TR-31 external keys, or the other way around.

opt_blocks_length

Direction:	Input
Type:	Integer

A pointer to an integer variable that specifies the length in bytes of the opt_blocks variable. If no optional data is to be included in the TR-31 key block, set this value to zero.

opt_blocks

Direction:	Input
Type:	String

A pointer to a string variable containing optional blocks data that is to be included in the output TR-31 key block. The optional blocks data can be constructed using the TR31 Optional Data Build verb.

These blocks do not require the OB-XX keywords to be specified in the rule array. If OB-XX keywords are specified in the rule array, ensure that these specific optional blocks are not also sent in via this parameter. The CSNBT31O verb can be used to build optional blocks, but the majority of the general blocks (KC, KP, TS, TC, WP, IBM [10]) should not be added by hand to ensure correctness. Some blocks cannot be sent in via this parameter, as follows

• When the output token is INTERNAL T31, this parameter cannot contain the following OBs: KC, KP, TC, TS, WP, IBM
• When the input token is T31 and the output is EXTERNAL T31, then this parameter cannot contain the following OBs: KC (algorithm ’01’), KP (algorithm ’01’), TC, TS, WP, IBM. KC and KP with algorithm ’00’ are allowed, but but should not be used.
• When the input token is CCA and the output is EXTERNAL T31, then an IBM optional block is not allowed, but all others are be accepted. However, when adding optional blocks, you should only use the rule array parameters to build the optional blocks for you.

Note: The Padding Block, ID "PB" cannot be added by the user, and therefore is not accepted in the opt_blocks parameter. CCA adds a Padding Block of the appropriate size as needed when building the TR-31 key block in TR31 Translate. The Padding Block for optional blocks serves no security purpose, unlike the padding in the encrypted key portion of the payload.

tr31_key_block_length

Direction:	Input/Output
Type:	Integer

A pointer to an integer variable containing the length in bytes of the tr31_key_block variable. On input, specify the size of the application program buffer available for the output key-token. On return from the verb, this variable is updated to contain the actual length of that returned token. TR-31 key blocks are variable in length.

tr31_key_block

Direction:	Output
Type:	String

A pointer to a string variable containing the output key block produced by the verb. The output key block contains the internal or external form of the key created by the verb, wrapped according to the method specified.

Note: The padding optional block in the output TR-31 key block can be present with zero data bytes. This situation can occur if the optional block portion of the header needs exactly four bytes of padding, the size of an optional block header without the data portion. The data portion is defined as optional by TR-31, which allows this.