Parameters

Edit online

The parameters for CSNDPKB.

For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see Parameters common to all verbs.

rule_array_count
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of elements in the rule_array variable. This value must be in the range 1 - 5.
rule_array
Direction: Input
Type: String array
A pointer to a string variable containing an array of keywords for the verb. The keywords must be in contiguous storage with each of the keywords left-aligned in its own 8-byte location and padded on the right with blanks. The rule_array keywords are described in Table 1.
Table 1. Keywords for PKA Key Token Build control information

Keywords for PKA Key Token Build control information
Keyword Description
Token type (One, required)
ECC-PAIR This keyword indicates building a token containing both public and private ECC key information. The parameter key_value_structure identifies the input key values, if supplied.
ECC-PUBL This keyword indicates building a token containing public ECC key information. The parameter key_value_structure identifies the input values, if supplied.
QSA-PAIR This keyword indicates building a token containing both public and private QSA key information. The parameter key_value_structure identifies the input values. This includes CRYSTALS-Dilithium, CRYSTALS-Kyber, ML-DSA or ML-KEM key pairs.
QSA-PUBL This keyword indicates building a token containing public QSA key information. The parameter key_value_structure identifies the input values. This includes CRYSTALS-Dilithium, CRYSTALS-Kyber, ML-DSA or ML-KEM key pairs.
RSA-AESC Create a key token for an RSA public key and an RSA private key in Chinese-Remainder Theorem (CRT) format with an AES-encrypted OPK.

Specify a format restriction keyword to restrict the private key to a particular digital-signature hash formatting method, or none (the default, see Format restriction section later in this table).

RSA-AESM Create a key token for an RSA public key and an RSA private key in Modulus-Exponent format with an AES-encrypted OPK.

Specify a format restriction keyword to restrict the private key to a particular digital-signature hash formatting method, or none (the default, see Format restriction section later in this table).

RSA-CRT This keyword indicates building a token containing an RSA private key in the optimized Chinese Remainder Theorem (CRT) format. The parameter key_value_structure identifies the input key values, if supplied.
RSA-PRIV This keyword indicates building a token containing both public and private RSA key information. The parameter key_value_structure identifies the input key values, if supplied.
RSA-PUBL This keyword indicates building a token containing public RSA key information. The parameter key_value_structure identifies the input values, if supplied.
RSAAESC2 This keyword is for creating a key token for an RSA public and private key in Chinese-Remainder Theorem format with a version X'05' private key associated data section. The object protection key is an AES key. Either RSAAESC2 or RSAAESM2 is required when using the COMP-TAG or the PKA Key Usage Control group.
RSAAESM2 This keyword is for creating a key token for an RSA public and private key in modulus-exponent format with a version X'04' private key associated data section. The object protection key is an AES key. Either RSAAESC2 or RSAAESM2 is required when using the COMP-TAG or the PKA Key Usage Control group.
RSAMEVAR This keyword is for creating a key token for an RSA public and private key pair in modulus-exponent form (RSA-Modulus Exponent-Variant[RSAMEVAR]) whose modulus is 512 bits or greater.
Note: Key tokens created with this key type cannot be passed to the PKA Key Generate verb for creating RETAIN (retained) keys.
Compliance (Optional)
COMP-TAG Build a compliant-tagged key token. Only valid with RSAAESC2 or RSAAESM2.
NOCMPTAG Do not build a compliant-tagged key token. This is the default.
RSA key usage control (One, optional). Not valid with type ECC-PUBL, RSAAESC2, RSAAESM2, RSA-PUBL, QSA-PAIR, or QSA-PUBL.
KEY-MGMT Indicates that an RSA or ECC private key can be used in both the Symmetric Key Import and the Digital Signature Generate verbs.
Note: Key tokens created with this key usage cannot be passed to the PKA Key Generate verb for creating RETAIN (retained) (retained) keys.
KM-ONLY Indicates that an RSA or ECC private key can be used only in symmetric key distribution.
Note: Key tokens created with this key usage cannot be passed to the PKA Key Generate verb for creating RETAIN (retained) (retained) keys.
SIG-ONLY Indicates that an RSA or ECC private key cannot be used in symmetric key distribution. This is the default.

This keyword is required when building type ECC-PAIR token with an Edwards curve.

