ECC key token

The format of ECC public and private key tokens.

Table 5 and Table 7 show the format of ECC public and private key tokens.

CCA allows a choice between three types of elliptic curves when generating an ECC key: Brainpool, Prime, and Edwards elliptic curves. Table 1 and Table 2 show the size and name of each supported elliptic curve, along with its object identifier (OID) in dot notation.

Table 1. Supported Brainpool elliptic curves
Supported Brainpool elliptic curves by size, name, and object identifier
Size of prime p in bits (key length)	OID in dot notation	Brainpool elliptic curve ID
160	1.3.36.3.3.2.8.1.1.1	brainpoolP160r1
192	1.3.36.3.3.2.8.1.1.3	brainpoolP192r1
224	1.3.36.3.3.2.8.1.1.5	brainpoolP224r1
256	1.3.36.3.3.2.8.1.1.7	brainpoolP256r1
320	1.3.36.3.3.2.8.1.1.9	brainpoolP320r1
384	1.3.36.3.3.2.8.1.1.11	brainpoolP384r1
512	1.3.36.3.3.2.8.1.1.13	brainpoolP512r1

Table 2. Supported Prime elliptic curves
Supported Prime elliptic curves by size, name, and object identifier
Size of prime p in bits (key length)	OID in dot notation	ANSI X9.62 ECDSA prime curve ID	NIST-recommended elliptic curve ID	SEC 2 recommended elliptic curve domain parameter
192	1.2.840.10045.3.1.1	prime192v1	P-192	secp192r1
224	1.3.132.0.33	N/A	P-224	secp224r1
256	1.2.840.10045.3.1.7	prime256v1	P-256	secp256r1
384	1.3.132.0.34	N/A	P-384	secp384r1
521	1.3.132.0.35	N/A	P-521	secp521r1

Table 3. Supported Edwards elliptic curves
Supported Edwards elliptic curves by size, name, and object identifier
Size of prime p in bits (key length)	OID in dot notation	Edwards-coordinate signature system	Elliptic curve
255	1.3.101.112	id-Ed25519	Curve25519
448	1.3.101.113	id-Ed448	Curve448

Table 4. Supported Koblitz elliptic curves
Supported Koblitz elliptic curves by size, name, and object identifier
Size of prime p in bits (key length)	OID in dot notation	ANS X9.62 curve name	Elliptic curve
256	1.3.132.0.10	Koblitz curve over 256-bit Prime field	secp256k1

