z/OS Cryptographic Services ICSF System Programmer's Guide
Previous topic | Next topic | Contents | Index | Contact z/OS | Library | PDF


Variable-length Symmetric Key Token

z/OS Cryptographic Services ICSF System Programmer's Guide
SA22-7520-17

The following table presents the presents the format for a variable-length symmetric key token. The length of the token depends on the key type and algorithm.

Table 52. Variable-length Symmetric Key Token
Offset (Dec)Length of Field (Bytes)Description
Header
01Token flag
X'00'
for null token
X'01'
for internal tokens
X'02'
for external tokens
11Reserved (X'00')
22Length of the token in bytes
41Token version number X'05'
53Reserved (X'000000')
Wrapping information
81Key material state.
X'00'
no key present (internal or external)
X'01'
key is clear (internal)
X'02'
key is encrypted under a key-encrypting key (external)
X'03'
key is encrypted under the master key (internal)
91Key verification pattern (KVP) type.
X'00'
No KVP
X'01'
AES master key verification pattern
X'02'
key-encrypting key verification pattern
1016Verification pattern of the key used to wrap the payload. Value is left justified.
261Wrapping method - This value indicates the wrapping method used to protect the data in the encrypted section.
X'00'
key is in the clear
X'02'
AESKW
X'03'
PKOAEP2
271Hash algorithm used in wrapping algorithm.
  • For wrapping method X'00'
    X'00'
    None. For clear key tokens.
  • For wrapping method X'02'
    X'02'
    SHA-256
  • For wrapping method X'03'
    X'01'
    SHA-1
    X'02'
    SHA-256
    X'04'
    SHA-384
    X'08'
    SHA-512
282Reserved (X'0000')
AESKW Components: Associated data and clear key or encrypted AESKW payload
Associated data section
301Associated data version (X'01')
311Reserved (X'00')
322Length of the associated data in bytes: adl
341Length of the key name in bytes: kl
351Length of the IBM extended associated data in bytes: iead
361Length of the installation-definable associated data in bytes: uad
371Reserved (X'00')
382Length of the payload in bits: pl
401Reserved (X'00')
411Type of algorithm for which the key can be used
X'02'
AES
X'03'
HMAC
422Key type:

For algorithm AES:

X'0001'
CIPHER
X'0003'
EXPORTER
X'0004'
IMPORTER

For algorithm HMAC:

X'0002'
MAC
441Key-usage field count (kuf) - (1 byte)
45kuf * 2Key-usage fields (kuf * 2 bytes)
  • For HMAC algorithm keys, refer to Table 53.
  • For AES algorithm Key-Encrypting Keys (Exporter or Importer), refer to Table 54.
  • For AES algorithm Cipher Keys, refer to Table 55.
45 + kuf * 21Key-management field count (kmf): 2 (no pedigree information) or 3 (has pedigree information)
46 + kuf * 22Key-management field 1

High-order byte:

1xxx xxxx
Allow export using symmetric key
x1xx xxxx
Allow export using unauthenticated asymmetric key
xx1x xxxx
Allow export using authenticated asymmetric key
xxx1 xxxx
Allow export in RAW format.

All other bits are reserved and must be zero.

Low-order byte:

--symmetric--

1xxx xxxx
Prohibit export using DES key.
x1xx xxxx
Prohibit export using AES key.

--asymmetric--

xxxx 1xxx
Prohibit export using RSA key.

All other bits are reserved and must be zero.

48 + kuf * 22Key-management field 2

High-order byte:

11xx xxxx
Key, if present, is incomplete. Key requires at least 2 more parts.
10xx xxxx
Key, if present, is incomplete. Key requires at least 1 more part.
01xx xxxx
Key, if present, is incomplete. Key can be completed or have more parts added.
00xx xxxx
Key, if present, is complete. No more parts can be added.

All other bits are reserved and must be zero.

Low-order byte (Security History):

xxx1 xxxx
Key was encrypted with an untrusted KEK
xxxx 1xxx
Key was in a format without type/usage attributes
xxxx x1xx
Key was encrypted with key weaker than itself
xxxx xx1x
Key was in a non-CCA format
xxxx xxx1
Key was encrypted in ECB mode.

All other bits are reserved and must be zero.

50 + kuf * 22Key-management field 3 - Pedigree (this field may or may not be present)

Indicates how key was originally created and how it got into the current system.

High-order byte: Pedigree Original.

