Usage notes

Edit online

The usage notes for CSNBT31I.

After being imported into a CCA key-token, the key and its attributes are ready to be used in a CCA system. The verb takes as input an external TR-31 key block and the internal DES IMPORTER or IKEYXLAT key-encrypting key of the key that was used to wrap the TR-31 key block.

The TR31 Key Import verb is analogous to the existing Key Import verb, except that TR31 Key Import accepts an external non-CCA DES key-token instead of an external CCA fixed-length DES key-token, and it translates the key to either an external or internal fixed-length DES key-token instead of only an internal fixed-length DES key-token. An import by TR31 Key Import to an external key-token requires a suitable internal fixed-length DES key-encrypting key. The purpose of both verbs is to import a DES key from another party.

An external-to-external translation would not normally be called an export or import operation. Instead, it would be called a key translation and would be handled by a verb such as Key Translate or Key Translate2. For practical reasons, the export of an external CCA DES key-token to an external TR-31 format is supported by the TR31 Translate verb, and the import of an external TR-31 key block to an external CCA DES key-token format is supported by the TR31 Key Import verb.

Prior to Release 5.4 and Release 6.2, the verb can only be used to import DES cryptographic keys from an external TR-31 key block wrapped under a DES key-encrypting key using key block version IDs (also called methods) "A", "B", or "C" based on ASC X9 TR 31-2018. The mechanism is designed to use AES as the unwrapping cipher. DES and TDES keys can be unwrapped with an 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 IMPORTER key-encrypting key with usage IMPTT31D (Release 5.4 and Release 6.2 or later) allowed is required for unwrapping the output TR-31 key block that contains a DES key. In addition, usage WR-DES must be allowed.

Support is available to import from an external TR-31 key block unwrapped under an AES key-encrypting key using a method based on ISO 20038:

  • AES keys can be unwrapped 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 IMPORTER key encrypting key with usage IMPTT31D (Release 5.4 or later) allowed is required for unwrapping the output TR-31 key block that contains an AES key. In addition, usage WR-AES must be allowed.

Support is available to import an external TR-31 key block wrapped under an 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 specified in the rule array. The ISO 20038 algorithm identifier "H" for SHA-1 hash limit of the key and algorithm identifier "I" for SHA-2 hash limit of the key are also supported. The hash algorithms recognized are: SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512. How CCA imports a TR-31 key block with algorithm "H" or "I" is determined based on the specification of the HMAC hash algorithm limit in the rule array.

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), 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 has been defined to specify which attribute is to be 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 control vector attributes are in any way incompatible with the attributes of the input key. In addition, access control points are defined that can be used to restrict the permitted attribute conversions.

The import operation produces the CCA external or internal fixed-length DES key-token as its output. It does not return any field values or optional block data from the TR-31 key block header. To obtain the header field values, use the TR31 Key Token Parse verb. To obtain optional block data from the header, use the TR31 Optional Data Read verb.

An optional control vector transport control rule-array keyword can be passed to the TR31 Translate verb. Such a keyword specifies that the verb is to copy the control vector from the CCA DES key into the TR-31 key block. A copy of the control vector is passed in an IBM-proprietary optional block. See TR-31 optional block data.

If the TR-31 key block contains an IBM-proprietary block, the TR31 Key Import verb verifies that the control vector is compatible with the attributes in the TR-31 key block. If any incompatibility is found, the verb rejects the import. If the control vector is valid for the key, the verb uses it for the control vector of the CCA DES key-token. Note that the import operation is always subject to the restrictions imposed by the relevant access control points, even if a control vector is received.

A control vector, if present, can be in the TR-31 key block in one of two ways, depending on the control vector transport control keyword specified in the rule array of the TR31 Translate verb when the key was exported. One keyword option is ATTR-CV, and the other is INCL-CV:
ATTR-CV
Causes a copy of the control vector to be included in the TR-31 key block. The TR-31 key usage and mode of use fields are set to IBM® proprietary. See TR-31 optional block data. These proprietary values indicate that the usage and mode information is contained in the included control vector. In this case, if the TR31 Key Import verb successfully verifies that the included control vector does not conflict with the rule-array keywords specified, it uses it as the control vector for the imported CCA DES key-token.
INCL-CV
Causes a copy of the control vector to be included in the TR-31 key block. The TR-31 key usage and mode of use fields contain attributes from the set defined in the TR-31 standard. In this case, the TR31 Key Import verb verifies that the usage and mode information in those fields are compatible with the included control vector. The verb also verifies that no rule array keywords conflict with the control vector.

Note that the included CV could have more capability from a CCA perspective than the TR-31 usage and mode fields indicate. This difference is not an error, because the key block binding methods give the importer assurance that the key block optional blocks are as secure as any other attribute.

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 with CCA Release 8.1, the CSNBT31I verb can build compliance-tagged TR-31 key tokens. The compliance tag in the TR-31 token to be imported 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 is set to 0x04 to indicate that there is a compliance tag for TR-31).

T31I will take in compliance-tagged TR-31 tokens and return a compliance tagged CCA token, if allowed. You must be in active compliance mode when sending in any compliance-tagged tokens to T31I. You can translate an input comp-tagged token in the following ways:

Table 1. Translating input compliance-tagged tokens for CSNBT31I

You can translate an input comp-tagged token in the following ways. Table with five columns showing Rule array keyword, source key identifier, unwrap key identifier, wrap key identifier, and TR-31 key block
Rule array keyword TR-31 key block Unwrap key identifier Wrap key identifier Output key identifier
INTERNAL Internal TR-31 compliance-tagged token N/A N/A Internal CCA compliance-tagged token
EXTERNAL Internal TR-31 compliance-tagged token N/A Compliance-tagged KEK External CCAtoken wrapped by compliance-tagged KEK
INTERNAL External TR-31 token Compliance-tagged KEK N/A Internal CCA compliance-tagged token
EXTERNAL External TR-31 token Compliance-tagged KEK Compliance-tagged KEK External CCA token wrapped by compliance-tagged KEK