Table 5. ECC private key section (X'20')
ECC private-key section (X'20')
Offset (bytes)	Length (bytes)	Description
000	001	Section identifier: X'20' ECC private key (ECC-PAIR)
001	001	Section version number: Value Meaning X'00' Legacy section version, no pedigree field, no IBM Extended Associated Data (IEAD), no support for ECC key-derivation information section (X'23'). Note: Use of this section version is provided for backward compatibility. Version 1 has additional security features and should be used instead. X'01' Latest section version. Includes pedigree field, IEAD, SHA-256 hash of all optional sections to IEAD, supports ECC key-derivation information section (X'23').
002	002	Length of section in bytes: 76 + asd + bb.
004	001	Wrapping method: X'00' Section is unencrypted (clear) X'01' AESKW (ANS X9.102)
005	001	Algorithm used to hash associated data section: X'00' None (no key present or key is clear key) X'01' SHA-224 X'02' SHA-256 Note: The message digest is calculated on the associated data section, offset 76 to offset 92 `+ kl + lead + uad`. The message digest becomes part of the payload prior to its encryption.
006	002	Reserved, binary zero.
008	001	Key-usage and translation control flag. Management of symmetric keys and generation of digital signatures: B'11xx xxxx' Only key establishment (KM-ONLY) B'10xx xxxx' Both signature generation and key establishment (KEY-MGMT) B'01xx xxxx' Undefined B'00xx xxxx' Only signature generation (SIG-ONLY) Note: secp256k1 curves are usable for ECDSA (signature) or ECDH (key agreement/key management). Translation control: B'xxxx xx1x' Private key translation is allowed (XLATE-OK). B'xxxx xx0x' Private key translation is not allowed (NO-XLATE). B'xxxx x1xx' Private key export under AES key is allowed (AES1ECOK). B'xxxx x0xx' Private key export under AES key is not allowed (NOAES1EC). Note: secp256k1 curves are NOT exportable to CPACF. Key management: B'B'xxxx xxx1' Private key CPACF-export is allowed (XPRTCPAC). B'xxxx xxx0' Private key CPACF-export is not allowed (NOEXCPAC). All other bits are reserved and must be zero.
009	001	Curve type: X'00' Prime curve X'01' Brainpool curve X'02' Edwards curve X'03' Koblitz curve
010	001	Key format and security flag: X'08' Encrypted internal ECC private key X'40' Unencrypted external ECC private key X'42' Encrypted external ECC private key
011	001	Section version X'00' (see offset 001): Reserved, binary zero Section version X'01' (see offset 001): Pedigree/Key source flag byte External key-token: Value Meaning X'00' None/Clear X'24' Randomly generated Internal key-token: Value Meaning X'00' None/Clear X'21' Imported from cleartext X'22' Imported from ciphertext X'24' Randomly generated
012	002	Length of prime p in bits. See Table 2 and Table 1. X'00A0' 160 (Brainpool) X'00C0' 192 (Brainpool, Prime) X'00E0' 224 (Brainpool, Prime) X'00FF' Edwards 25519 X'0100' 256 (Brainpool, Prime, Koblitz) X'0140' 320 (Brainpool) X'0180' 384 (Brainpool, Prime) X'01C0' Edwards 448 X'0200' 512 (Brainpool) X'0209' 521 (Prime)
014	002	Length in bytes of IBM® associated data, 0 or iadl = 16 + pknl + ieadl.
016	008	Key verification pattern. External key-token For an encrypted private key, KEK verification pattern (KVP) For a clear private key, binary zeros For a skeleton, binary zeros Internal key-token For encrypted private key, master-key verification pattern (MKVP) For a skeleton, binary zeros
024	048	Object Protection Key (OPK). External key-token: Reserved, binary zero. Internal key token: OPK data consists of an 8-byte integrity check value (ICV) and length indicators, an 8-byte confounder, and a 256-bit AES key used with the AESKW algorithm to encrypt the ECC private key contained in an AESKW formatted section. Note: The OPK is encrypted by the APKA master key using AESKW (ANS X9.102). The OPK has no associated data.
072	002	Length in bytes of associated data, 0 or asdl = iadl + uadl.
074	002	Length in bytes of formatted section, or bb.
Associated data section
Start of IBM associated data
076	001	Associated data section version number. Includes IBM associated data and user-definable associated data. Value Meaning X'00' Legacy associated data section version. Only defined for section version number X'00' (see offset 001). X'01' Latest associated data section version. Only defined for section version number X'01' (see offset 001).
077	001	Length in bytes of the key label: kl (0 - 64).
078	002	Length in bytes of the IBM associated data (AD), including key label and IBM extended associated data. AD data section version number (see offset 076) Length of AD X'00' ≥ 16 X'01' ≥ 52
080	002	Length in bytes of the IBM extended associated data: iead. AD data section version number (see offset 076) Length of AD X'00' iead = 0 X'01' iead = 36
082	001	Length in bytes of the user-definable associated data: uad (0 - 100).
083	001	Curve type (see offset 009).
084	002	Length of p in bits (see offset 012).
086	001	Key-usage flag (see offset 008).
087	001	Key format and security flag (see offset 010).
088	001	AD section version number X'00' (see offset 001): Reserved, binary zero AD section version number X'01' (see offset 001): Pedigree/Key source flag byte (see offset 011)
089	003	Reserved, binary zero.
092	kl	Optional key label. Private key name (in ASCII), left-justified, padded with space characters (X'20').
092 + kl	iead	Optional IBM extended associated data. For AD section version number X'01' (see offset 076): Consists of a single section hash tag-length-value (TLV) object with TLV tag identifier X'60'. Refer to Table 6. Note: A section hash TLV object cannot be present in section version number X'00', and will always be present in section version number of X'01'. When present, it contains the SHA-256 hash digest of all the optional sections that follow the public key section, if any. Otherwise, it contains binary zeros.
End of IBM associated data
092 + kl + iead	uad	Optional user-definable associated data.
End of associated data section
092 + kl + iead + uad	bb	Formatted section (payload), which includes private key d: Clear-key section contains d. Encrypted-key section contains d within the AESKW-wrapped payload.

