AESKW key format for external keys

Edit online

View the structure used to export an ECC or PQC private key when the ECC-AES1 or QSA-AES1 keyword is used with CSNDPKT. This key token is an external-only format and cannot be imported to CCA.

Table 1. AESKW key format structure

AESKW key format structure
Offset (decimal) Number of bytes Field
Start of Associated Data section
Sub-section: Header
0 1


Primary Identifier:
Value: X'53' (ASCII 'S')
1 1


Version:
Value:  X'00'  Version X‘00’ indicates AESKW wrapping method
2 2


SL = structLen
Value: dynamic, Length in bytes of the total structure (big endian).
Sub-section: Key data
4 1 Algorithm type (algorithm for which the key can be used):
Value
Meaning
X'81'
ECC key (private)
X'82'
PQC key : CRYSTALS-Dilithium - Round 2 (private)
X'83'
PQC key : CRYSTALS-Kyber - Round 2 (private)
X'84'
PQC key : CRYSTALS-Dilithium - Round 3 (private)
X'85'
PQC key : CRYSTALS-Kyber - Round 3 (private)
X'86'
PQC key : Pure ML-DSA (private)
X'87'
PQC key : ML-KEM (private)
X'88'
PQC key : Pre-hash ML-DSA (private)
5 2 Key type (general class of the key):

Values in this field depend on the input token and the value at offset '0x4': Algorithm type.

1. ECC private key source token:

Encoding:

  1. Upper nibble gives curve type.
  2. Lower three nibbles give length of private key ‘p’ in bits.

Values :

  1. X’0209’ ECC_PRIME_521

2. PQC private key token:

Encoding:

  1. Values correspond to the algorithm parameter field of the PQC token.

Values :

  1. X’0404’ CRYSTALS-Dilithium (4,4)
  2. X’0605’ CRYSTALS-Dilithium (6,5)
  3. X’0807’ CRYSTALS-Dilithium (8,7)
  4. X'1024' CRYSTALS-Kyber (1024)
  5. X'0768' CRYSTALS-Kyber (768)
7 1 kuf_count: Key usage fields count: 0 - 4. Key-usage field information defines restrictions on the use of the key.

QSA ML-DSA, CRYSTALS-Dilithium: kuf count = 2. QSA ML-KEM, CRYSTALS-Kyber: kuf count = 2.

Notes:
  1. Values in this field depend on the input token, the value at offset '0x4', key algorithm, and the value at offset '0x5', key type.
    • ECC private key source token: kuf_count=2
    • PQC key :ML-DSA, CRYSTALS-Dilithium: kuf_count=2
    • PQC key : ML-KEM, CRYSTALS-Kyber: kuf_count=2
  2. Each key-usage field is 2 bytes in length. The value in this field indicates how many 2-byte key usage fields follow.
  3. There are 8 bytes of Associated Data after this field. Each of these remaining 8 bytes of Associated Data is either 0x00 or a KUF byte, as indicated by this kuf_count field. This section is not variable size: unused bytes are 0x00 value.

Examples:

kuf_count = 1
two bytes of key usage information follow, this is one kuf field. The remaining 6 bytes of Associated Data are 0x00 bytes
kuf_count = 2
four bytes of key usage information follow, this is two kuf fields. The remaining 4 bytes of Associated Data are 0x00 bytes
8 1 Bit value meanings:

Algorithm at offset 4; ECC (X’81’), QSA-CRYSTALS-Dilithium Round 2 (X'82'), CRYSTALS-Kyber Round 2 (X'83'), CRYSTALS-Dilithium Round 3 (X'84'), CRYSTALS-Kyber Round 3 (X'85'), ML-DSA (X'86'), pure ML-KEM (X'87'), pre-hash ML-DSA (X'88')

A
B'1xxx xxxx' digitalSignature
B
B'x1xx xxxx' nonrepudiation or contentCommitment
C
B'xx1x xxxx' keyEncipherment
D
B'xxx1 xxxx' dataEncipherment
E
B'xxxx 1xxx' keyAgreement
F
B'xxxx x1xx' keyCertSign
G
B'xxxx xx1x' cRLSign
H
B'xxxx xxx1' encipherOnly (requires keyAgreement)
9 1 Bit value meanings:

