Format of trusted block sections

At the beginning of every trusted block is a trusted block header. The header contains the following information:
  • A token identifier, which specifies whether the token contains an external or internal key-token.
  • A token version number to allow for future changes.
  • A length in bytes of the trusted block, including the length of the header.
The trusted block header is defined in the following table:
Table 1. Trusted block header
Offset (bytes) Length (bytes) Description
000 001 Token identifier (a flag that indicates token type)
X'1E'
External trusted block token.
X'1F'
Internal trusted block token.
001 001 Token version number (X'00').
002 002 Length of the key-token structure in bytes.
004 004 Reserved, binary zero.
Note: See Number representation in trusted blocks.

Following the header, in no particular order, are trusted block sections. There are five different sections that are defined, each identified by a one-byte section identifier (X'11' - X'15'). Two of the five sections have subsections that are defined. A subsection is a tag-length-value (TLV) object, which is identified by a two-byte subsection tag.

Only sections X'12' and X'14' have subsections that are defined; the other sections do not. A section and its subsections, if any, are one contiguous unit of data. The subsections are concatenated to the related section, but are otherwise in no particular order. Section X'12' has five subsections that are defined (X'0001' - X'0005'), and section X'14' has two (X'0001' and X'0002'). Of all the subsections, only subsection X'0001' of section X'14' is required. Section X'14' is also required.

The trusted block sections and subsections are described in detail in the following sections.

Trusted block section X'11'

Trusted block section X'11' contains the trusted RSA public key in addition to a key-usage flag indicating whether the public key is usable in key-management operations, digital signature operations, or both.

Section X'11' is optional. No multiple sections are allowed. It has no subsections that are defined.

This section is defined in the following table:

Table 2. Trusted block trusted RSA public-key section (X'11')
Offset (bytes) Length (bytes) Description
000 001 Section identifier:
X'11'
Trusted block trusted RSA public key.
001 001 Section version number (X'00').
002 002 Section length (16+xxx+yyy).
004 002 Reserved, must be binary zero.
006 002 RSA public-key exponent field length in bytes, xxx.
008 002 RSA public-key modulus length in bits.
010 002 RSA public-key modulus field length in bytes, yyy.
012 xxx
Public-key exponent, e (this field length is
typically 1, 3, or 64 - 512 bytes). e must be
odd and 1≤e<n. (e is frequently
valued to 3 or 216+1 (=65537),
otherwise e is of the same order of magnitude
as the modulus).
Note: Although the current product implementation does not generate such a public key, you can import an RSA public key having an exponent valued to two (2). Such a public key (a Rabin key) can correctly validate an ISO 9796-1 digital signature.
012+xxx yyy
RSA public-key modulus, n. n=pq, where p and q
are prime and 2512≤
n<24096.
The field length is 64 - 512 bytes.
012
+xxx+yyy
 004 Flags:
X'00000000'
Trusted block public key can be used in digital signature operations only.
X'80000000'
Trusted block public key can be used in both digital signature and key management operations.
X'C0000000'
Trusted block public key can be used in key management operations only.
Note: See Number representation in trusted blocks.

Trusted block section X'12'

Trusted block section X'12' contains information that defines a rule. A trusted block can have zero or more rule sections.

  1. A trusted block with no rule sections can be used by the PKA Key Token Change and PKA Key Import callable services. A trusted block with no rule sections can be used by the Digital Signature Verify verb, provided there is an RSA public-key section that has its key-usage flag set to allow digital signature operations.
  2. At least one rule section is required when the Remote Key Export verb is used to:
    • Generate an RKX key-token.
    • Export an RKX key-token.
    • Export a CCA DES key-token.
    • Generate or export a key encrypted by a public key. The public key is contained in a vendor certificate (section X'11'), and is the root certification key for the ATM vendor. It is used to verify the digital signature on public-key certificates for specific individual ATMs.
  3. If a trusted block has multiple rule sections, each rule section must have a unique 8-character Rule ID.
Section X'12' is the only section that is allowed to have multiple sections. Section X'12' is optional. Multiple sections are allowed.
Note: The overall length of the trusted block can not exceed its maximum size of 3500 bytes.

Five subsections (TLV objects) are defined.

This section is defined in the following table:

Table 3. Trusted block rule section (X'12')
Offset (bytes) Length (bytes) Description
Offset (bytes) Length (bytes) Description
000 001 Section identifier:
X'12'
Trusted block rule.
001 001 Section version number (X'00').
002 002 Section length in bytes (20+yyy).
004 008 Rule ID (in ASCII).

An 8-byte character string that uniquely identifies the rule within the trusted block.

Valid ASCII characters are: A...Z, a...z, 0...9, - (hyphen), and _ (underscore), left-justified and padded on the right with space characters.
012 004 Flags (undefined flag bits are reserved and must be zero).
X'00000000'
Generate new key.
X'00000001'
Export existing key.
016 001 Generated key length.

