Usage notes

Edit online

The usage notes for CSNBT31X.

This verb takes as input either an external or internal symmetric CCA key-token (DES, AES, or HMAC), or an internal or external TR-31 key-token. And depending on the specific action taken, a wrapping and/or unwrapping key-encrypting key (KEK) can be required. Either a CCA or a TR-31 KEK can be used. A CCA KEK must be a DES EXPORTER or OKEYXLAT token or an AES EXPORTER KEK with usage EXPTT31D. A TR-31 KEK must have the following attributes:

  • TR-31 key usage: K0 or K1
  • Algorithm: T or A
  • TR-31 mode of key use: E

For CCA tokens, the main purpose of the TR-31 Translate verb is to prepare a proprietary CCA token for use in a non-proprietary system. To this end, the TR-31 Translate verb can translate both internal and external symmetric CCA tokens into external TR-31 tokens. After translating a CCA token into an external TR-31 key block, the key and its attributes are ready to be interchanged with any outside third party who uses TR-31.

For TR-31 tokens the main purpose of the TR-31 Translate verb is to translate a TR-31 token between internal and external formats so that it can be used locally at the current node or remotely in another system.

Both CCA and TR-31 define key attributes that control key usage. In both cases, the usage information is securely bound to the key so that the attributes cannot be changed in unintended or uncontrolled ways. CCA maintains its DES key attributes in a control vector (CV) and maintains its AES and HMAC key attributes in key usage and key management fields, while a TR-31 key block uses fields key usage, algorithm, mode of use, and exportability.

Each attribute in a CCA control vector falls under one of these categories:
  1. There is a one-to-one correspondence between the CV attribute and the TR-31 attribute. For these attributes, conversion is straightforward.
  2. There is not a one-to-one correspondence between the CV attribute and the TR-31 attribute, but the attribute can be automatically translated when performing this export operation.
  3. There is not a one-to-one correspondence between the CV attribute and the TR-31 attribute, in which case a rule-array keyword is defined to specify which attribute is used in the TR-31 key block.
  4. Category (1), (2), or (3) applies, but there are some attributes that are lost completely on translation (for example, key-generating bits in key-encrypting keys).
  5. None of the above categories applies, because the key type, its attributes, or both simply cannot be reasonably translated into a TR-31 key block.

The control vector is always checked for compatibility with the TR-31 attributes. It is an error if the specified TR-31 attributes are in any way incompatible with the control vector of the input key. In addition, access control points are defined that can be used to restrict the permitted attribute conversions.

The TR-31 key block has a header that can contain optional blocks. Optional blocks become securely bound to the key by virtue of the MAC on the TR-31 key block. The opt_blocks parameter is provided to allow a complete and properly formatted optional block structure to be included as part of the TR-31 key block that is returned by the verb. The TR31 Optional Data Build (CSNBT31O) verb can be used to construct an optional block structure, one optional block at a time.

An optional block has a 2-byte ASCII block ID value that determines the use of the block. The use of a particular optional block is either defined by TR-31, or it has a proprietary use. An optional block that has a block ID with a numeric value is a proprietary block. IBM has its own proprietary optional block to contain a CCA control vector. See TR-31 optional block data for a description of the IBM-defined data.

To include a copy of the control vector from the a CCA DES source key in an optional block of the output TR-31 key block, specify the ATTR-CV or INCL-CV control vector transport control keyword in the rule array. If either optional keyword is specified, the verb copies the single-length or double-length control vector field from the source key into the optional data field of the TR-31 header. The TR31 Key Import verb can later extract this data and use it as the control vector for the CCA key that it creates when importing the TR-31 key block. This method provides a way to use TR-31 for transport of CCA keys and to make the CCA key have identical control vectors on the sending and receiving nodes.

DES and TDES keys can be wrapped with a CCA AES key block protection key using ISO 20038 method "D":

  • Method "D" is applicable to all prior exportable DES key types and translations to the "D" key block version ID (protection method). Some DES translation options are restricted according to the method. In all cases, method "D" follows the same restrictions in place for method "B".
  • An AES EXPORTER key-encrypting key with usage EXPTT31D (Release 5.4 or later) allowed is required for wrapping the output TR-31 key block that contains a DES key. In addition, usage WR-DES must be allowed.