Note: Only a skeleton key-token created from PKA Key Token Build with this key usage type can be passed to PKA Key Generate to create a RETAIN (retained) (retained) key.
Translate control (One, optional). Not valid with token type ECC-PUBL, RSA-PUBL, or QSA-PUBL.
NO-XLATE The RSA or ECC key cannot be used as a key-encrypting-key for PKA Key Translate (CSNDPKT).
Note: Use of this keyword does not matter when creating a skeleton key-token for a later retained key generation operation. It is redundant to the necessary SIG-ONLY keyword.
XLATE-OK The RSA or ECC key can be used as a key-encrypting-key for PKA Key Translate (CSNDPKT).
Note: Key tokens created with this keyword cannot be passed to the PKA Key Generate verb for creating RETAIN (retained) keys.
Format restriction (One, optional). Only valid with token type keyword RSA-AESC, RSAAESC2, or RSAAESM2.
FR-NONE Specifies to not restrict the private key to be used by a particular digital-signature hash formatting method. The key is usable for any method. This is the default.
FR-I9796 Specifies to render the private key usable only with the digital-signature hash formatting method ISO-9796.
FR-X9.31 Specifies to render the private key usable only with the digital-signature hash formatting method X9.31.
FR-ZPAD Specifies to render the private key usable only with the digital-signature hash formatting method ZERO-PAD.
FR-PK10 Specifies to render the private key usable only with the digital-signature hash formatting method PKCS-1.0.
FR-PK11 Specifies to render the private key usable only with the digital-signature hash formatting method PKCS-1.1.
FR-PSS Specifies to render the private key usable only with the digital-signature hash formatting method PKCS-PSS.
ECC token version (One, optional). Release 5.2 or later. Only valid with token type ECC-PAIR.
ECC-VER0 Build an ECC private-key section (X'20') using the format section version number X'00'. This is the default.
Note: Use of this option is provided for backward compatibility and its use is discouraged. The preferred format is Version X'01'.
ECC-VER1 Build an ECC private-key section (X'20') using the format section version number X'01'. This keyword is required if key derivation data is provided.

Version X'01' key token enhancements include a pedigree field, a section hash tag-length-value (TLV) object (X'60') that gets included in the IBM extended associated data (IEAD) with a hash digest of all optional sections up to the IEAD. The Version 1 key token also supports the ECC key-derivation information section (X'23') that is required by the Elliptic Curve Diffie-Hellman verb to derive one element of any key pair using the ANSI-X963-KDF key derivation function.
CPACF export (One, optional). Valid with ECC-PAIR only. Not valid with ECC Koblitz curves.
NOEXCPAC Prohibit export to CPACF protected key format. This is the default.
XPRTCPAC Allow export to CPACF protected key format. Valid for ECC curves P256, P384, P521, Ed25519, and Ed448.
AES export (One, optional). Only valid with token type ECC-PAIR or QSA-PAIR.
AES1ECOK Enable export of the ECC, CRYSTALS-Dilithium, CRYSTALS-Kyber, ML-DSA or ML-KEM private key under an AES key encrypting key of similar strength or stronger. An ECC private key must have bit 5 in the single byte field at offset 9 of the ECC private key section set in the skeleton key token to allow this. A QSA private key must have bit 5 in the single byte field at offset 14 of the QSA private key section set in the skeleton key token to allow this. This keyword causes the indicated bit to be set in the output skeleton key token.
NOAES1EC Do not allow export of the ECC private key. This is the default.
PKA Key Usage Control (Required with RSAAESC2, RSAAESM2, QSA-PAIR, or QSA-PUBL. Not valid otherwise). For QSA-PAIR, or QSA-PUBL, refer to allowed usages for the key algorithm. CRYSTALS-Kyber or ML-KEM keys require the keywords U-KEYENC or U-DATAENC. CRYSTALS-Dilithium or ML-DSA keys require the keyword U-DIGSIG.
U-DIGSIG Digital Signature usage is allowed. When COMP-TAG is specified, cannot be combined with U-KEYENC, U-DATENC, or U-KEYAGR.
U-NONRPD Non-Repudiation usage is allowed. When COMP-TAG is specified, cannot be combined with U-KEYENC, U-DATENC, or U-KEYAGR.
U-KCRTSN keyCertSign usage is allowed. When COMP-TAG is specified, cannot be combined with U-KEYENC, U-DATENC, or U-KEYAGR.
U-CRLSN Certificate Revocation List Sign usage is allowed. When COMP-TAG is specified, cannot be combined with U-KEYENC, U-DATENC, or U-KEYAGR.
U-KEYENC Key Encipherment usage is allowed. When COMP-TAG is specified, cannot be combined with any other keyword from this group.
U-DATENC Data Encipherment usage is allowed. When COMP-TAG is specified, cannot be combined with any other keyword from this group.
U-KEYAGR Key agreement usage is allowed. When COMP-TAG is specified, cannot be combined with any other keyword from this group.
Key agreement control (One, Optional). Only valid with U-KEYAGR.
U-ENCONL

