PKA Key Generate (CSNDPKG)

Input to the PKA Key Generate verb is either a skeleton key token that has been built by the PKA Key Token Build verb, or a valid internal RSA token. In the case of a valid internal RSA token, the verb will generate a key with the same modulus length and the same exponent.

In the case of a valid internal ECC token, PKA Key Generate generates a key based on the curve type and size.

For PQC tokens, the CSNDPKG verb generates a key based on the algorithm identifier and algorithm parameter.

Internal tokens with a X'09' section are not supported.

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

• Size of the modulus in bits. The modulus for modulus-exponent form keys is between 512 and 1024. The CRT modulus is between 512 and 8192. The modulus for the variable-length-modulus-exponent form is between 512 and 8192.

RSA key generation has these restrictions: For modulus-exponent, there are restrictions on modulus, public exponent, and private exponent. For CRT, there are restrictions on dp, dq, U, and public exponent. See the Key value structure in Parameters for the PKA Key Token Build verb for more information.

ECC key generation requires this information in the skeleton token:

• The key type: ECC.
• The type of curve: NIST 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 512 for Brainpool curves.
  • 255 or 448 for Edwards curves.
  • 256 for Koblitz curves.
• Key usage information:
  • For Brainpool, Prime, and Koblitz curves, the key can be used for ECDSA and key agreement.
  • For Edwards curve, the key can be used for EdDSA only.
• Optionally, application associated data.

The generated ECC private key is returned in one of the following forms:

• Clear key.
• Encrypted key enciphered under the APKA master key.
• Encrypted key enciphered by an AES transport key.

These quantum-safe keys may be created:

• CRYSTALS-Dilithium(6,5), NIST Round 2 with OID: 1.3.6.1.4.1.2.267.1.6.5
• CRYSTALS-Dilithium (8,7), NIST Round 2 with OID: 1.3.6.1.4.1.2.267.1.8.7
• CRYSTALS-Kyber (1024), NIST Round 2 with OID: 1.3.6.1.4.1.2.267.5.4.4
• CRYSTALS-Kyber (768), NIST Round 2 with OID: 1.3.6.1.4.1.2.267.5.3.3
• CRYSTALS-Dilithium (6,5), NIST Round 3 with OID: 1.3.6.1.4.1.2.267.7.6.5
• CRYSTALS-Dilithium (8,7), NIST Round 3 with OID: 1.3.6.1.4.1.2.267.7.8.7
• CRYSTALS-Kyber(1024), NIST Round 3 with OID: 1.3.6.1.4.1.2.267.8.4.4
• CRYSTALS-Kyber (768), NIST Round 3 with OID: 1.3.6.1.4.1.2.267.8.3.3
• 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

ML-DSA or CRYSTALS-Dilithium 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’ Pure ML-DSA
  • X’07’ Pre-Hash ML-DSA
• The Algorithm parameter:
  • Use parameter value X'0605' for CRYSTALS-Dilithium (6,5) Round 2 and 3, or pre-hash and pure ML-DSA.
  • Use parameter value X'0807' for CRYSTALS-Dilithium (8,7) Round 2 and 3, or for pre-hash and pure ML-DSA.
  • Use parameter value X'0404'' for CRYSTALS-Dilithium (4,4), and for pure and pre-hash ML-DSA
• PKA key usage information:
  • For CRYSTALS-Dilithium and for pure and pre-hash ML-DSA, U-DIGSIG is required.

ML-KEM or CRYSTALS-Kyber 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:
  • Use parameter value X'1024' for CRYSTALS-Kyber (1024) Round 2 or Round 3 or for ML-KEM.
  • Use parameter value X'0768' for CRYSTALS-Kyber (0768) Round 2 or Round 3 or for ML-KEM.
• PKA key usage information:
  • For CRYSTALS-Kyber and ML-KEM, UKEY-ENC or UDATAENC is required.

The generated ML-KEM, ML-DSA, CRYSTALS-Dilithium or CRYSTALS-Kyber private key is returned in one of the following forms:

• Clear key.
• Encrypted key enciphered under the APKA master key.
• Additionally, an ML-KEM key may be returned encrypted under an AES key-encrypting key (KEK).

Unenciphered

When rule-array keyword CLEAR is specified, the PKA private key is returned in cleartext form. The clear key is returned in an external PKA key-token.

Enciphered using a master key

When rule-array keyword MASTER is specified, a master key is used to protect the private key or its OPK if the private key has one. The enciphered key is returned in an internal PKA key-token. ECC keys (section X'20') and RSA keys in section X'30' and X'31' have an OPK that is enciphered by the APKA master key. All other RSA keys are enciphered by the PKA master key.

Enciphered using a transport key

When rule-array keyword XPORT is specified, a transport key (key-encrypting key) is used to protect the private key or its object protection key (OPK) if the private key has one. The enciphered key is returned in an external PKA key-token. By definition, an ECC private-key section always has an OPK, while an RSA private-key section either has an OPK or it does not, depending on the section identifier. v The OPK of an external ECC private-key is enciphered under a variable-length AES EXPORTER or IMPORTER key-encrypting key after the OPK is used to encipher the private key. Two private key sections are defined, X'30' and X'31'. When the key token is external, the OPK data contained in either private-key section X'30' or X'31' is enciphered under a variable-length AES EXPORTER or IMPORTER key-encrypting key after it is used to encipher the private key. An external RSA private-key that does not have a private-key section of X'30' or X'31' is enciphered under a fixed-length DES EXPORTER or IMPORTER key-encrypting key.

Note: A private key enciphered by an EXPORTER key can be imported onto a node where the corresponding IMPORTER key is installed. In contrast, a private key enciphered by an IMPORTER key can be imported onto the generating node.

With the exception of RSA private key sections X'30' and X'31', use the RETAIN rule-array keyword to cause an RSA private key to be retained within the coprocessor. Incorporate the key label to be used later to reference the newly generated key in the key name section of the skeleton key-token. Later, use this label to employ the key in verbs such asDigital Signature Generate,Symmetric Key Import, SET Block Decompose, and PKA Decrypt.

On output, the verb returns an external key-token containing the public key in the generated_key_identifier variable. This variable returned by the verb does not contain the private key.

The rule array keyword CLONE flags a generated and retained RSA private-key as usable in an engine cloning process. Cloning is a technique for copying sensitive coprocessor information from one coprocessor to another (see Understanding and managing master keys). ECC private keys and RSA keys in private key sections X'30' or X'31' are not usable in an engine cloning process.

If you include an RSA public-key certificate section within the PKA skeleton key-token, the cryptographic engine signs a certificate with the key that is designated in the RSA public-key certificate signature subsection. This technique causes the cryptographic engine to sign the newly generated RSA public key using another key that has been retained within the engine, including the newly generated key (producing a self-signature). You can obtain more than one signature on the public key when you include multiple signature subsections in the skeleton key token. See PKA public-key certificate section.

This verb does not need to document any Usage notes.