DES key wrapping

Impacts of WRAPENH3 protected TDES tokens in customer applications

Read some notes about potential application use case impacts due to the implementation of WRAPENH3 protected TDES tokens.

Use case 1:

Issue with Use case 1:

If the user key has 1 or more 8-byte sections with a 0x00 value at the end, then CCA calculates the key length from just the non-0x00 byte sections. For example, a key with value 0x123456781234567812345678123456780000000000000000 is calculated as a 16-byte key. A key with value 0x123456781234567800000000000000000000000000000000 is considered as an 8-byte key.

Firmware handling of Use case 1:

CCA returns an error (return code 8, reason code 1085) when detecting these cases:

1. When CCA firmware detects that re-wrap of a key from a legacy key wrap to a WRAPENH3-protected TDES token would result in the key being considered shorter than it was before, this error is returned.
2. When CCA firmware detects that import of a key (by key part or from an external form) to a WRAPENH3-protected TDES token would result in a key that is considered shorter than it was before, the this error (return code 8, reason code 1085) is also returned.

Workaround for Use case 1:

1. When importing a key by parts, do not start with a part that has 8 byte sections of 0x00 bytes at the end.
2. When the new error (return code 8, reason code 1085) is seen for changing or importing a key to a form that is WRAPENH3, create a new key that is the required strength and migrate the data protected by the weaker key to be protected by the new key.

Use case 2:

When WRAPENH3 is used to protect a TDES key in a CCA key token, the length of the clear key cannot be determined by inspecting the encrypted key token.

Issues with Use case 2:

1. Use cases where a WRAPENH3 protected TDES token with a key in it is passed for some key management, or where key derivation services are not possible. A legacy application may expect to use a key token with a key in it, instead of a key skeleton, which has no key. CCA cannot tell the key length needed when presented with a WRAPENH3 token, because the length is hidden.
2. For these legacy use cases, CCA does not decrypt the input key, CCA uses the control vector (CV) to determine key attributes needed for the key to be created or derived. For a new WRAPENH3-protected key token, this is not possible. The key must be decrypted to determine the length.
3. Skeletons which have the 'KEY' flag set to binary 1 but do not have key material will also be impacted by this use case. These skeletons are malformed as they indicate a key is contained but do not contain a key and will result in the same error.

Handling of Use case 2:

When this case is detected, an error (return code 8, reason code 1083) is returned, which indicates that a skeleton token is needed.

Examples:

a) CSNBFPED, parameter DUKPT_PIN_key_identifier: If the derived key is to be WRAPENH3 protected, the input parameter must be a key skeleton to properly indicate the needed key length.

b) CSNBKGN, parameters generated_key_identifier_1, generated_key_identifier_2: If the generated key(s) are passed as complete WRAPENH3-protected TDES tokens, it is not possible to determine the desired key length based on an encrypted input token. Some users may have a practice of using legacy keys for these parameters, or external keys, for which the wrapping key has passed out of use. For this reason, a skeleton with the same control vector (CV) is needed instead of a complete encrypted token.

Use case 3:

Legacy CCA service CSNBCVT does not support WRAPENH3 tokens.

Issue with Use case 3:

The CSNBCVT service involves manipulating the encrypted and decrypted sections of key tokens in ways that rely on the key token being wrapped with TDES-ECB encryption. The integrity checking inherent to the WRAPENH3 method does not allow manipulation of encrypted portions of the key token.

Handling of Use case 3:

An error (return code 8, reason code 2161) is returned when a WRAPENH3-protected TDES token is presented for any CSNBCVT key_identifier parameter.

Use case 4:

When using the host-based wrapping keyword override to specify WRAPENH3 to key management services, such as the CSU_WRAP_OVERRIDE environment variable, there is an extra access control check triggered in CCA firmware.

Issue with Use case 4:

When the host-based wrapping method override control indicates to add the WRAPENH3 keyword where no wrapping keyword was indicated, this will trigger checking of the verb-unique wrapping override access control point (ACP).

Example:

The CSNBUKDJ service override ACP is at offset 0x01CA. When using the host-based wrapping method override, this ACP must be set to ON for the use of WRAPENH3 keyword to succeed.

Workaround for Use case 4:

1. All wrapping control override ACPs have ON as their default setting in the IBM Z® default role for each domain, allowing this use case.
2. A configuration that has been migrated forward across several HSM levels may not be carrying ON values for these ACPs. A Trusted Key Entry workstation needs to be used to set these ACPs to allow the behavior.

Use case 5:

When using the host-based wrapping keyword override to specify WRAPENH3 to key management services, such as the CSU_WRAP_OVERRIDE environment variable, note that wrapping method WRAPENH3 is not usable for a control vector (CV) with all 8 bytes set to value 0x00.

Issue with Use case 5:

All CCA services that make keys with a zero CV (with all bytes of 0x00) will return error (return code 8, reason code 175) if the token is also requested to be wrapped with WRAPENH3.

Workaround for Use case 5:

Migrate legacy key tokens that use CV with all bytes set to 0x00 to a key type that uses a non-zero CV before migrating them to WRAPENH3.

ECB wrapping of DES keys (original method)

e*KEK(KL) || e*KEK(KR) = eKEKL(dKEKR(eKEKL(KL))) || eKEKL(dKEKR(eKEKL(KR)))

where:

KL

is the left 64 bits of *K

KR

is the right 64 bits of *K

KEKL

is the left 64 bits of *KEK

KEKR

is the right 64 bits of *KEK

||

means concatenation

d_*k(m) or e_*k(m)

means that message m is decrypted (d) or encrypted (e) with key *k.

Enhanced CBC wrapping of DES keys

e*KEK(*KL) = ecbcKEKL(dcbcKEKR(ecbcKEKL(KLPRIME || KR)))
KLPRIME = KL XOR SHA1(KR)

Wrapping key derivation for enhanced wrapping of DES keys

The wrapping key is exactly the same key that is used by the legacy wrapping method (the only method used by CCA 4.0.0), with one exception.

Instead of using the base key itself (master key or key-encrypting key), a key that is derived from that base key is used. The derived key will have the control vector applied to it in the standard CCA manner, and then use the resulting key to wrap the new-format target key token.

The reason for using a derived key is to ensure that no attacks against this wrapping scheme are possible using the existing CCA functions. For example, it was observed that an attack was possible by copying the wrapped key into an ECB CCA key token, if the wrapping key was used instead of a derivative of that key.

The key will be derived using a method defined in the U.S. National Institute of Standards and Technology (NIST) standard SP 800-108, Recommendation for Key Derivation Using Pseudorandom Functions (October, 2009). Derivation will use the method KDF in counter mode using pseudo-random function (PRF) HMAC-SHA256. This method provides sufficient strength for deriving keys for any algorithm used.

HMAC(K, text) = H((K0 XOR opad ) || H((K0 XOR ipad) || text))

If the key K is equal in length to the input block size of the hash function (512 bits for SHA-256), K0 is set to the value of K. Otherwise, K0 is formed from K by hashing or padding.

The Key Derivation Function (KDF) specification calls for inputs optionally including two byte strings, Label and Context. The Context will not be used. The Label will contain information on the usage of this key, to distinguish it from other derivations that CCA may use in the future for different purposes. Because the security of the derivation process is rooted in the security of the derivation key and in the HMAC and Key Derivation Functions (KDF) themselves, it is not necessary for this label string to be of any particular minimum size. The separation indicator byte of X'00' specified in the NIST document will follow the label.

ENHANCEDWRAP2010 (X'454E4841 4E434544 57524150 32303130’)