Algorithm at offset 4; ECC (X’81’), QSA-CRYSTALS-Dilithium Round 2 (X'82'), CRYSTALS-Kyber Round 2 (X'83'), CRYSTALS-Dilithium Round 3 (X'84'), CRYSTALS-Kyber Round 3 (X'85'), ML-DSA (X'86'), pure ML-KEM (X'87'), pre-hash ML-DSA (X'88')

A
B'1xxx xxxx' decipherOnly - Requires keyAgreement bit at offset 8.

Cannot be combined with encipherOnly

B
B’x111 1111’ reserved
10 1 This field is reserved and must be X'00' byte.
11 1 This field is reserved and must be X'00' byte.
12 1 This field is reserved and must be X'00' byte.
13 1 This field is reserved and must be X'00' byte.
14 1 This field is reserved and must be X'00' byte.
15 1 This field is reserved and must be X'00' byte.
End of Associated Data section
Start of AESKW wrapped payload
16 6


Integrity Constant : byte array
Value:          X'A6A6A6A6A6A6'
22 1


PbL: Zero Padding bit length, this padding is AFTER the key, at the end of the payload
Value:          dynamic, depends on KL and ADLen, see examples below
23 1


ADLen: Associated Data byte length, in hex
Value:          X’10’
24 16 Copy of Associated Data.

The Associated Data is copied here after decryption. It must exactly match clear data as shown in the above Associated Data section of the AESKW key format structure.
40 KL Keydata.
Note: The size of the private key p across all components is determined by the key algorithm at offset 0x04 and the type field at offset 0x05.

Format of keydata

  • Algorithm: ECC (X’81’)

    A   The maximum size key, P521, will have KL=66 bytes.
  • Algorithm: QSA CRYSTALS-Dilithium Round 2 (X’82’), Type (X'0605') 
    
A   32 B for component 1: key D
B   48 B for component 2: tr T  
C   480 B for component 3: vector 's1'
D   576 B component 4: vector 's2'
E   2688 B component 5: 't0'
  • Algorithm: QSA CRYSTALS-Dilithium Round 2 (X'82'), Type (X'0807') 
    
A   32 B for component 1: key D 
B   48 B for component 2: tr T 
C   672 B for component 3: vector 's1'  
D   768 B component 4: vector 's2'  
E   3584 B component 5: 't0'
  • Algorithm: QSA CRYSTALS-Kyber Round 2 (X'83'), Type (X'0768') 
    
A   1152 B for component 1: secret polynomial vector 
B   32 B for component 2: public key integrity check 
C   32 B for component 3: random data
  • Algorithm: QSA CRYSTALS-Kyber Round 2 (X'83'), Type (X'1024') 
    
A   1536 B for component 1: secret polynomial vector 
B   32 B for component 2: public key integrity check 
C   32 B for component 3: random data
  • Algorithm: QSA CRYSTALS-Dilithium Round 3 (X'84'), Type (X'0605') 
    
A   32 B for component 1: key D 
B   32 B for component 2: tr T 
C   640 B for component 3: vector 's1'  
D   768 B component 4: vector 's2'   
E   2496 B component 5: 't0'
  • Algorithm: QSA CRYSTALS-Dilithium Round 3 (X'84'), Type (X'0807') 
    
A   32 B for component 1: key D  
B   32 B for component 2: tr T 
C   672 B for component 3: vector 's1' 
D   768 B component 4: vector 's2' 
E   3328 B component 5: 't0'
40 (cont'd) KL (cont'd)
  • Algorithm: QSA CRYSTALS-Kyber Round 3 (X'85'), Type (X'0768')
    
A   1152 B for component 1: secret polynomial vector 
B   32 B for component 2: public key integrity check 
C   32 B for component 3: random data
  • Algorithm: QSA CRYSTALS-Kyber Round 3 (X'85'), Type (X'1024')
    
