AESKW key format for external keys

Edit online

View the structure used to export an ECC or QSA 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
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'
QSA key : CRYSTALS-Dilithium - Round 2 (private)
X'83'
QSA key : CRYSTALS-Kyber - Round 2 (private)
X'84'
QSA key : CRYSTALS-Dilithium - Round 3 (private)
X'85'
QSA key : CRYSTALS-Kyber - Round 3 (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. QSA private key token:

Encoding:

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

Values :

  1. X’0605’ CRYSTALS-Dilithium (6,5)
  2. X’0807’ CRYSTALS-Dilithium (8,7)
  3. X'1024' CRYSTALS-Kyber (1024)
  4. 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.
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.
    A.
    ECC private key source token: kuf_count=2
    B.
    QSA key : CRYSTALS-Dilithium: kuf_count=2
    C.
    QSA key : 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'), QSA-CRYSTALS-Kyber Round 2 (X'83'), QSA-CRYSTALS-Dilithium Round 3 (X'84')

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'), QSA-CRYSTALS-Kyber Round 2 (X'83'), QSA-CRYSTALS-Dilithium Round 3 (X'84')

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 (con't) KL
  • 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'86'), 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 (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