Only encipher operations are allowed during key agreement key establishment protocols.

When input key type is RSAAESC2 or RSAAESM2, the U-DECONL must not be enabled in the input key token.
U-DECONL

Only decipher operations are allowed during key agreement key establishment protocols.

When input key type is RSAAESC2 or RSAAESM2, the U-ENCONL must not be enabled in the input key token.

key_value_structure_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the key_value_structure variable. The length depends on the key type parameter in the rule_array and on the actual values input. The length is in bytes. For maximum values, see Table 2.
Table 2. PKA Key Token Build - Key value structure length maximum values

PKA Key Token Build - Key value structure length maximum values
Key type Key value structure maximum value
ECC-PAIR 207
ECC-PUBL 139
RSA-AESC, RSA-AESM, RSAAESC2, RSAAESM2 5000
RSA-CRT, RSAMEVAR 3500
RSA-PRIV 648
RSA-PUBL 1544
QSA-PAIR 7496
QSA-PUBL 2600
key_value_structure
Direction: Input
Type: String
This is a segment of contiguous storage containing a variable number of input clear key values and the lengths of these values in bits or bytes, as specified. The structure elements are ordered, of variable length, and the input key values must be right-aligned within their respective structure elements and padded on the left with binary zeros. If the leading bits of the modulus are zeros, do not count them in the length. Table 3 defines the structure and contents as a function of key type.
Table 3. PKA Key Token Build - Key value structure elements

PKA Key Token Build - Key value structure elements
Offset Length (bytes) Description
Key value structure (ECC-PAIR)
000 001 Curve type:
X'00'
Prime curve
X'01'
Brainpool curve
X'02'
Edwards curve
X'03'
Koblitz curve
001 001 Reserved X'00'
002 002 Length of p in bits
X'00A0'
Brainpool P-160
X'00C0'
Prime P-192, Brainpool P-192
X'00E0'
Prime P-224, Brainpool P-224
X'00FF'
255 (Edwards curve25519, id-Ed25519, OID = 1.3.101.112). See also Table 3.
X'0100'
Prime P-256, Brainpool P-256, Koblitz
X'0140'
Brainpool P-320
X'0180'
Prime P-384, Brainpool P-384
X'01C0'
448 (Edwards curve448, id-Ed448, OID = 1.3.101.113). See also Table 3.
X'0200'
Brainpool P-512
X'0209'
Prime P-521
004 002 ddd - this field is the length of the private key d in bytes. This value can be zero if the key token is used as a skeleton key-token in the PKA Key Generate verb. The maximum value is 66 bytes.
006 002 xxx - this field is the length of the public key Q in bytes. This value can be zero if the key token is used as a skeleton key-token in the PKA Key Generate verb. The maximum value is 133 bytes, which includes one byte to indicate if the value is compressed.
008 ddd Private key, d
008 + ddd xxx Public key, Q
Key value structure (ECC-PUBL)
000 001 Curve type:
X'00'
Prime curve
X'01'
Brainpool curve
X'02'
Edwards curve
X'03'
Koblitz curve
001 001 Reserved X'00'
002 002 Length of p in bits
X'00A0'
Brainpool p-160
X'00C0'
Prime P-192, Brainpool P-192
X'00E0'
Prime P-224, Brainpool P-224
X'00FF'
255 (Edwards curve25519, id-Ed25519, OID = 1.3.101.112). See also Table 3.
X'0100'
Prime P-256, Brainpool P-256, Koblitz
X'0140'
Brainpool P-320
X'0180'
Prime P-384, Brainpool P-384
X'01C0'
448 (Edwards curve448, id-Ed448, OID = 1.3.101.113). See also Table 3.
X'0200'
Brainpool P-512
X'0209'
Prime P-521
004 002 xxx - this field is the length of the public key Q in bytes. This value can be zero if the key token is used as a skeleton key-token in the PKA Key Generate verb. The maximum value is 133 bytes, which includes one byte to indicate if the value is compressed.
006 xxx Public key Q.
Key value structure (Optimized RSA, Chinese Remainder Theorem format, RSA-CRT)
000 002 Modulus length in bits (512 - 4096). This is required.
002 002 Modulus field length in bytes, nnn. This value can be zero if the key token is used as a skeleton key-token in the PKA Key Generate verb. This value must not exceed 512.
004 002 Public exponent field length in bytes, eee. This value can be zero if the key token is used as a skeleton key-token in the PKA Key Generate verb.
006 002 Reserved, binary zero.
008 002 Length of the prime number p, in bytes, ppp. This value can be zero if the key token is used as a skeleton key-token in the PKA Key Generate verb. Maximum size of p + q is 512 bytes.
010 002 Length of the prime number q, in bytes, qqq. This value can be zero if the key token is used as a skeleton key-token in the PKA Key Generate verb. Maximum size of p + q is 512 bytes.
012 002 Length of dp, in bytes, rrr. This value can be zero if the key token is used as a skeleton key-token in the PKA Key Generate verb. Maximum size of dp + dq is 512 bytes.
014 002 Length of dq, in bytes, sss. This value can be zero if the key token is used as a skeleton key-token in the PKA Key Generate verb. Maximum size of dp + dq is 512 bytes.
016 002 Length of U, in bytes, uuu. This value can be zero if the key token is used as a skeleton key token in the PKA Key Generate verb. Maximum size of U is 512 bytes.
018 nnn Modulus, n.
018 + nnn eee Public exponent, e. This is an integer such that 1 < e < n. e must be odd. When you are building a skeleton key-token to control the generation of an RSA key pair, the public key exponent can be one of the following values: 3, 65537 (216 + 1), or 0 to indicate that a full random exponent should be generated. The exponent field can be a null-length field if the exponent value is 0.
018 + nnn + eee ppp Prime number p.
018 + nnn + eee + ppp qqq Prime number q.
018 + nnn + eee + ppp + qqq rrr dp = d mod(p-1).
018 + nnn + eee + ppp + qqq + rrr sss dq = d mod(q-1).
018 + nnn + eee + ppp + qqq + rrr + sss uuu U = q-1mod(p).
Key value structure (RSA private, RSA private variable, or RSA public)
000 002 Modulus length in bits. This is required. When building a skeleton key-token, the modulus length in bits must be greater than or equal to 512 bits.
002 002 Modulus field length in bytes, XXX. This value can be zero if you are using the key token as a skeleton in the PKA Key Generate verb. This value must not exceed 512 when the RSA-PUBL keyword is used and must not exceed 128 when the RSA-PRIV keyword is used.

