Trusted block section X'12' subsections

Section X'12' has five rule subsections (tag-length-value objects) defined.

These subsections are summarized in Table 1.

Table 1. Summary of trusted block X'12'subsections
Rule subsection tag	TLV object	Optional or required	Comments
X'0001'	Transport key variant	Optional	Contains variant to be XORed into the cleartext transport key.
X'0002'	Transport key rule reference	Optional; required to use an RKX key-token as a transport key	Contains the rule ID for the rule that must have been used to create the transport key.
X'0003'	Common export key parameters	Optional for key generation; required for key export of an existing key	Contains the export key and source key minimum and maximum lengths, an output key variant length and variant, a CV length, and a CV to be XORed with the cleartext transport key to control usage of the key.
X'0004'	Source key reference	Optional; required if the source key is an RKX key-token	Contains the rule ID for the rule used to create the source key. Note: Include all rules that will ever be needed when a trusted block is created. A rule cannot be added to a trusted block after it has been created.
X'0005'	Export key CCA token parameters	Optional; used for export of CCA DES key tokens only	Contains mask length, mask, and CV template to limit the usage of the exported key. Also contains the template length and template that defines which source key labels are allowed. The key type of a source key input parameter can be "filtered" by using the export key CV limit mask (offset 005) and limit template (offset 005 + yyy) in this subsection.

Note: See Number representation in trusted blocks.

Trusted block section X'12' subsection X'0001'

Subsection X'0001' of the trusted block rule section (X'12') is the transport key variant TLV object. This subsection is optional. It contains a variant to be XORed into the cleartext transport key.

This subsection is defined in Table 2.

Table 2. Transport key variant subsection (X'0001') of trusted block rule section (X'12')
Offset (bytes)	Length (bytes)	Description
000	002	Subsection tag: (X'0001') Transport key variant TLV object
002	002	Subsection length in bytes (8 + nnn).
004	001	Subsection version number (X'00').
005	002	Reserved, must be binary zero.
007	001	Length of variant field in bytes (nnn). This length must be greater than or equal to the length of the transport key that is identified by the transport_key_identifier parameter. If the variant is longer than the key, truncate it on the right to the length of the key prior to use.
008	nnn	Transport key variant. XOR this variant into the cleartext transport key, provided: (1) the length of the variant field value (offset 007) is not zero, and (2) the symmetric encrypted output key format flag (offset 018 in section X'12') is X'01'. Note: A transport key is not used when the symmetric encrypted output key is in RKX key-token format.

Note: See Number representation in trusted blocks.

Trusted block section X'12' subsection X'0002'

Subsection X'0002' of the trusted block rule section (X'12') is the transport key rule reference TLV object. This subsection is optional. It contains the rule ID for the rule that must have been used to create the transport key. This subsection must be present to use an RKX key-token as a transport key.

This subsection is defined in Table 3.

Table 3. Transport key rule reference subsection (X'0002') of trusted block rule section (X'12')
Offset (bytes)	Length (bytes)	Description
000	002	Subsection tag: X'0002' Transport key rule reference TLV object
002	002	Subsection length in bytes (14).
004	001	Subsection version number (X'00').
005	001	Reserved, must be binary zero.
006	008	Rule ID. Contains the rule identifier for the rule that must have been used to create the RKX key-token used as the transport key. The Rule ID is an 8-byte string of ASCII characters, left-aligned and padded on the right with space characters. Acceptable characters are A - Z, a - z, 0 - 9, - (X'2D'), and _ (X'5F'). All other characters are reserved for future use.

Note: See Number representation in trusted blocks.

Trusted block section X'12' subsection X'0003'

Subsection X'0003' of the trusted block rule section X'12') is the common export key parameters TLV object. This subsection is optional, but is required for the key export of an existing source key (identified by the source_key_identifier parameter) in either RKX key-token format or CCA DES key-token format. For new key generation, this subsection applies the output key variant to the cleartext generated key, if such an option is desired. It contains the input source key and output export key minimum and maximum lengths, an output key variant length and variant, a CV length, and a CV to be XORed with the cleartext transport key.