Support is available to package CCA AES cryptographic keys for transport in an external TR-31 key block wrapped under a CCA AES key-encrypting key using a method based on ISO 20038:

  • AES keys can be wrapped with an AES key block protection key using method "D". Method "D" is limited to the following AES key types: 
    
CIPHER    DKYGENKY    EXPORTER    IMPORTER    MAC    PINPROT
  • An AES EXPORTER key encrypting key with usage EXPTT31D (Release 5.4 or later) allowed is required for wrapping the output TR-31 key block that contains an AES key. In addition, usage WR-AES must be allowed.

Support is available to package HMAC cryptographic keys for transport in an external TR-31 key block wrapped under a CCA AES key-encrypting key using a method based on ISO 20038 or ASC X9 TR 31-2018 as determined by the HMAC hash algorithm limit keyword specified in the rule array. HMAC keys can be wrapped with an AES key block protection key using method "D". The only supported HMAC key type is MAC.

Note: ISO 20038 and ASC 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 algorithm and SHA-2 uses ASCII "I".
  • ASC X9 TR 31-2018 uses "H" for the algorithm value at offset 7 and represents the hash algorithm limit in an "HM" optional block.
The ATTR-CV and INCL-CV keywords both cause the control vector to be included in a TR-31 optional block, but each has a different purpose:
ATTR-CV
Causes a copy of the control vector to be included, but both the TR-31 usage and mode of use fields in the non-optional part of the TR-31 key block header are set to IBM® proprietary values. These values, described in TR-31 optional block data, indicate that the usage and mode information are specified in the control vector of the optional block and not in the TR-31 header. The restrictions imposed by the setting of the relevant access control points are bypassed, and any CCA key can be exported as long as the export control fields in the control vector allow it.
INCL-CV
Causes a copy of the control vector to be included as additional detail. The resulting attributes set in the non-optional part of the TR-31 key block header are identical to not using either keyword, except that the value for the number of optional blocks is increased by one. The export operation is still subject to the restrictions imposed by the settings of the relevant access control points.

Starting with CCA Release 8.1, TR-31 key tokens can be used in parameters unwrap_key_identifier and wrap_kek_identifier to wrap and unwrap CCA DES tokens, CCA AES tokens, CCA HMAC tokens, and other TR-31 tokens. When unwrapping a DES token, the TR-31 KEK must have the following attributes:

  • TR-31 key usage: K0 or K1
  • Algorithm: A or T
  • TR-31 mode of key use: E

When wrapping a DES token, the TR-31 KEK must have the following attributes:

  • TR-31 key usage: K0 or K1
  • Algorithm: A or T
  • TR-31 mode of key use: E

When unwrapping an AES or HMAC token, the TR-31 KEK must have the following attributes:

  • TR-31 key usage: K0 or K1
  • Algorithm: A
  • TR-31 mode of key use: E

When wrapping an AES of HMAC token, the TR-31 KEK must have the following attributes:

  • TR-31 key usage: K0 or K1
  • Algorithm: A
  • TR-31 mode of key use: E
Note:
  • For 'K*' key usage, use 'K0' if wrapping a CCA token, and use 'K1' if wrapping a TR-31 token.
  • The additional usage restriction defined for CCA KEKs require an optional block.

Starting with Release 8.1, you can use the CSNBT31X verb to switch a TR-31 key token from internal to external or the other way round. Use the Key Context rule group for this. When translating a TR-31 token from external to internal or the other way round, all normal rule array parameters must be specified. The TR-31 key usage and mode of key use rule array parameters must match the usage and mode of the source key identifier. When translating a TR-31 token, any DES, AES, and HMAC TR-31 tokens can be translated by placing them in the source_key_identifier unless compliance-tag keywords are set.