X'00'
Unknown (Key Token Build2, Key Translate2)
X'01'
Other - method other than those defined here, probably used in UDX
X'02'
Randomly Generated (Key Generate2)
X'03'
Established by key agreement (ECC Diffie-Hellman)
X'04'
Created from cleartext key components (Key Part Import2)
X'05'
Entered as a cleartext key value (Key Part Import2, Secure Key Import2)
X'06'
Derived from another key
X'07'
Cleartext keys or key parts that were entered at TKE and secured from there to the target card (operational key load)

All unused values are reserved and undefined.

Low-order byte: Pedigree Current.

X'00'
Unknown (Key Token Build2)
X'01'
Other - method other than those defined here, probably used in UDX
X'02'
Randomly Generated (Key Generate2)
X'03'
Established by key agreement (ECC Diffie-Hellman)
X'04'
Created from cleartext key components (Key Part Import2)
X'05'
Entered as a cleartext key value (Key Part Import2, Secure Key Import2)
X'06'
Derived from another key
X'07'
Imported from a CCA 05 variable length token with pedigree field (Symmetric Key Import2)
X'08'
Imported from a CCA 05 variable length token with no pedigree field (Symmetric Key Import2)
X'09'
Imported from a CCA token that had a CV
X'0A'
Imported from a CCA token that had no CV or a zero CV
X'0B'
Imported from a TR-31 key block that contained a CCA CV (ATTR-CV option) (TR-31 Import)
X'0C'
Imported from a TR-31 key block that did not contain a CCA CV (TR-31 Import)
X'0D'
Imported using PKCS 1.2 RSA encryption (Symmetric Key Import2)
X'0E'
Imported using PKCS OAEP encryption (Symmetric Key Import2)
X'0F'
Imported using PKA92 RSA encryption (Symmetric Key Import2)
X'10'
Imported using RSA ZERO-PAD encryption (Symmetric Key Import2)
X'11'
Converted from a CCA token that had a CV (Key Translate2)
X'12'
Converted from a CCA token that had no CV or a zero CV (Key Translate2)
X'13'
Cleartext keys or key parts that were entered at TKE and secured from there to the target card (operational key load)
X'14'
Exported from a CCA 05 variable length token with pedigree field (Symmetric Key Export)
X'15'
Exported from a CCA 05 variable length token with no pedigree field (Symmetric Key Export)
X'16'
Exported using PKCS OAEP encryption (Symmetric Key Export)

All unused values are reserved and undefined.

46 + kuf * 2 + kmf * 2klKey name
46 + kuf * 2 + kmf * 2 + klieadIBM extended associated data
46 + kuf * 2 + kmf * 2 + kl + ieaduadInstallation-defined associated data
Clear key or encrypted payload
30 + adl(pl+7)/8

Encrypted AESKW payload (internal keys): The encrypted AESKW payload is created from the unencrypted AESKW payload which is made up of the ICV/pad length/hash options and hash length/hash options/hash of the associated data/key material/padding. See unencrypted AESKW payload below.

Encrypted PKOAEP2 payload (external keys): The encrypted PKOAEP2 payload is created using the PKCS #1 v1.2 encoding method for a given hash algorithm. The message (M) inside the encoding contains: [2 bytes: bit length of key] || [clear HMAC key]. M is encoded using OAEP and then encrypted with an RSA public key according to the standard.

Clear key payload: When the key is clear, only the key material will be in the payload padded to the nearest byte with binary zeros.

30 + adl + (pl+7)/8End of AESKW components
Unencrypted AESKW payload (This data will never appear in the clear outside of the cryptographic coprocessor)
06Integrity check value.

Six byte constant: X'A6A6A6A6A6A6'.

61Length of the padding in bits: pb
71Length of hash options and hash of the associated data in bytes (hoh)
84Hash options
12hoh - 4Hash of the associated data
8 + hoh(pl/8) - 8 - hohKey data and padding (key data is left justified).
pl/8pl is the bit length of the payload
Table 53. HMAC Algorithm Key-usage fields
Offset (Dec)Length of Field (Bytes)Description
441Key-usage field count (kuf): 2
452Key-usage field 1

High-order byte:

1xxx xxxx
Key can be used for generate.
x1xx xxxx
Key can be used for verify.

All unused bits are reserved and must be zero.

Low-order byte:

xxxx 1xxx
The key can only be used in UDXs (used in KGN, KIM, KEX).
xxxx 0xxx
The key can be used in both UDXs and CCA.
xxxx xuuu
Reserved for UDXs, where uuu are UDX-defined bits.