This subsection is defined in Table 4.

Table 4. Common export key parameters subsection (X'0003') of trusted block rule section (X'12')
Offset (bytes)	Length (bytes)	Description
000	002	Subsection tag: X'0003' Common export key parameters TLV object
002	002	Subsection length in bytes (12 + xxx + yyy).
004	001	Subsection version number (X'00').
005	002	Reserved, must be binary zero.
007	001	Flags (must be set to binary zero).
008	001	Export key minimum length in bytes. Length must be 0, 8, 16, or 24. Also applies to the source key. Not applicable for key generation.
009	001	Export key maximum length in bytes (yyy). Length must be 0, 8, 16, or 24. Also applies to the source key. Not applicable for key generation.
010	001	Output key variant length in bytes (xxx). Valid values are 0 or 8 - 255. If greater than 0, the length must be at least as long as the longest key ever to be exported using this rule. If the variant is longer than the key, truncate it on the right to the length of the key prior to use. Note: The output key variant (offset 011) is not used if this length is zero.
011	xxx	Output key variant. The variant can be any value. XOR this variant into the cleartext value of the output key.
011 + xxx	001	CV length in bytes (yyy). If the length is not 0, 8, or 16, return an error. If the length is 0, and if the source key is a CCA DES key-token, preserve the CV in the symmetric encrypted output if the output is to be in the form of a CCA DES key-token. If a nonzero length is less than the length of the key identified by the source_key_identifier parameter, return an error. If the length is 16, and if the CV (offset 012 + xxx) is valued to 16 bytes of X'00' (ignoring the key-part bit), then: Ignore all CV bit definitions If CCA DES key-token format, set the flag byte of the symmetric encrypted output key to indicate a CV value is present. If the source key is eight bytes in length, do not replicate the key to 16 bytes
012 + xxx	yyy	CV. (See Control vector table.) Place this CV into the output exported key-token, provided that the symmetric encrypted output key format selected (offset 018 in rule section) is CCA DES key-token. If the symmetric encrypted output key format flag (offset 018 in section X'12') indicates return an RKX key-token (X'00'), then ignore this CV. Otherwise, XOR this CV into the cleartext transport key. XOR the CV of the source key into the cleartext transport key if the CV length (offset 011 + xxx) is set to 0. If a transport key to encrypt a source key has equal left and right key halves, return an error. Replicate the key halves of the key identified by the source_key_identifier parameter whenever all of these conditions are met: The Key Generate - SINGLE-R command (offset X'00DB') is enabled in the active role The CV length (offset 011 + xxx) is 16, and both CV halves are nonzero The source_key_identifier parameter (contained in either a CCA DES key-token or RKX key-token) identifies an 8-byte key The key-form bits (40 - 42) of this CV do not indicate a single-length key (are not set to zero) Key-form bit 40 of this CV does not indicate the key is to have guaranteed unique halves (is not set to B'1'). See Key form bits, 'fff' and 'FFF'. Note: A transport key is not used when the symmetric encrypted output key is in RKX key-token format.

Note: See Number representation in trusted blocks.

Trusted block section X'12' subsection X'0004'

Subsection X'0004' of the trusted block rule section (X'12') is the source key rule reference TLV object. This subsection is optional, but is required if using an RKX key-token as a source key (identified by source_key_identifier parameter). It contains the rule ID for the rule used to create the export key. If this subsection is not present, an RKX key-token format source key will not be accepted for use.

This subsection is defined in Table 5.

Table 5. Source key rule reference subsection (X'0004') of trusted block rule section (X'12')
Offset (bytes)	Length (bytes)	Description
000	002	Subsection tag: X'0004' Source key rule reference TLV object
002	002	Subsection length in bytes (14).
004	001	Subsection version number (X'00').
005	001	Reserved, must be binary zero.
006	008	Rule ID. Rule identifier for the rule that must have been used to create the source key. The Rule ID is an 8-byte string of ASCII characters, left-aligned and padded on the right with space characters. Acceptable characters are A - Z, a - z, 0 - 9, - (X'2D'), and _ (X'5F'). All other characters are reserved for future use.