Length in bytes of key to be generated when flags value (offset 012) is set to generate a new key; otherwise, ignore this value. Valid values are 8, 16, or 24; return an error if not valid.
017 001 Key-check algorithm identifier (all others are reserved and must not be used):
Value
Meaning
X'00'
Do not compute key-check value. In a call to CSNDRKX or CSNFRKX, set the key_check_length variable to zero.
X'01'
Encrypt an 8-byte block of binary zeros with the key. In a call to CSNDRKX or CSNFRKX, set the key_check_length variable to 8.
X'02'
Compute the MDC-2 hash of the key. In a call to CSNDRKX or CSNFRKX, set the key_check_length variable to 16.
018 001 Symmetric encrypted output key format flag (all other values are reserved and must not be used).

Return the indicated symmetric key-token by using the sym_encrypted_key_identifier parameter.

Value
Meaning
X'00'
Return an RKX key-token encrypted under a variant of the MAC key.
Note: This is the only key format that is permitted when the flags value (offset 012) is set to generate a new key.
X'01'
Return a CCA DES key-token encrypted under a transport key.
Note: This is the only key format that is permitted when the flags value (offset 012) is set to export an existing key.
019 001 Asymmetric encrypted output key format flag (all other values are reserved and must not be used).

Return the indicated asymmetric key-token in the asym_encrypted_key variable.

Value
Meaning
X'00'
Do not return an asymmetric key. Set the asym_encrypted_key_length variable to zero.
X'01'
Output in PKCS1.2 format.
X'02'
Output in RSAOAEP format.
020 yyy Rule section subsections (tag-length-value objects). A series of 0 - 5 objects in TLV format.
Note: See Number representation in trusted blocks.
Section X'12' has five rule subsections (tag-length-value objects) defined. These subsections are summarized in the following table:
Table 4. Summary of trusted block rule subsection
Rule subsection tag TLV object Optional or required Comments
X'0001' Transport key variant Optional Contains variant to be exclusive-ORed 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 exclusive-ORed 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 exclusive-ORed into the cleartext transport key.

This subsection is defined in the following table:

Table 5. 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 before use.
008 nnn Transport key variant.
Exclusive-OR 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 the following table:
Table 6. 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-justified 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.

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 wanted. 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 exclusive-ORed with the cleartext transport key.

This subsection is defined in the following table:

Table 7. 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 8, 16, or 24.

Also applies to the source key.
009 001 Export key maximum length in bytes (yyy). Length must be 8, 16, or 24.

Also applies to the source key.
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 that uses this rule. If the variant is longer than the key, truncate it on the right to the length of the key before 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. Exclusive-OR this variant into the cleartext value of the output.
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 non-zero length is less than the length of the key that is 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:
    1. Ignore all CV bit definitions.
    2. If CCA DES key-token format, set the flag byte of the symmetric encrypted output key to indicate that a CV value is present.
    3. If the source key is 8 bytes, do not replicate the key to 16 bytes.
012+xxx yyy CV.

Place this CV into the output exported key-token, if 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, exclusive-OR this CV into the cleartext transport key.
  • Exclusive-OR 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 that is identified by the source_key_identifier parameter whenever all of these conditions are met:
    1. The Replicate Key command (offset X'00DB') is enabled in the active role.
    2. The CV length (offset 011+xxx) is 16, and both CV halves are non-zero.
    3. The source_key_identifier parameter (contained in either a CCA DES key-token or RKX key-token) identifies an 8-byte key.
    4. The key-form bits (40 - 42) of this CV do not indicate a single-length key (are not set to zero)
    5. Key-form bit 40 of this CV does not indicate that the key is to have guaranteed unique halves (is not set to 1).
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 that is 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 the following table:
Table 8. 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-justified 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 the following table:
Table 9. 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 (10+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 non-zero, 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).

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).

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:

  1. If the length of the key to be exported is less than yyy, return an error.
  2. Logical AND the CV for the key to be exported with the export key CV limit mask.
  3. Compare the result to the export key CV limit template.
  4. 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 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.
  • 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 that are permitted are #, $, @, and * (X'23', X'24', X'40', and X'2A').
  • The wildcard X'2A' (*) is only permitted 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.

Trusted block section X'13'

Trusted block section X'13' contains the name (key label). The trusted block name section provides a 64-byte variable to identify the trusted block, just as key labels are used to identify other CCA keys. This name, or label, enables a host access-control system such as RACF to use the name to verify that the application has authority to use the trusted block.

Section X'13' is optional. No multiple sections are allowed. It has no subsections that are defined. This section is defined in the following table:

Table 10. Trusted block key label (name) section X'13'
Offset (bytes) Length (bytes) Description
000 001 Section identifier:
X'13'
Trusted block name (key label).
001 001 Section version number (X'00').
002 002 Section length in bytes (68).
004 064 Name (key label).
Note: See Number representation in trusted blocks.

Trusted block section X'14'

