PKA Key Token Build (CSNDPKB)

Edit online

Use this verb to build external PKA key tokens containing unenciphered private RSA, ECC, or PQC keys (an ML-KEM, ML-DSA, CRYSTALS-Dilithium, or CRYSTALS-Kyber key pair).

You can use this token as input to the PKA Key Import verb to obtain an operational internal token containing an enciphered private key. This verb builds a skeleton token that you can use as input to the PKA Key Generate verb (see Table 1). You can also input to this verb a clear unenciphered public RSA or ECC key and return the public key in a token format that other PKA verbs can use directly.

Specifically, you can use this verb to:

  • Build external PKA key tokens containing unencrypted private keys for ECC, RSA, CRYSTALS-Dilithium, CRYSTALS-Kyber, ML-KEM, or pure or pre-hash ML-DSA keys. You can use this token as input to the PKA Key Import service to obtain an operational internal token containing an enciphered private key.
  • Build external RSA key tokens with the private key for use with the PKA Key Translate service.
  • Build a skeleton token for ECC, RSA, CRYSTALS-Dilithium, CRYSTALS-Kyber, ML-KEM, or pure or pre-hash ML-DSA keys that you can use as input to the PKA Key Generate service.
  • Build a public key token containing a clear unencrypted public key for an ECC or RSA keys and return the public key in a token format that other PKA services can use directly.
  • An RSA token with X'09' section identifier using the RSAMEVAR keyword to obtain a token for a key in modulus-exponent format that is variable length.

ECC key generation requires this information in the skeleton token:

  • The key type: ECC
  • The type of curve: Prime, Brainpool, Edwards, or Koblitz.
  • The size of p in bits:
    • 192, 224, 256, 384 or 521 for Prime curves
    • 160, 192, 224, 256, 320, 384, or 521 for Brainpool curves
    • 255 or 448 for Edwards curves.
    • 256 for Koblitz curves.
  • Key usage information:
    • If an ECC private key specifies an Edwards curve, it can be used for EdDSA only.
    • The Edwards keys are not usable outside their specified cryptography system. When creating the Edwards (Ed25519, Ed448) skeleton key token for use with EdDSA, the SIG-ONLY key usage keyword is required.
    • If an ECC private key specifies an Edwards curve, it cannot be used for ECDSA.
    • Koblitz curve (secp256k1) keys have the same usage constraints as Prime 256 curve keys.
  • Optionally, application associated data.
  • Optionally, a key-derivation section.

RSA key generation requires this following information in the skeleton token:

  • In modulus-exponent format:
    • The length of the modulus n (512-4096 bits).
    • The length of the public exponent e (optional).
    • The length of the private exponent d (optional).
    • The public exponent e (optional).
  • In Chinese Remainder Theorem format:
    • The length of the modulus n (512-4096 bits).
    • The length of the public exponent e (optional).
    • The public exponent e (optional).
    • Other optional lengths.
  • There are restrictions on the value and length of the RSA public exponent:
    • For RSA keys with modulus lengths less than or equal to 4096 bits, the public exponent can be 3, 5, 17, 257, 65537 or random. The length of the random exponent in the random case will match the bit length of the modulus.
    • For 2049-bit to 8192-bit RSA keys, the public exponent may have a value of 3, 5, 17, 257, 65537, or random.
    • Support for a random public exponent requires zEC12, zBC12, and later systems with a CEX4C or later coprocessor with September 2013 or later licensed internal code (LIC).
    • Support for RSA public exponents of values 5, 17, and 257 requires the October 2016 or later licensed internal code (LIC).

These quantum-safe keys may be created:

  • ML-DSA pure
    • (4,4), OID: 2.16.840.1.101.3.4.3.17
    • (6,5), OID: 2.16.840.1.101.3.4.3.18
    • (8,7), OID: 2.16.840.1.101.3.4.3.19
  • ML-DSA pre-hash
    • (4,4-SHA512), OID: 2.16.840.1.101.3.4.3.32
    • (6,5-SHA512), OID: 2.16.840.1.101.3.4.3.33
    • (8,7-SHA512), OID: 2.16.840.1.101.3.4.3.34
  • ML-KEM
    • (768), OID: 2.16.840.1.101.3.4.4.2
    • (1024), OID: 2.16.840.1.101.3.4.4.3
  • CRYSTALS-Dilithium Round 2
    • (6,5), OID: 1.3.6.1.4.1.2.267.1.6.5
    • (8,7), OID: 1.3.6.1.4.1.2.267.1.8.7
  • CRYSTALS-Dilithium Round 3
    • (6,5), OID: 1.3.6.1.4.1.2.267.7.6.5
    • (8,7), OID: 1.3.6.1.4.1.2.267.7.8.7
  • CRYSTALS-Kyber Round 2
    • (768), OID: 1.3.6.1.4.1.2.267.5.3.3
    • (1024), OID: 1.3.6.1.4.1.2.267.5.4.4
  • CRYSTALS-Kyber Round 3
    • (768), OID: 1.3.6.1.4.1.2.267.8.3.3
    • (1024), OID: 1.3.6.1.4.1.2.267.8.4.4

CRYSTALS-Dilithium or ML-DSA key generation requires the following information in the skeleton token:

  • The Algorithm identifier:
    • X'01' CRYSTALS-Dilithium Round 2.
    • X'03' CRYSTALS-Dilithium Round 3.
    • X’05’ ML-DSA pure
    • X’07’ ML-DSA pre-hash
  • The Algorithm parameter:
    • X'0605' CRYSTALS-Dilithium (6,5) Round 2 or Round 3 or ML-DSA pure and pre-hash
    • X'0807' CRYSTALS-Dilithium (8,7) Round 2 or Round 3 or ML-DSA pure and pre-hash
    • X'0404' CRYSTALS-Dilithium (4,4), or ML-DSA pure and pre-hash
  • PKA key usage information:
    • For CRYSTALS-Dilithium or ML-DSA, U-DIGSIG is required.
    • CRYSTALS-Dilithium or ML-DSA keys are only usable for signature creation and verification.

CRYSTALS-Kyber and ML-KEM key generation requires the following information in the skeleton token:

  • The Algorithm identifier:
    • X'02' CRYSTALS-Kyber Round 2.
    • X'04' CRYSTALS-Kyber Round 3.
    • X'06' ML-KEM
  • The Algorithm parameter:
    • X'1024' CRYSTALS-Kyber (1024) Round 2 or Round 3 or ML-KEM
    • X'0768' CRYSTALS-Kyber (768) Round 2 or Round 3 or ML-KEM
  • PKA key usage information:
    • CRYSTALS-Kyber or ML-KEM keys are only usable for encryption, decryption, and key encapsulation. The U-KEYENC or U-DATENC keyword must be selected.

This verb does not need to document any Required commands nor Usage notes.