Exportability applies as follows:

  • T31-int to T31-ext: Exportability of T31-int is enforced for the KEK that will wrap the T31-ext. You can pass a new exportability value. The new exportability value goes in the T31-ext and impacts the receivers of the T31-ext when they import it. It has no bearing on the wrapping (in verb CSNBT31X) of the output T31-ext in CSNBT31X.
  • T31-ext to T31-int: The exportability is copied from the T31-ext token into the T31-int token. You can make the exportability more restrictive on import, but not less.
  • T31-ext to T31-ext: Exportability can be made more restrictive on import, but not less.
Note: CCA AES internal tokens with attributes DKPINOP, DKPINOPP, DKPINAD1, or DKPINAD2 will not be translated to TR-31 internal key-blocks.

TR-31 external tokens with the IBM Control Vector in the IBM optional block are designed for reconstruction to a CCA key token on import and thus do not directly translate to a TR-31 internal token. You should first import the TR-31 external token to a CCA internal token with the CV, then translate that to an TR-31 internal format. Translating TR-31 to TR-31 with an IBM Control Vector optional block results in an error.

Note: ATTR-CV and INCL-CV are not valid with an input TR-31 token. Additionally, neither parameter is valid with INTERNAL in the rule array.

The only partial key tokens that may be exported are CCA DES key tokens when using either the ATTR-CV or INCL-CV rules. This behavior may be prohibited by setting the ACP at offset X’006E’ to ON (T31X - Disallow Partial DES Key Export with CV in IBMC01 OB).

With PCI-HSM 2016, CCA introduces compliance-tagged key support for domains that enter compliance mode. Compliance-tagged TDES keys may be converted to or from TR-31 key blocks. The wrapping key encrypting key (KEK) must be compliance-tagged as well as the key to be exported or imported. A compliance-tagged KEK cannot be used to import or export a key that is not compliance-tagged.

Starting in 8.1, compliance-tagged TR-31 key tokens are supported, meaning that CSNBT31X can build compliance-tagged tokens. The compliance tag is specified in the IBM proprietary optional block, which has a block ID X’3130 (ASCII ’10’) and TLV X’3032’ (ASCII ’02’). The compliance tag flag is set in the first byte of data (bit 5) and the following three bytes are used as the KDF indicator (the last of these bytes will be set to 0x04 to indicate that there is a compliance tag for TR-31).

To help with compliance-tagged TR-31 keys, two keywords are available in the Wrapping Method rule array group:

  • COMP-CHK: Checks to see if the key token can be compliance-tagged. This input token can be internal or external. If the input key token already has a compliance tag, return code and reason code 8/2418 is returned. If the key token can be compliance-tagged, return code and reason code 0/0 is be returned. This does not change the token in any way, but this keyword must be specified without any other keywords.
  • COMP-TAG: Changes the key token to a compliance-tagged key token. The input token must be an internal token. The token is re-wrapped using the compliance tag method and returned with the KDF bytes and compliance tag bit set in the IBM optional block (which is added if it was not already present). The other attributes of the key (usage, mode, context, key field length (KFL), etc.) stay the same. This keyword must be specified without any other keywords and you must be in migration mode to use this.

Additionally, the CSNBT31X verb can change compliance-tagged tokens that are sent in when in active compliance mode. You can translate an input comp-tagged token in the following ways:

Table 1. Translating input compliance-tagged tokens for CSNBT31X
Rule array keyword source_key_identifier unwrap_key_identifier wrap_key_identifier t31_key_block
STOREXCH or EXCHANGE Internal TR-31 compliance-taggedtoken N/A Compliance-tagged KEK External TR-31 token wrapped by compliance-tagged KEK
INTERNAL External TR-31 token Compliance-tagged KEK N/A Internal TR-31 compliance-tagged token

For TR-31 tokens in the source_key_identifier. In the case that COMP-TAG is specified, the TR-31 source_key_identifier must be an internal TR-31 token, and it is limited to the following attributes:

  • TR-31 key usage: * (any usage)
  • Algorithm: A or T
  • TR-31 mode of key use: * (any mode of use)
  • Exportable: E or N

This is because keys that are single-DES (Algorithm D) cannot be compliance-tagged and so the command does not run, and an error is returned. In addition, the Exportability S option also does not meet the requirements for compliance-tagging.

In the case that COMP-CHK is specified, the TR-31 key token in the source_key_identifier parameter can be an internal or external TR-31 token.