* The {@code getInstance} method creates a new {@code KEM} object that * implements the specified algorithm. *
* A {@code KEM} object is immutable. It is safe to call multiple * {@code newEncapsulator} and {@code newDecapsulator} methods on the * same {@code KEM} object at the same time. *
* If a provider is not specified in the {@code getInstance} method when * instantiating a {@code KEM} object, the {@code newEncapsulator} and * {@code newDecapsulator} methods may return encapsulators or decapsulators * from different providers. The provider selected is based on the parameters * passed to the {@code newEncapsulator} or {@code newDecapsulator} methods: * the private or public key and the optional {@code AlgorithmParameterSpec}. * The {@link Encapsulator#providerName} and {@link Decapsulator#providerName} * methods return the name of the selected provider. *
* {@code Encapsulator} and {@code Decapsulator} objects are also immutable. * It is safe to invoke multiple {@code encapsulate} and {@code decapsulate} * methods on the same {@code Encapsulator} or {@code Decapsulator} object * at the same time. Each invocation of {@code encapsulate} will generate a * new shared secret and key encapsulation message. *
* * Example operation using a fictitious {@code KEM} algorithm {@code ABC}: * {@snippet lang = java: * // Receiver side * KeyPairGenerator g = KeyPairGenerator.getInstance("ABC"); * KeyPair kp = g.generateKeyPair(); * publishKey(kp.getPublic()); * * // Sender side * KEM senderKEM = KEM.getInstance("ABC"); * PublicKey receiverPublicKey = retrieveKey(); * ABCKEMParameterSpec senderSpec = new ABCKEMParameterSpec(args); * KEM.Encapsulator e = senderKEM.newEncapsulator( * receiverPublicKey, senderSpec, null); * KEM.Encapsulated enc = e.encapsulate(); * SecretKey senderSecret = enc.key(); * * sendBytes(enc.encapsulation()); * sendBytes(enc.params()); * * // Receiver side * byte[] ciphertext = receiveBytes(); * byte[] params = receiveBytes(); * * KEM receiverKEM = KEM.getInstance("ABC"); * AlgorithmParameters algParams = * AlgorithmParameters.getInstance("ABC"); * algParams.init(params); * ABCKEMParameterSpec receiverSpec = * algParams.getParameterSpec(ABCKEMParameterSpec.class); * KEM.Decapsulator d = * receiverKEM.newDecapsulator(kp.getPrivate(), receiverSpec); * SecretKey receiverSecret = d.decapsulate(ciphertext); * * // senderSecret and receiverSecret should now be equal. * } * * @since 21 */ public final class KEM { /** * This class specifies the return value of the encapsulate method of * a Key Encapsulation Mechanism (KEM), which includes the shared secret * (as a {@code SecretKey}), the key encapsulation message, * and optional parameters. *
* Note: the key encapsulation message can be also referred to as ciphertext. * * @see #newEncapsulator(PublicKey, AlgorithmParameterSpec, SecureRandom) * @see Encapsulator#encapsulate(int, int, String) * * @since 21 */ public static final class Encapsulated { private final SecretKey key; private final byte[] encapsulation; private final byte[] params; /** * Constructs an {@code Encapsulated} object. * * @param key the shared secret as a key, must not be {@code null}. * @param encapsulation the key encapsulation message, must not * be {@code null}. The contents of the array are copied * to protect against subsequent modification. * @param params optional parameters, can be {@code null}. * The contents of the array are copied to protect * against subsequent modification. * @throws NullPointerException if {@code key} or {@code encapsulation} * is {@code null} */ public Encapsulated(SecretKey key, byte[] encapsulation, byte[] params) { Objects.requireNonNull(key); Objects.requireNonNull(encapsulation); this.key = key; this.encapsulation = encapsulation.clone(); this.params = params == null ? null : params.clone(); } /** * Returns the {@code SecretKey}. * * @return the secret key */ public SecretKey key() { return key; } /** * Returns the key encapsulation message. * * @return the key encapsulation message. A new copy of the byte array * is returned. */ public byte[] encapsulation() { return encapsulation.clone(); } /** * Returns the optional parameters in a byte array. * * @return the optional parameters in a byte array or {@code null} * if not specified. A new copy of the byte array is returned. */ public byte[] params() { return params == null ? null : params.clone(); } } /** * An encapsulator, generated by {@link #newEncapsulator} on the KEM * sender side. *
* This class represents the key encapsulation function of a KEM. * Each invocation of the {@code encapsulate} method generates a * new secret key and key encapsulation message that is returned * in an {@link Encapsulated} object. * * @since 21 */ public static final class Encapsulator { private final KEMSpi.EncapsulatorSpi e; private final Provider p; private Encapsulator(KEMSpi.EncapsulatorSpi e, Provider p) { assert e != null; assert p != null; this.e = e; this.p = p; } /** * Returns the name of the provider. * * @return the name of the provider */ public String providerName() { return p.getName(); } /** * The key encapsulation function. *
* This method is equivalent to * {@code encapsulate(0, secretSize(), "Generic")}. This combination * of arguments must be supported by every implementation. *
* The generated secret key is usually passed to a key derivation * function (KDF) as the input keying material. * * @return a {@link Encapsulated} object containing the shared * secret, key encapsulation message, and optional parameters. * The shared secret is a {@code SecretKey} containing all of * the bytes of the secret, and an algorithm name of "Generic". */ public Encapsulated encapsulate() { return encapsulate(0, secretSize(), "Generic"); } /** * The key encapsulation function. *
* Each invocation of this method generates a new secret key and key * encapsulation message that is returned in an {@link Encapsulated} object. *
* An implementation may choose to not support arbitrary combinations * of {@code from}, {@code to}, and {@code algorithm}. * * @param from the initial index of the shared secret byte array * to be returned, inclusive * @param to the final index of the shared secret byte array * to be returned, exclusive * @param algorithm the algorithm name for the secret key that is returned. * See the SecretKey Algorithms section in the * * Java Security Standard Algorithm Names Specification * for information about standard secret key algorithm names. * Specify "Generic" if the output will be used as the input keying * material of a key derivation function (KDF). * @return a {@link Encapsulated} object containing a portion of * the shared secret, key encapsulation message, and optional * parameters. The portion of the shared secret is a * {@code SecretKey} containing the bytes of the secret * ranging from {@code from} to {@code to}, exclusive, * and an algorithm name as specified. For example, * {@code encapsulate(0, 16, "AES")} uses the first 16 bytes * of the shared secret as a 128-bit AES key. * @throws IndexOutOfBoundsException if {@code from < 0}, * {@code from > to}, or {@code to > secretSize()} * @throws NullPointerException if {@code algorithm} is {@code null} * @throws UnsupportedOperationException if the combination of * {@code from}, {@code to}, and {@code algorithm} * is not supported by the encapsulator * @spec security/standard-names.html Java Security Standard Algorithm Names */ public Encapsulated encapsulate(int from, int to, String algorithm) { return e.engineEncapsulate(from, to, algorithm); } /** * Returns the size of the shared secret. *
* This method can be called to find out the length of the shared secret * before {@code encapsulate} is called or if the obtained * {@code SecretKey} is not extractable. * * @return the size of the shared secret */ public int secretSize() { int result = e.engineSecretSize(); assert result >= 0 && result != Integer.MAX_VALUE : "invalid engineSecretSize result"; return result; } /** * Returns the size of the key encapsulation message. *
* This method can be called to find out the length of the encapsulation * message before {@code encapsulate} is called. * * @return the size of the key encapsulation message */ public int encapsulationSize() { int result = e.engineEncapsulationSize(); assert result >= 0 && result != Integer.MAX_VALUE : "invalid engineEncapsulationSize result"; return result; } } /** * A decapsulator, generated by {@link #newDecapsulator} on the KEM * receiver side. *
* This class represents the key decapsulation function of a KEM. * An invocation of the {@code decapsulate} method recovers the * secret key from the key encapsulation message. * * @since 21 */ public static final class Decapsulator { private final KEMSpi.DecapsulatorSpi d; private final Provider p; private Decapsulator(KEMSpi.DecapsulatorSpi d, Provider p) { assert d != null; assert p != null; this.d = d; this.p = p; } /** * Returns the name of the provider. * * @return the name of the provider */ public String providerName() { return p.getName(); } /** * The key decapsulation function. *
* This method is equivalent to * {@code decapsulate(encapsulation, 0, secretSize(), "Generic")}. This * combination of arguments must be supported by every implementation. *
* The generated secret key is usually passed to a key derivation * function (KDF) as the input keying material. * * @param encapsulation the key encapsulation message from the sender. * The size must be equal to the value returned by * {@link #encapsulationSize()}, or a {@code DecapsulateException} * will be thrown. * @return the shared secret as a {@code SecretKey} with * an algorithm name of "Generic" * @throws DecapsulateException if an error occurs during the * decapsulation process * @throws NullPointerException if {@code encapsulation} is {@code null} */ public SecretKey decapsulate(byte[] encapsulation) throws DecapsulateException { return decapsulate(encapsulation, 0, secretSize(), "Generic"); } /** * The key decapsulation function. *
* An invocation of this method recovers the secret key from the key * encapsulation message. *
* An implementation may choose to not support arbitrary combinations * of {@code from}, {@code to}, and {@code algorithm}. * * @param encapsulation the key encapsulation message from the sender. * The size must be equal to the value returned by * {@link #encapsulationSize()}, or a {@code DecapsulateException} * will be thrown. * @param from the initial index of the shared secret byte array * to be returned, inclusive * @param to the final index of the shared secret byte array * to be returned, exclusive * @param algorithm the algorithm name for the secret key that is returned. * See the SecretKey Algorithms section in the * * Java Security Standard Algorithm Names Specification * for information about standard secret key algorithm names. * Specify "Generic" if the output will be used as the input keying * material of a key derivation function (KDF). * @return a portion of the shared secret as a {@code SecretKey} * containing the bytes of the secret ranging from {@code from} * to {@code to}, exclusive, and an algorithm name as specified. * For example, {@code decapsulate(encapsulation, secretSize() * - 16, secretSize(), "AES")} uses the last 16 bytes * of the shared secret as a 128-bit AES key. * @throws DecapsulateException if an error occurs during the * decapsulation process * @throws IndexOutOfBoundsException if {@code from < 0}, * {@code from > to}, or {@code to > secretSize()} * @throws NullPointerException if {@code encapsulation} or * {@code algorithm} is {@code null} * @throws UnsupportedOperationException if the combination of * {@code from}, {@code to}, and {@code algorithm} * is not supported by the decapsulator * @spec security/standard-names.html Java Security Standard Algorithm Names */ public SecretKey decapsulate(byte[] encapsulation, int from, int to, String algorithm) throws DecapsulateException { return d.engineDecapsulate( encapsulation, from, to, algorithm); } /** * Returns the size of the shared secret. *
* This method can be called to find out the length of the shared secret * before {@code decapsulate} is called or if the obtained * {@code SecretKey} is not extractable. * * @return the size of the shared secret */ public int secretSize() { int result = d.engineSecretSize(); assert result >= 0 && result != Integer.MAX_VALUE : "invalid engineSecretSize result"; return result; } /** * Returns the size of the key encapsulation message. *
* This method can be used to extract the encapsulation message
* from a longer byte array if no length information is provided
* by a higher level protocol.
*
* @return the size of the key encapsulation message
*/
public int encapsulationSize() {
int result = d.engineEncapsulationSize();
assert result >= 0 && result != Integer.MAX_VALUE
: "invalid engineEncapsulationSize result";
return result;
}
}
private static final class DelayedKEM {
private final Provider.Service[] list; // non empty array
private DelayedKEM(Provider.Service[] list) {
this.list = list;
}
private Encapsulator newEncapsulator(PublicKey publicKey,
AlgorithmParameterSpec spec, SecureRandom secureRandom)
throws InvalidAlgorithmParameterException, InvalidKeyException {
if (publicKey == null) {
throw new InvalidKeyException("input key is null");
}
RuntimeException re = null;
InvalidAlgorithmParameterException iape = null;
InvalidKeyException ike = null;
NoSuchAlgorithmException nsae = null;
for (Provider.Service service : list) {
if (!service.supportsParameter(publicKey)) {
continue;
}
try {
KEMSpi spi = (KEMSpi) service.newInstance(null);
return new Encapsulator(
spi.engineNewEncapsulator(publicKey, spec, secureRandom),
service.getProvider());
} catch (NoSuchAlgorithmException e) {
nsae = merge(nsae, e);
} catch (InvalidAlgorithmParameterException e) {
iape = merge(iape, e);
} catch (InvalidKeyException e) {
ike = merge(ike, e);
} catch (RuntimeException e) {
re = merge(re, e);
}
}
if (iape != null) throw iape;
if (ike != null) throw ike;
if (nsae != null) {
throw new InvalidKeyException("No installed provider found", nsae);
}
throw new InvalidKeyException("No installed provider supports this key: "
+ publicKey.getClass().getName(), re);
}
private static
* This method is equivalent to {@code newEncapsulator(publicKey, null, null)}.
*
* @param publicKey the receiver's public key, must not be {@code null}
* @return the encapsulator for this key
* @throws InvalidKeyException if {@code publicKey} is {@code null} or invalid
* @throws UnsupportedOperationException if this method is not supported
* because an {@code AlgorithmParameterSpec} must be provided
*/
public Encapsulator newEncapsulator(PublicKey publicKey)
throws InvalidKeyException {
try {
return newEncapsulator(publicKey, null, null);
} catch (InvalidAlgorithmParameterException e) {
throw new UnsupportedOperationException(
"AlgorithmParameterSpec must be provided", e);
}
}
/**
* Creates a KEM encapsulator on the KEM sender side.
*
* This method is equivalent to {@code newEncapsulator(publicKey, null, secureRandom)}.
*
* @param publicKey the receiver's public key, must not be {@code null}
* @param secureRandom the source of randomness for encapsulation.
* If {@code} null, a default one from the
* implementation will be used.
* @return the encapsulator for this key
* @throws InvalidKeyException if {@code publicKey} is {@code null} or invalid
* @throws UnsupportedOperationException if this method is not supported
* because an {@code AlgorithmParameterSpec} must be provided
*/
public Encapsulator newEncapsulator(PublicKey publicKey, SecureRandom secureRandom)
throws InvalidKeyException {
try {
return newEncapsulator(publicKey, null, secureRandom);
} catch (InvalidAlgorithmParameterException e) {
throw new UnsupportedOperationException(
"AlgorithmParameterSpec must be provided", e);
}
}
/**
* Creates a KEM encapsulator on the KEM sender side.
*
* An algorithm can define an {@code AlgorithmParameterSpec} child class to
* provide extra information in this method. This is especially useful if
* the same key can be used to derive shared secrets in different ways.
* If any extra information inside this object needs to be transmitted along
* with the key encapsulation message so that the receiver is able to create
* a matching decapsulator, it will be included as a byte array returned by the
* {@link Encapsulated#params()} method within the encapsulation output.
* In this case, the security provider should provide an
* {@code AlgorithmParameters} implementation using the same algorithm name
* as the KEM. The receiver can initiate such an {@code AlgorithmParameters}
* instance with the {@code params} byte array received and recover
* an {@code AlgorithmParameterSpec} object to be used in its
* {@link #newDecapsulator(PrivateKey, AlgorithmParameterSpec)} call.
*
* @param publicKey the receiver's public key, must not be {@code null}
* @param spec the optional parameter, can be {@code null}
* @param secureRandom the source of randomness for encapsulation.
* If {@code} null, a default one from the
* implementation will be used.
* @return the encapsulator for this key
* @throws InvalidAlgorithmParameterException if {@code spec} is invalid
* or one is required but {@code spec} is {@code null}
* @throws InvalidKeyException if {@code publicKey} is {@code null} or invalid
*/
public Encapsulator newEncapsulator(PublicKey publicKey,
AlgorithmParameterSpec spec, SecureRandom secureRandom)
throws InvalidAlgorithmParameterException, InvalidKeyException {
return delayed != null
? delayed.newEncapsulator(publicKey, spec, secureRandom)
: new Encapsulator(spi.engineNewEncapsulator(publicKey, spec, secureRandom), provider);
}
/**
* Creates a KEM decapsulator on the KEM receiver side.
*
* This method is equivalent to {@code newDecapsulator(privateKey, null)}.
*
* @param privateKey the receiver's private key, must not be {@code null}
* @return the decapsulator for this key
* @throws InvalidKeyException if {@code privateKey} is {@code null} or invalid
* @throws UnsupportedOperationException if this method is not supported
* because an {@code AlgorithmParameterSpec} must be provided
*/
public Decapsulator newDecapsulator(PrivateKey privateKey)
throws InvalidKeyException {
try {
return newDecapsulator(privateKey, null);
} catch (InvalidAlgorithmParameterException e) {
throw new UnsupportedOperationException(e);
}
}
/**
* Creates a KEM decapsulator on the KEM receiver side.
*
* @param privateKey the receiver's private key, must not be {@code null}
* @param spec the parameter, can be {@code null}
* @return the decapsulator for this key
* @throws InvalidAlgorithmParameterException if {@code spec} is invalid
* or one is required but {@code spec} is {@code null}
* @throws InvalidKeyException if {@code privateKey} is {@code null} or invalid
*/
public Decapsulator newDecapsulator(PrivateKey privateKey, AlgorithmParameterSpec spec)
throws InvalidAlgorithmParameterException, InvalidKeyException {
return delayed != null
? delayed.newDecapsulator(privateKey, spec)
: new Decapsulator(spi.engineNewDecapsulator(privateKey, spec), provider);
}
/**
* Returns the name of the algorithm for this {@code KEM} object.
*
* @return the name of the algorithm for this {@code KEM} object.
*/
public String getAlgorithm() {
return this.algorithm;
}
}