This verb can build a key token for a public RSA key with a 4096-bit modulus length or it can build a key token for a 1024-bit modulus length private key.
004 002 Public exponent field length in bytes, YYY. This value must not exceed 512 when the RSA-PUBL keyword is used and must not exceed 128 when the RSA-PRIV keyword is used. This value can be zero if you are using the key token as a skeleton key-token in the PKA Key Generate verb. In this case, a random exponent is generated. To obtain a fixed, predetermined public key exponent, you can supply this field and the public exponent as input to the PKA Key Generate verb.
006 002 Private exponent field length in bytes, ZZZ. This field can be zero, indicating that private key information is not provided. This value must not exceed 128 bytes. This value can be zero if you are using the key token as a skeleton in the PKA Key Generate verb.
008 XXX Modulus, n. This is an integer such that 1 < n < 24096. The n is the product of p and q for primes p and q.
008 + XXX YYY RSA public exponent, e. This is an integer such that 1 < e < n. e must be odd. When you are building a skeleton key token to control the generation of an RSA key pair, the public key exponent can be one of the following values: 3, 65537 (216 + 1), or 0 to indicate that a full random exponent should be generated. The exponent field can be a null-length field if the exponent value is 0.
008 + XXX + YYY ZZZ RSA secret exponent d. This is an integer such that 1 < d < n. The value of d is e-1 mod(p-1)(q-1). You need not specify this value if you specify RSA-PUBL in the rule_array parameter.
Key value structure RSA keys (RSA-PRIV, RSA-PUBL, RSAMEVAR, RSA-AESM, RSAAESM2)
000 002 Length of the modulus in bits
RSA-AESM and RSAAESM2 (section X'30')
512 - 8192
RSA-PRIV (section X'02')
512 - 1024
RSA-PUBL (section X'04')
512 - 8192
RSAMEVAR (section X'09')
512 - 4096
002 002 Modulus field length in bytes, nnn. This value must not exceed 512 when the RSA-PUBL, RSA-AESM, or RSAMEVAR keyword is used, and must not exceed 128 when the RSA-PRIV keyword is used.

This service can build a key token for a public RSA key with a 4096-bit modulus length, or it can build a key token for a 1024-bit modulus length private key.
004 002 Public exponent field length in bytes: eee.

This value must not exceed 512 when either the RSA-PUBL, RSAAESM, or RSAMEVAR keyword is used, and must not exceed 128 when the RSA-PRIV keyword is used.

This value can be zero if you are using the key token as a skeleton token in the PKA Key Generate verb. In this case, a random exponent is generated.