Trusted block section X'14' contains control and security information that is related to the trusted block. This information section is separate from the public key and other sections because this section is required while the others are optional. This section contains the cryptographic information that guarantees its integrity and binds it to the local system.

Section X'14' is required. No multiple sections are allowed. Two subsections are defined. This section is defined in the following table:

Table 11. Trusted block information section X'14'
Offset (bytes) Length (bytes) Description
000 001 Section identifier:
X'14'
Trusted block information.
001 001 Section version number (X'00').
002 002 Section length in bytes (10+xxx).
004 002 Reserved, binary zero.
006 004 Flags:
X'00000000'
Trusted block is in the inactive state.
X'00000001'
Trusted block is in the active state.
010 xxx Information section subsections (tag-length-value objects).

One or two objects in TLV format.
Note: See Number representation in trusted blocks.
Section X'14' has two information subsections (tag-length-value objects) defined. These subsections are summarized in the following table:
Table 12. Summary of trusted block information subsections
Rule subsection tag TLV object Optional or required Comments
X'0001' Protection information Required Contains the encrypted 8-byte confounder and triple-length (24-byte) MAC key, the ISO 16609 TDES CBC MAC value, and the MKVP of the PKA master key (computed by using MDC4).
X'0002' Activation and expiration dates Optional Contains flags indicating whether the coprocessor is to validate dates, and contains the activation and expiration dates that are considered valid for the trusted block.
Note: See Number representation in trusted blocks.
Trusted block section X'14' subsection X'0001'

Subsection X'0001' of the trusted block information section (X'14') is the protection information TLV object. This subsection is required. It contains the encrypted 8-byte confounder and triple-length (24-byte) MAC key, the ISO-16609 TDES CBC MAC value, and the MKVP of the PKA master key (computed by using MDC4).

This subsection is defined in the following table:
Table 13. Protection information subsection (X'0001') of trusted block information section (X'14')
Offset (bytes) Length (bytes) Description
000 002 Subsection tag:
X'0001'
Trusted block information TLV object.
002 002 Subsection length in bytes (62).
004 001 Subsection version number (X'00').
005 001 Reserved, must be binary zero.
006 032 Encrypted MAC key.

Contains the encrypted 8-byte confounder and triple-length (24-byte) MAC key in the following format:

Offset
Description
00 - 07
Confounder.
08 - 15
Left key.
16 - 23
Middle key.
24 - 31
Right key.
038 008 MAC.

Contains the ISO-16609 TDES CBC message authentication code value.
046 016 MKVP.

Contains the PKA master key verification pattern, computed by using MDC4, when the trusted block is in internal form, otherwise contains binary zero.
Note: See Number representation in trusted blocks.
Trusted block section X'14' subsection X'0002'

Subsection X'0002' of the trusted block information section (X'14') is the activation and expiration dates TLV object. This subsection is optional. It contains flags indicating whether the coprocessor is to validate dates, and contains the activation and expiration dates that are considered valid for the trusted block.

This subsection is defined in the following table:
Table 14. Activation and expiration dates subsection (X'0002') of trusted block information section (X'14')
Offset (bytes) Length (bytes) Description
000 002 Subsection tag:
X'0002'
Activation and expiration dates TLV object.
002 002 Subsection length in bytes (16).
004 001 Subsection version number (X'00').
005 001 Reserved, must be binary zero.
006 002 Flags:
X'0000'
The coprocessor does not check dates.
X'0001'
The coprocessor checks dates.

Compare the activation date (offset 008) and the expiration date (offset 012) to the coprocessor's internal real-time clock. Return an error if the coprocessor date is before the activation date or after the expiration date.
008 004 Activation date.
Contains the first date that the trusted block can be used for generating or exporting keys. Format of the date is YYMD, where:
YY
Big-endian year (return an error if greater than 9999).
M
Month (return an error if any value other than X'01' - X'0C').
D
Day of month (return an error if any value other than X'01' - X'1F'; day must be valid for given month and year, including leap years).

Return an error if the activation date is after the expiration date or is not valid.
012 004 Expiration date.

Contains the last date that the trusted block can be used. Same format as activation date (offset 008). Return an error if date is not valid.
Note: See Number representation in trusted blocks.

Trusted block section X'15'

Trusted block section X'15' contains application-defined data. The trusted block application-defined data section can be used to include application-defined data in the trusted block. The purpose of the data in this section is defined by the application; it is not examined or used by CCA in any way.

Section X'15' is optional. No multiple sections are allowed. It has no subsections that are defined. This section is defined in the following table:

Table 15. Trusted block application-defined data section X'15'
Offset (bytes) Length (bytes) Description
000 001 Section identifier:
X'15'
Application-defined data.
001 001 Section version number (X'00').
002 002 Section length (6+xxx).
004 002 Application data length (xxx).

The value of xxx can be from 0 bytes to a length that does not cause the trusted block to exceed its maximum size of 3500 bytes.
006 xxx Application-defined data.

Can be used to hold a public-key certificate for the trusted public key.
Note: See Number representation in trusted blocks.