A   1536 B for component 1: secret polynomial vector 
B   32 B for component 2: public key integrity check 
C   32 B for component 3: random data
  • Algorithm: QSA, pure and pre-hash ML-DSA (X'86'/X'88'), Type (X'0404') 
    
A   32 B for component 1: key D  
B   64 B for component 2: tr T 
C   384 B for component 3: vector 's1' 
D   384 B component 4: vector 's2' 
E   1664 B component 5: 't0'
  • Algorithm: QSA, pure and pre-hash ML-DSA (X'86'/X'88'), Type (X'0605') 
    
A   32 B for component 1: key D  
B   64 B for component 2: tr T 
C   640 B for component 3: vector 's1' 
D   768 B component 4: vector 's2' 
E   2496 B component 5: 't0'
  • Algorithm: QSA, pure and pre-hash ML-DSA (X'86'/X'88'), Type (X'0807') 
    
A   32 B for component 1: key D  
B   64 B for component 2: tr T 
C   672 B for component 3: vector 's1' 
D   768 B component 4: vector 's2' 
E   3328 B component 5: 't0'
  • Algorithm: QSA, ML-KEM (X'87'), Type (X'0768') 
    
A   1152 B for component 1: secret polynomial vector 
B   32 B for component 2: public key integrity check
C   32 B for component 3: random data
  • Algorithm: QSA, ML-KEM (X'87'), Type (X'1024') 
    
A   1536 B for component 1: secret polynomial vector 
B   32 B for component 2: public key integrity check
C   32 B for component 3: random data
KL+40 PbL / 8 Padding data: PbL count of 0b0 bits.
End of AESKW wrapped payload
KL+40+(PbL/8) Final size (FS) = structLen


Size of Keydata = KL = structLen – ((2 * 16) + 8 + (PbL / 8))
PbL (bits) = 64 – ((ADLen*8 + KL*8)mod64) = 64-((16*8 +KL*8)mod64) = 0 when (KL)mod8=0
FS = KL+40+(PbL/8)

ECC: Actual KL values, Pbl values:

521 bit P521 : KL = 66 Bytes; PbL = 48 bits; FS = 112 bytes. This is the maximum for the largest exportable ECC key size.

QSA CRYSTALS-Dilithium Round 2 (X’82’), Type (X'0605')

KL = 3824; PbL = 0; FS = 3864 Bytes

QSA CRYSTALS-Dilithium Round 2 (X'82'), Type (X'0807')

KL = 5104; PbL = 0; FS = 5144 Bytes

QSA CRYSTALS-Kyber Round 2 (X'83'), Type (X'0768')

KL = 1216; PbL = 0; FS = 1256 Bytes

QSA CRYSTALS-Kyber Round 2 (X'83'), Type (X'1024')

KL = 1600; PbL = 0; FS = 1640 Bytes

QSA CRYSTALS-Dilithium Round 3 (X'84'), Type (X'0605')

KL = 3968; PbL = 0; FS = 4008 Bytes

QSA CRYSTALS-Dilithium Round 3 (X'84'), Type (X'0807')

KL = 4832; PbL = 0; FS = 4872 Bytes

QSA CRYSTALS-Kyber Round 3 (X'85'), Type (X'0768')

KL = 1216; PbL = 0; FS = 1265 Bytes

QSA CRYSTALS-Kyber Round 3 (X'85'), Type (X'1024')

KL = 1600; PbL = 0; FS = 1640 Bytes

QSA pure and pre-hash ML-DSA (X'86'/X'88'), Type (X'0404')

KL = 2528; PbL = 0; FS = 2568 Bytes

QSA pure and pre-hash ML-DSA (X'86'/X'88'), Type (X'0605')

KL = 4000; PbL = 0; FS = 4040 Bytes

QSA pure and pre-hash ML-DSA (X'86'/X'88'), Type (X'0807')

KL = 4864; PbL = 0; FS = 4904 Bytes

QSA ML-KEM (X'87'), Type (X'0768')

KL = 1216; PbL = 0; FS = 1256 Bytes

QSA ML-KEM (X'87'), Type (X'1024')

KL = 1600; PbL = 0; FS = 1640 Bytes