To obtain a fixed, predetermined public key exponent, you can supply this field and the public exponent as input to the PKA Key Generate verb.
006 002 Private exponent field length in bytes, ddd.

This value can be zero, indicating that private key information is not provided.

This value must not exceed 128 bytes. This value can be zero if you are using the key token as a skeleton token in the PKA Key Generate verb.
008 nnn Modulus n. This is an integer value, such that 1 < n < 28192. The n is the product of p and q for primes p and q.
8 + nnn eee Public exponent field e, integer value, 1 < e < n, e must be odd. When you are building a skeleton key token to control the generation of an RSA key pair, the public key exponent must be one of the following values: 0 (full-random), 3, or 65537. Beginning with Release 5.2, you can also specify a value of 5, 17, or 257. The exponent field can be a null-length field when preparing a skeleton key token.
8 + nnn + eee ddd RSA secret exponent d.

This is an integer value such that 1 < d < n.

The value of d is: d = e-1 mod(p-1)(q-1). The product of e and d is 1 mod(p-1)(q-1). This can be a null-length field if you are using the key token as a skeleton token in the PKA Key Generate verb.
RSA key-values structure, Chinese-Remainder Theorem format (RSA-AESC, RSAAESC2, or RSA-CRT)
000 002 Length of the modulus in bits:
RSA-AESC and RSAAESC2 (section X'31')
512 - 8192
RSA-CRT (section X'30')
512 - 4096
002 002 Length of the modulus field n, in bytes: nnn. This value must not exceed 4096/8 = 512.

This value should be zero when preparing a skeleton key token for use with the PKA Key Generate verb.
004 002 Length of the public exponent field e, in bytes: eee.

This value should be zero when preparing a skeleton key-token to generate a random-exponent public key in the PKA Key Generate verb. This value must not exceed 512.
006 002 Reserved, binary zero.
008 002 Length of the prime number field p, in bytes: ppp. Should be zero in a skeleton key-token. The maximum value of ppp+qqq is 512 bytes.
010 002 Length of the prime number field q, in bytes: qqq. Should be zero in a skeleton key-token. The maximum value of ppp+qqq is 512 bytes.
012 002 Length of the dp field, in bytes: rrr. Should be zero in a skeleton key-token. The maximum value of rrr + sss is 512 bytes.
014 002 Length of the dq field, in bytes: sss. Should be zero in a skeleton key-token. The maximum value of rrr + sss is 512 bytes.
016 002 Length of the U field, in bytes: uuu. Should be zero in a skeleton key-token. The maximum length of U is 256 bytes.
018 nnn Modulus n.
018 + nnn eee Public exponent field e, integer value, 1 < e < n, e must be odd. When you are building a skeleton key-token to control the generation of an RSA key pair, the public key exponent must be one of the following values: 0 (full-random), 3, or 65537. Beginning with Release 5.2, you can also specify a value of 5, 17, or 257. The exponent field can be a null-length field when preparing a skeleton key-token.
018 + nnn + eee ppp Prime number p.
018 + nnn + eee + ppp qqq Prime number q.
018 + nnn + eee + ppp + qqq rrr dp = d mod(p-1).
018 + nnn + eee + ppp + qqq + rrr sss dq = d mod(q-1).
018 + nnn + eee + ppp + qqq + rrr + sss uuu U = q-1 mod(p).
Key value structure QSA Private/public key pair form (QSA-PAIR) and QSA Public key form (QSA-PUBL)
000 001 Algorithm identifier:
X'00'
No algorithm
X'01'
CRYSTALS-Dilithium Round 2
X'02'
CRYSTALS-Kyber Round 2
X'03'
CRYSTALS-Dilithium Round 3
X'04'
CRYSTALS-Kyber Round 3
X'05'
Pure ML-DSA
X'06'
Pure ML-KEM
X'07'
Pre-hash ML-DSA
001 001 Clear key format:
X'00'
No clear key. Total structure size is 8 bytes.
X'01'
Clear private and public key pair in 'KAT format' (Known Answer Test format)
X'02'
Clear private and public key pair in 'parameterized format'
X'03'
Clear public key only. Must be specified with QSA-PUBL.
002 002

Algorithm parameters

When Algorithm identifier is X'01', allowed values are:

X'0605'
CRYSTALS-Dilithium (6,5), Round 2. See also Table 4.
X'0807'
CRYSTALS-Dilithium (8,7), Round 2. See also Table 4.

When Algorithm identifier is X'02', allowed values are:

X'1024'
CRYSTALS-Kyber (1024), Round 2. See also Table 6.
X'0768'
CRYSTALS-Kyber (0768), Round 2. See also Table 6.