Note: See Number representation in trusted blocks.

Trusted block section X'12' subsection X'0005'

Subsection X'0005' of the trusted block rule section (X'12') is the export key CCA token parameters TLV object. This subsection is optional. It contains a mask length, mask, and template for the export key CV limit. It also contains the template length and template for the source key label. When using a CCA DES key-token as a source key input parameter, its key type can be "filtered" by using the export key CV limit mask (offset 005) and limit template (offset 005+yyy) in this subsection.

This subsection is defined in Table 6.

Table 6. Export key CCA token parameters subsection (X'0005') of trusted block rule section (X'12')
Offset (bytes)	Length (bytes)	Description
000	002	Subsection tag: X'0005' Export key CCA token parameters TLV object
002	002	Subsection length in bytes (8 + yyy + yyy + zzz).
004	001	Subsection version number (X'00').
005	002	Reserved, must be binary zero.
007	001	Flags (must be set to binary zero).
008	001	Export key CV limit mask length in bytes (yyy). Do not use CV limits if this CV limit mask length (yyy) is zero. Use CV limits if yyy is nonzero, in which case yyy: Must be 8 or 16 Must not be less than the export key minimum length (offset 008 in subsection X'0003') Must be equal in length to the actual source key length of the key Example: An export key minimum length of 16 and an export key CV limit mask length of 8 returns an error.
009	yyy	Export key CV limit mask (does not exist if yyy=0). See DES control-vector base bit maps Indicates which CV bits to check against the source key CV limit template (offset 009 + yyy). Examples: A mask of X'FF' means check all bits in a byte. A mask of X'FE' ignores the parity bit in a byte.
009 + yyy	yyy	Export key CV limit template (does not exist if yyy = 0). Specifies the required values for those CV bits that are checked based on the export key CV limit mask (offset 009). (See DES control-vector base bit maps.) The export key CV limit mask and template have the same length, yyy. This is because these two variables work together to restrict the acceptable CVs for CCA DES key tokens to be exported. The checks work as follows: If the length of the key to be exported is less than yyy, return an error Logical AND the CV for the key to be exported with the export key CV limit mask Compare the result to the export key CV limit template Return an error if the comparison is not equal Examples: An export key CV limit mask of X'FF' for CV byte 1 (key type) along with an export key CV limit template of X'3F' (key type CVARENC) for byte 1 filters out all key types except CVARENC keys. Note: Using the mask and template to permit multiple key types is possible, but cannot consistently be achieved with one rule section. For example, setting bit 10 to B'1' in the mask and the template permits PIN processing keys and cryptographic variable encrypting keys, and only those keys. However, a mask to permit PIN-processing keys and key-encrypting keys, and only those keys, is not possible. In this case, multiple rule sections are required, one to permit PIN-processing keys and the other to permit key-encrypting keys.
009 + yyy + yyy	001	Source key label template length in bytes (zzz). Valid values are 0 and 64. Return an error if the length is 64 and a source key label is not provided.
010 + yyy + yyy	zzz	Source key label template (does not exist if zzz = 0). If a key label is identified by the source_key_identifier parameter, verify that the key label name matches this template. If the comparison fails, return an error. The source key label template must conform to the following rules: The key label template must be 64 bytes in length The first character cannot be in the range X'00' - X'1F', nor can it be X'FF' The first character cannot be numeric (X'30' - X'39') A key label name is terminated by a space character (X'20') on the right and must be padded on the right with space characters The only special characters permitted are #, $, @, and * (X'23', X'24', X'40', and X'2A') The wildcard X'2A' (*) is permitted only as the first character, the last character, or the only character in the template Only alphanumeric characters (a - z, A - Z, 0 - 9), the four special characters (X'23', X'24', X'40', and X'2A'), and the space character (X'20') are allowed

Note: See Number representation in trusted blocks.