public abstract Class NamedKeyPairGenerator

Together with NamedKeyFactory, NamedKEM, and NamedSignature, these classes form a compact framework designed to support any public key algorithm standardized with named parameter sets. In this scenario, the algorithm name is the "family name" and each standardized parameter set has a "parameter set name". Implementations of these classes are able to instantiate a KeyPairGenerator, KeyFactory, or KEM or Signature object using either the family name or a parameter set name. All keys used in this context will be of the type NamedPKCS8Key or NamedX509Key, with getAlgorithm returning the family name, and getParams returning the parameter set name as a NamedParameterSpec object.

A NamedKeyPairGenerator or NamedKeyFactory implementation must include a zero-argument public constructor that calls super(fname, pnames), where fname is the family name of the algorithm and pnames are its supported parameter set names. pnames must contain at least one element. For an implementation of NamedKeyPairGenerator, the first element becomes its default parameter set, i.e. the parameter set used by generated keys unless initialize(AlgorithmParameterSpec, java.security.SecureRandom) is called on a different parameter set.

A NamedKEM or NamedSignature implementation must include a zero-argument public constructor that calls super(fname, factory), where fname is the family name of the algorithm and factory is the NamedKeyFactory object that is used to translate foreign keys. factory only recognizes parameter sets supported by this implementation.

An implementation must implement all abstract methods. For all these methods, the implementation must relinquish any "ownership" of any input and output array argument. Precisely, the implementation must not retain any reference to a returning array so that it won't be able to modify its content later. Similarly, the implementation must not modify any input array argument and must not retain any reference to an input array argument after the call.

Also, an implementation must not keep any extra copy of a private key in any format. For key generation, the only copy is the one returned in the implGenerateKeyPair call. For all other methods, it must not make a copy of the input private key. A KEM implementation also must not keep a copy of the shared secret key, no matter if it's an encapsulator or a decapsulator. Only the code that owns these sensitive data can choose to perform cleanup when it determines they are no longer needed.

The NamedSignature and NamedKEM classes provide implCheckPublicKey and implCheckPrivateKey methods that allow an implementation to validate a key before using it. An implementation may return a parsed key in a local type, and this parsed key will be passed to an operational method (For example, implSign) later. An implementation must not retain a reference of the parsed key.

The private key, represented as a byte array when used in NamedKEM or NamedSignature, is referred to as its expanded format. For some algorithms, this format may differ from the key material inside a PKCS #8 file. For example, FIPS 204 Table 2 defines the ML-DSA-65 private key as a 4032-byte array, which is used in the ML-DSA.Sign function in Algorithm 2, representing the expanded format. However, in RFC 9881, a private key can be encoded into a CHOICE of three formats, none in the same as the FIPS 204 format. The choices are defined in sun.security.util.KeyChoices. A NamedKeyPairGenerator implementation should return both the expanded key and a preferred encoding in its implGenerateKeyPair method.

A NamedKeyFactory must override the implExpand method to derive the expanded format from an encoding format, or return null if there is no difference.

Implementations may support multiple encoding formats.

A NamedKeyFactory must not modify the encoding when generating a key from a KeySpec object, ensuring that when re-encoded, the key retains its original encoding format.

A NamedKeyFactory can choose a different encoding format when translateKey is called.

When constructing a NamedX509Key or NamedPKCS8Key object from raw key bytes, the key bytes are directly referenced within the object, so the caller must not modify them afterward. Similarly, the key's getRawBytes method returns direct references to the underlying raw key bytes, meaning the caller must not alter the contents of the returned value.

Together, these measures ensure the classes are as efficient as possible, preventing unnecessary array cloning and potential data leaks. While these classes should not be considered immutable, strictly adhering to the rules above will ensure data integrity is maintained.