When Algorithm identifier is X'03', allowed values are:

X'0605'
CRYSTALS-Dilithium (6,5), Round 3. See also Table 7.
X'0807'
CRYSTALS-Dilithium(8,7), Round 3. See also Table 7.

When Algorithm identifier is X'04', allowed values are:

X'1024'
CRYSTALS-Kyber (1024), Round 3.
X'0768'
CRYSTALS-Kyber (0768), Round 3.

When Algorithm identifier is X'05', allowed values are:

X'0404'
pure ML-DSA (4,4)
X'0605'
pure ML-DSA (6,5)
X'0807'
pure ML-DSA (8,7)

When Algorithm identifier is X'06', allowed values are:

X'0768'
ML-KEM (768)
X'1024'
ML-KEM (1024)

When Algorithm identifier is X'07', allowed values are:

X'0404'
pre-hash ML-DSA (4,4)
X'0605'
pre-hash ML-DSA (6,5)
X'0807'
pre-hash ML-DSA (8,7)
004 002 Clear key length
ppp
This field is the length of the PQC key value in bytes. This value can be zero if the key token is used as a skeleton key token in the PKA Key Generate callable service.
006 002 Reserved X'00'
008 ppp PQC private/public key pair or PQC public key value.
When the clear key format is X'01', see:
  • Table 4 for the KAT format for ML-DSA or CRYSTALS-Dilithium keys.
    Note: The format matches the format of the NIST Known Answer Test keys for ML-DSA or CRYSTALS-Dilithium, with the private key 'sk' in binary form, followed by public key 'pk'. The 'rho' appears twice.
  • Table 5 for the KAT format for ML-KEM or CRYSTALS-Kyber keys.
    Note: ML-KEM or CRYSTALS-Kyber secret key 'sk' is in binary form, which includes public key 'pk'. The normal encapsulated form of the 'sk' produced by the reference ML-KEM or CRYSTALS-Kyber includes 'pk' components mixed with 'sk' secrets, in the order shown.
When the clear key format is X'02', see:
  • Table 6 for the parameterized format for ML-DSA or CRYSTALS-Dilithium keys.
    Note: This format matches the format of the NIST Known Answer Test keys for ML-DSA or CRYSTALS-Dilithium, with the private key 'sk' in binary form, followed by public key 'pk'. The 'rho' does not appear twice.
  • Table 5 for the parameterized format for ML-KEM or CRYSTALS-Kyber keys.
    Note: ML-KEM or CRYSTALS-Kyber secret key 'sk' is in binary form, which includes public key 'pk'. The normal encapsulated form of the 'sk' produced by the reference ML-KEM or CRYSTALS-Kyber includes 'pk' components mixed with 'sk' secrets, in the order shown.
When the clear key format is X'03', see:
  • Table 7 for the public key format for ML-DSA or CRYSTALS-Dilithium keys.
    Note: This format matches the format of the NIST Known Answer Test keys for ML-DSA or CRYSTALS-Dilithium, with the public key 'pk' in binary form.
  • Table 8 for the public key format for ML-KEM or CRYSTALS-Kyber keys.
    Note: Kyber1024 secret key 'sk' in binary form, which includes public key 'pk'. Sizes of the pieces are fully determined by the reference implementation of the NIST PQC competition Round 2. The normal encapsulated form of the 'sk' produced by the reference Kyber1024 includes 'pk' components mixed with 'sk' secrets in the order shown.
Note:
  1. All length fields are in binary.
  2. All binary fields (exponent, lengths, modulus, and so on) are stored with the high-order byte field first (big-endian format). This integer number is right-aligned within the key structure element field.
  3. You must supply all values in the structure to create a token containing an RSA or ECC private key for input to the PKA Key Import verb.
Table 4. Clear key format X'01' CRYSTALS-Dilithium and ML-DSA key object layout with sizes