Table 6. ECC section hash TLV object (X'60') of Version 1
ECC section hash TLV object (X'60') of Version 1 ECC private-key section (X'20')
Offset (bytes)	Length (bytes)	Description
000	001	Tag identifier: X'60' ECC section hash TLV object
001	001	TLV object version number (X'00').
002	002	TLV object length in bytes (X'0024').
004	032	SHA-256 hash of all the optional sections that follow the public-key section, if any. Otherwise binary zeros. Note: A section hash TLV object will always be present in a PKA key token that has an ECC private key section (X'20') with a section version number of X'01'.

Table 7. ECC public key section (X'21')
ECC public key section (X'21')
Offset (bytes)	Length (bytes)	Description
000	001	Section identifier: X'21' ECC public key (ECC-PUBL)
001	001	Section version number (X'00').
002	002	Section length in bytes.
004	004	Reserved, binary zero.
008	001	Curve type: X'00' Prime curve X'01' Brainpool curve X'02' Edwards curve X'03' Koblitz curve
009	001	Reserved, binary zero
010	002	Length of prime p in bits. See Table 2 and Table 1. X'00A0' 160 (Brainpool) X'00C0' 192 (Brainpool, Prime) X'00E0' 224 (Brainpool, Prime) X'00FF' Edwards 25519 X'0100' 256 (Brainpool, Prime, Koblitz) X'0140' 320 (Brainpool) X'0180' 384 (Brainpool, Prime) X'01C0' Edwards 448 X'0200' 512 (Brainpool) X'0209' 521 (Prime)
012	002	Length of public key q in bytes. Value includes key material length plus a one-byte flag to indicate if the key material is compressed. For Prime and Brainpool curves, the value includes the key material length plus a one byte flag to indicate if the key material is compressed or uncompressed. For Edwards curves, the value is in little endian format.
014	cc	Public key q.

Table 8. ECC key-derivation information section (X'23')
ECC key-derivation information section (X'23')
Offset (bytes)	Length (bytes)	Description
000	001	Section identifier: X'23' ECC key-derivation information
001	001	Section version number (X'00')
002	002	Section length in bytes (8)
004	001	Algorithm of key to be derived: Value Algorithm X'01' DES X'02' AES
005	001	Type of CCA key to be derived: Value Meaning X'01' DATA X'02' EXPORTER X'03' IMPORTER X'04' CIPHER X'05' DECIPHER X'06' ENCIPHER X'07' CIPHERXI X'08' CIPHERXL X'09' CIPHERXO	Type of TR-31 key to be derived: Value Meaning X'02' EXPORTER TR-31 key usage: K0 or K1 Algorithm: A, D, or T TR-31 mode of key use: E X'03' IMPORTER TR-31 key usage: K0 or K1 Algorithm: A, D, or T TR-31 mode of key use: D X'04' CIPHER TR-31 key usage: D0 Algorithm: A TR-31 mode of key use: B, D, or E or TR-31 key usage: D0 Algorithm: D or T TR-31 mode of key use: B X'05' DECIPHER TR-31 key usage: D0 Algorithm: D or T TR-31 mode of key use: D X'06' ENCIPHER TR-31 key usage: D0 Algorithm: D or T TR-31 mode of key use: E
006	002	Key-bit length: Value Meaning X'0040' (64) DES X'000' (128) AES, DES X'00C0' (192) AES X'0100' (256) AES Note: Bit length of DES keys includes parity bits.