Offset (bytes) | Length (bytes) | Description |
---|---|---|
000 | 001 | Token identifier (a flag that indicates token
type)
|
001 | 001 | Token version number (X'00'). |
002 | 002 | Length of the key-token structure in bytes. |
004 | 004 | Reserved, binary zero. |
Following the header, in no particular order, are trusted block sections. There are five different sections defined, each identified by a one-byte section identifier (X'11' - X'15'). Two of the five sections have subsections defined. A subsection is a tag-length-value (TLV) object, identified by a two-byte subsection tag.
Only sections X'12' and X'14' have subsections 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 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' 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 defined.
This section is defined in the following table:
Offset (bytes) | Length (bytes) | Description |
---|---|---|
000 | 001 | Section identifier:
|
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 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 |
012 |
004 | Flags:
|
Trusted block section X'12' contains information that defines a rule. A trusted block may have zero or more rule sections.
Five subsections (TLV objects) are defined.
This section is defined in the following table:
Offset (bytes) | Length (bytes) | Description |
---|---|---|
Offset (bytes) | Length (bytes) | Description |
000 | 001 | Section identifier:
|
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).
|
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):
|
018 | 001 | Symmetric encrypted output key format flag (all
other values are reserved and must not be used). Return the indicated symmetric key-token using the sym_encrypted_key_identifier parameter.
|
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.
|
020 | yyy | Rule section subsections (tag-length-value objects). A series of 0 - 5 objects in TLV format. |
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 which 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. |
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:
Offset (bytes) | Length (bytes) | Description |
---|---|---|
000 | 002 | Subsection tag:
|
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. 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.
|
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.
Offset (bytes) | Length (bytes) | Description |
---|---|---|
000 | 002 | Subsection tag:
|
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 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 exclusive-ORed with the cleartext transport key.
This subsection is defined in the following table:
Offset (bytes) | Length (bytes) | Description |
---|---|---|
000 | 002 | Subsection tag:
|
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 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. Exclusive-OR this variant into the cleartext value of the output. |
011+xxx | 001 | CV length in bytes (yyy).
|
012+xxx | yyy | CV. 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.
Note: A transport key is not used when the symmetric encrypted
output key is in RKX key-token format.
|
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.
Offset (bytes) | Length (bytes) | Description |
---|---|---|
000 | 002 | Subsection tag:
|
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. |
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:
Offset (bytes) | Length (bytes) | Description |
---|---|---|
000 | 002 | Subsection tag:
|
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:
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:
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+ |
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+ |
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:
|
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 defined. This section is defined in the following table:
Offset (bytes) | Length (bytes) | Description |
---|---|---|
000 | 001 | Section identifier:
|
001 | 001 | Section version number (X'00'). |
002 | 002 | Section length in bytes (68). |
004 | 064 | Name (key label). |
Trusted block section X'14' contains control and security information 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:
Offset (bytes) | Length (bytes) | Description |
---|---|---|
000 | 001 | Section identifier:
|
001 | 001 | Section version number (X'00'). |
002 | 002 | Section length in bytes (10+xxx). |
004 | 002 | Reserved, binary zero. |
006 | 004 | Flags:
|
010 | xxx | Information section subsections (tag-length-value
objects). One or two objects in TLV format. |
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 using MDC4). |
X'0002' | Activation and expiration dates | Optional | Contains flags indicating whether or not the coprocessor is to validate dates, and contains the activation and expiration dates that are considered valid for the trusted block. |
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 using MDC4).
Offset (bytes) | Length (bytes) | Description |
---|---|---|
000 | 002 | Subsection tag:
|
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:
|
038 | 008 | MAC. Contains the ISO-16609 TDES CBC message authentication code value. |
046 | 016 | MKVP. Contains the PKA master key verification pattern, computed using MDC4, when the trusted block is in internal form, otherwise contains binary zero. |
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 or not the coprocessor is to validate dates, and contains the activation and expiration dates that are considered valid for the trusted block.
Offset (bytes) | Length (bytes) | Description |
---|---|---|
000 | 002 | Subsection tag:
|
002 | 002 | Subsection length in bytes (16). |
004 | 001 | Subsection version number (X'00'). |
005 | 001 | Reserved, must be binary zero. |
006 | 002 | Flags:
|
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:
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. |
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 neither examined nor used by CCA in any way.
Section X'15' is optional. No multiple sections are allowed. It has no subsections defined. This section is defined in the following table:
Offset (bytes) | Length (bytes) | Description |
---|---|---|
000 | 001 | Section identifier:
|
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 May be used to hold a public-key certificate for the trusted public key. |