Clear Key format X'01' CRYSTALS-Dilithium key object layout with sizes. This table contains columns for object, Dilithium (6,5) Round 2, Dilithium (8,7) Round 2, Dilithium (6,5) Round 3, and Dilithium (8,7) Round 3. It has rows for sk (private key), pk (public key), and Clear key length at offset 004.
Object Dilithium (6,5) Round 2 Dilithium (8,7) Round 2 Dilithium (6,5) Round 3 Dilithium (8,7) Round 3 Pre-hash and pure ML-DSA (4,4) Pre-hash and pure ML-DSA (6,5) Pre-hash and pure ML-DSA (8,7)
sk (private key) rho 32 32 32 32 32 32 32
Key D, 'seed' 32 32 32 32 32 32 32
tr T ('tr') 48 48 32 32 64 64 64
s1 480 672 640 672 384 640 672
s2 576 768 768 768 384 768 768
t0 2688 3584 2496 3328 1664 2496 3328
pk (public key) rho 32 32 32 32 32 32 32
t1 1728 2304 1920 2560 1280 1920 2560
Clear key length at offset 004 of Table 3 X'15F0' (5616 bytes) X'1D30' (7472 bytes) X'1740' (5952 bytes) X'1D20' (7456 bytes) X'F20' (3872 bytes) X'1760' (5984 bytes) X'1D40’ (7488 bytes)
Table 5. Clear Key format X'01' and X'02' CRYSTALS-Kyber and ML-KEM key object layout with sizes

Clear Key format X'01' and X'02' CRYSTALS-Kyber key object layout with sizes. This table contains columns for object and Kyber (1024) Round 2. It has rows for sk (private key), pk (public key), and Clear key length at offset 004.
Object Kyber (768) Round 2 and 3 and ML-KEM Kyber (1024) Round 2 and 3 and ML-KEM
sk secret polynomial vector 1152 1536
pk public polynomial vector 1152 1536
public seed 32 32
sk hash of 'pk' 32 32
'z': random bytes 32 32
Clear key length at offset 004 of Table 3 X'0960' (2400 bytes) X'0C60' (3168 bytes)
Table 6. Clear key format X'02' CRYSTALS-Dilithium and ML-DSA key object layout with sizes

Clear Key format X'02' CRYSTALS-Dilithium key object layout with sizes. This table contains columns for object, Dilithium (6,5) Round 2, Dilithium (8,7) Round 2, Dilithium (6,5) Round 3, and Dilithium (8,7) Round 3. It has rows for pk (public key), sk (private key), pk (public key), and Clear key length at offset 004.
Object Dilithium (6,5) Round 2 Dilithium (8,7) Round 2 Dilithium (6,5) Round 3 Dilithium (8,7) Round 3 Pre-hash and pure ML-DSA (4,4) Pre-hash and pure ML-DSA (6,5) Pre-hash and pure ML-DSA (8,7)
pk (public key) rho 32 32 32 32 32 32 32
sk (private key) Key D, 'seed' 32 32 32 32 32 32 32
tr T ('tr') 48 48 32 32 64 64 64
s1 480 672 640 672 384 640 672
s2 576 768 768 768 384 768 768
t0 2688 3584 2496 3328 1664 2496 3328
pk (public key) t1 1728 2304 1920 2560 1280 1920 2560
Clear key length at offset 004 of Table 3 X'15D0' (5584 bytes) X'1D10' (7440 bytes) X'1720' (5920 bytes) X'1D00' (7424 bytes) X'F00' (3840 bytes) X'1740' (5952 bytes) X'1D20’ (7456 bytes)
Table 7. Clear key format X'03' CRYSTALS-Dilithium and ML-DSA key object layout with sizes

Clear Key format X'03' CRYSTALS-Dilithium key object layout with sizes. This table contains columns for object, Dilithium (6,5) Round 2, Dilithium (8,7) Round 2, Dilithium (6,5) Round 3, and Dilithium (8,7) Round 3. It has rows for pk (public key) and Clear key length at offset 004.
Object Dilithium (6,5) Round 2 Dilithium (8,7) Round 2 Dilithium (6,5) Round 3 Dilithium (8,7) Round 3 Pre-hash and pure ML-DSA (4,4) Pre-hash and pure ML-DSA (6,5) Pre-hash and pure ML-DSA (8,7)
pk (public key) rho 32 32 32 32 32 32 32
t1 1728 2304 1920 2560 1280 1920 2560
Clear key length at offset 004 of Table 3 X'06E0' (1760 bytes) X'0920' (2336 bytes) X'07A0' (1952 bytes) X'0A20' (2592 bytes) X'0520' (1312 bytes) X'07A0' (1952 bytes) X'0A20’ (2592 bytes)
Table 8. Clear Key format X'03' CRYSTALS-Kyber and ML-KEM key object layout with sizes