All unused bits are reserved and must be zero.

472Key-usage field 2

High-order byte:

1xxx xxxx
SHA-1 hash method is allowed for the key.
x1xx xxxx
SHA-224 hash method is allowed for the key.
xx1x xxxx
SHA-256 hash method is allowed for the key.
xxx1 xxxx
SHA-384 hash method is allowed for the key.
xxxx 1xxx
SHA-512 hash method is allowed for the key.

All unused bits are reserved and must be zero.

Low-order byte:

All bits are reserved and must be zero.

Table 54. AES Algorithm KEK Key-usage fields
Offset (Dec)Length of Field (Bytes)Description
441Key-usage field count (kuf): 4
452Key-usage field 1

High-order byte for EXPORTER:

1xxx xxxx
Key can be used for EXPORT.
x1xx xxxx
Key can be used for TRANSLAT.
xx1x xxxx
Key can be used for GENERATE-OPEX.
xxx1 xxxx
Key can be used for GENERATE-IMEX.
xxxx 1xxx
Key can be used for GENERATE-EXEX.
xxxx x1xx
Key can be used for GENERATE-PUB.

All unused bits are reserved and must be zero.

High-order byte for IMPORTER:

1xxx xxxx
Key can be used for IMPORT.
x1xx xxxx
Key can be used for TRANSLAT.
xx1x xxxx
Key can be used for GENERATE-OPIM.
xxx1 xxxx
Key can be used for GENERATE-IMEX.
xxxx 1xxx
Key can be used for GENERATE-IMIM.
xxxx x1xx
Key can be used for GENERATE-PUB.

All unused bits are reserved and must be zero.

Low-order byte:

xxxx 1xxx
The key can only be used in UDXs (used in KGN, KIM, KEX).
xxxx 0xxx
The key can be used in both UDXs and CCA.
xxxx xuuu
Reserved for UDXs, where uuu are UDX-defined bits.

All unused bits are reserved and must be zero.

472Key-usage field 2

High-order byte:

1xxx xxxx
Key can wrap a TR-31 key.

All unused bits are reserved and must be zero.

Low-order byte:

xxxx xxx1
This KEK can export a key in RAW format.

All unused bits are reserved and must be zero

492

Key-usage field 3

High-order byte:

1xxx xxxx
Key can wrap DES keys
x1xx xxxx
Key can wrap AES keys
xx1x xxxx
Key can wrap HMAC keys
xxx1 xxxx
Key can wrap RSA keys
xxxx 1xxx
Key can wrap ECC keys

All unused bits are reserved and must be zero.

Low-order byte:

All bits are reserved and must be zero.

512

Key-usage field 4

High-order byte:

1xxx xxxx
Key can wrap DATA class keys
x1xx xxxx
Key can wrap KEK class keys
xx1x xxxx
Key can wrap PIN class keys
xxx1 xxxx
Key can wrap DERIVATION class keys
xxxx 1xxx
Key can wrap CARD class keys

All unused bits are reserved and must be zero.

Low-order byte:

All bits are reserved and must be zero.

Table 55. AES Algorithm Cipher Key Associated Data
Offset (Dec)Length of Field (Bytes)Description
441Key-usage field count (kuf): 2
452

Key-usage field 1

High-order byte:

1xxx xxxx
Key can be used for encryption.
x1xx xxxx
Key can be used for decryption.

All unused bits are reserved and must be zero.

Low-order byte:

xxxx 1xxx
The key can only be used in UDXs (used in KGN, KIM, KEX).
xxxx 0xxx
The key can be used in both UDXs and CCA.
xxxx xuuu
Reserved for UDXs, where uuu are UDX-defined bits.

All unused bits are reserved and must be zero.

472

Key-usage field 2

High-order byte:

X'00'
Key can be used for Cipher Block Chaining (CBC).
X'01'
Key can be used for Electronic Code Book (ECB).
X'02'
Key can be used for Cipher Feedback (CFB).
X'03'
Key can be used for Output Feedback (OFB).
X'04'
Key can be used for Galois/Counter Mode (GCM)
X'05'
Key can be used for XEX-based Tweaked CodeBook Mode with CipherText Stealing (XTS)

All unused values are reserved and must not be used.

Low-order byte:

All bits are reserved and must be zero.

Go to the previous page Go to the next page




Copyright IBM Corporation 1990, 2014