Clear Key format X'03' CRYSTALS-Kyber key object layout with sizes. This table contains columns for object and Kyber (1024) Round 2. It has rows for pk (public key) and Clear key length at offset 004.
Note: CRYSTALS-Kyber Round 2 and 3 and ML-KEM return the secret key 'sk' in binary form, which includes public key 'pk'. Sizes of the pieces are fully determined by the reference implementation of the NIST PQC competition Round 2 and 3 and FIPS 203. The normal encapsulated form of the 'sk' includes 'pk' components mixed with 'sk' secrets in the order shown.
Object Kyber (768) Round 2 and Round 3 and ML-KEM Kyber (1024) Round 2 and Round 3 and ML-KEM
pk public polynomial vector 1152 1536
public seed 32 32
Clear key length at offset 004 of Table 3 X'04A0' (1184 bytes) X'0620' (1568 bytes)
private_key_name_length
Direction: Input
Type: Integer
The length can be 0 or 64. This parameter is ignored with key type RSA-PUBL, ECC-PUBL, or QSA-PUBL.
private_key_name
Direction: Input
Type: String
This field contains the name of a private key. The name must conform to CCA key label syntax rules. That is, allowed characters are alphanumeric, national (@, #, $) or period (.). The first character must be alphabetic or national. The name is folded to upper case and converted to ASCII characters. ASCII is the permanent form of the name because the name should be independent of the platform. The name is then cryptographically coupled with clear private key data before encryption of the private key. Because of this coupling, the name can never change after the key token is imported. This parameter is ignored with key type RSA-PUBL, ECC-PUBL, or QSA-PUBL.

For RSA and QSA keys, the private-key name is stored in the PKA private-key name section of the token.

For ECC keys, the private-key name is stored in the associated data section of the token.

user_definable_associated_data_length
Direction: Input
Type: Integer
Length in bytes of the user_definable_associated_data parameter. This parameter is valid only for a key type of ECC-PAIR with a maximum value of 100 and is ignored for all other key types.
user_definable_associated_data
Direction: Input
Type: String
The user_definable_associated_data parameter identifies a string variable containing the associated data that will be placed following the IBM® associated data in the token. The associated data is data whose integrity, but not whose confidentiality, is protected by a key wrap mechanism. The user_definable_associated_data can be used to bind usage control information.

This parameter is valid only for a key type of ECC-PAIR.

key_derivation_data_length
Direction: Input
Type: Integer

The length of the key_derivation_data parameter in bytes. When the token version keyword ECC-VER1 is specified, the value must be 0 or 4. Otherwise, the value must be 0.

key_derivation_data
Direction: Input
Type: String
The 4-byte key derivation data structure describing the key to be derived. This data will be used to create the optional key derivation section of an ECC key-token. Table 9 shows the contents of this structure.
Table 9. PKA Key Token Build key-derivation-data contents, ECC keys

PKA Key Token Build key-derivation-data contents, ECC keys
Offset Length (bytes) Description
ECC key-derivation data, ECC-PAIR ECC-VER1
000 001 Algorithm of the key to be derived:
X'01'
DES
X'02'
AES
001 001 Key type of the key to be derived.

DES keys (offset 0 is X'01'):

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
Notes:
  1. CIPHER, DECIPHER, and ENCIPHER key types can be 64 bits in length, which includes 8 parity bits.
  2. All DES keys can be 128 bits in length, which includes 16 parity bits.
  3. EXPORTER, IMPORTER, CIPHER, DECIPHER, ENCIPHER key types can be 192 bits in length, which includes 24 parity bits.

AES keys (offset 0 is X'02'):

X'01'
DATA
X'02'
EXPORTER
X'03'
IMPORTER
X'04'
CIPHER
Note: All AES keys can be 128, 192, or 256 bits in length.
002 002 Key bit length: 64, 128, 192, 256
reserved_3_length
Direction: Input
Type: Integer
Length in bytes of a reserved parameter. You must set this variable to 0.
reserved_3
Direction: Input
Type: String
The reserved_3 parameter identifies a string that is reserved. The verb ignores it.
reserved_4_length
Direction: Input
Type: Integer
Length in bytes of a reserved parameter. You must set this variable to 0.
reserved_4
Direction: Input
Type: String
The reserved_4 parameter identifies a string that is reserved. The verb ignores it.
reserved_5_length
Direction: Input
Type: Integer
Length in bytes of a reserved parameter. You must set this variable to 0.
reserved_5
Direction: Input
Type: String
The reserved_5 parameter identifies a string that is reserved. The verb ignores it.
key_token_length
Direction: Input/Output
Type: Integer
Length of the returned key token. The verb checks the field to ensure that it is at least equal to the size of the token to return. On return from this verb, this field is updated with the exact length of the key_token created. On input, a size of 8000 bytes is sufficient to contain the largest key_token created.
key_token
Direction: Output
Type: String
The returned key token containing an unenciphered private or public key. The private key is in an external form that can be exchanged with different CCA PKA systems. You can use the public key token directly in appropriate CCA signature verification or key management services.