Package org.bouncycastle.jcajce.provider.asymmetric.util

Class KdfUtil

java.lang.Object

org.bouncycastle.jcajce.provider.asymmetric.util.KdfUtil

public class KdfUtil
extends java.lang.Object

The KEM secret-key derivation toolkit shared by every KEM in the provider, public so a caller building its own KEM integration can use the same pieces. The intended sequence is the one the provider's javax.crypto.KEM services follow: resolveKemSpec(java.security.spec.AlgorithmParameterSpec, java.lang.String, java.lang.String, int) to validate the caller's KTSParameterSpec (or build the default) when the encapsulator or decapsulator is created, resolveAlgorithm(org.bouncycastle.jcajce.spec.KTSParameterSpec, java.lang.String) to reconcile the requested algorithm name with the spec's per operation, and makeSecretKey(org.bouncycastle.jcajce.spec.KTSParameterSpec, byte[], int, int, java.lang.String) to derive the key - or makeKeyBytes(org.bouncycastle.jcajce.spec.KEMKDFSpec, byte[]) where raw bytes are wanted, as the KEM KeyGenerator services do. The secret-bearing inputs are erased by the methods that consume them; each javadoc says exactly when.

Constructor Summary

Constructors

Constructor	Description
KdfUtil()

Method Summary

Modifier and Type	Method	Description
static byte[]	makeKeyBytes(KEMKDFSpec kdfSpec, byte[] secret)	Generate a byte[] secret key from the passed in secret.
static javax.crypto.SecretKey	makeSecretKey(KTSParameterSpec parameterSpec, byte[] kemSecret, int from, int to, java.lang.String algorithm)	Derive a secret key from a KEM's shared secret and return the requested slice of it.
static java.lang.String	resolveAlgorithm(KTSParameterSpec parameterSpec, java.lang.String algorithm)	Reconcile the algorithm name passed to a KEM's encapsulate/decapsulate with the one its KTSParameterSpec names: "Generic" on either side defers to the other, and a genuine mismatch is refused.
static KTSParameterSpec	resolveKemSpec(java.security.spec.AlgorithmParameterSpec spec, java.lang.String algorithmName, java.lang.String parameterSetName, int sessionKeySize)	Validate a KTSParameterSpec offered to a KEM, or build the default spec - the shared secret used as it comes, with no KDF - when the caller supplied none.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

KdfUtil

public KdfUtil()

Method Detail

resolveKemSpec

public static KTSParameterSpec resolveKemSpec(java.security.spec.AlgorithmParameterSpec spec,
                                              java.lang.String algorithmName,
                                              java.lang.String parameterSetName,
                                              int sessionKeySize)
                                       throws java.security.InvalidAlgorithmParameterException

Validate a KTSParameterSpec offered to a KEM, or build the default spec - the shared secret used as it comes, with no KDF - when the caller supplied none.

Everything a KEM cannot honour is rejected here rather than at encapsulate/decapsulate time, where it would surface as an unchecked exception the javax.crypto.KEM API does not declare. Note that without a KDF the secret is the mechanism's own session key, so the requested size must be a whole number of bytes no larger than that key: javax.crypto.KEM validates encapsulate()'s range against secretSize(), so that size has to be honest rather than quietly shortened the way WrapUtil shortens a KEK to the secret it has.

Parameters:

spec - the caller-supplied spec, or null for the default.

algorithmName - the KEM's name, used in the exception messages.

parameterSetName - the name of the key's parameter set, used in the exception messages.

sessionKeySize - the size in bits of the mechanism's own session key for that set.

Returns:

the spec to use.

Throws:

java.security.InvalidAlgorithmParameterException - if the spec cannot be honoured.

makeSecretKey

public static javax.crypto.SecretKey makeSecretKey(KTSParameterSpec parameterSpec,
                                                   byte[] kemSecret,
                                                   int from,
                                                   int to,
                                                   java.lang.String algorithm)

Derive a secret key from a KEM's shared secret and return the requested slice of it.

Note: the passed in secret will be erased, as it is by makeKeyBytes(KEMKDFSpec, byte[]), and so will the derived bytes once the key has copied them. Take anything else you need from the mechanism's output - the encapsulation in particular - before calling this, and destroy the SecretWithEncapsulation it came from afterwards; that is left to the caller so the ordering stays visible at the call site.

The requested range is validated before deriving, so an out-of-range request is reported as the range error it is instead of surfacing from SecretKeySpec - the secret is erased either way.

Parameters:

parameterSpec - the KDF and output size to derive with.

kemSecret - the mechanism's shared secret (erased before this returns).

from - index of the first byte of the derived key to use.

to - index after the last byte of the derived key to use.

algorithm - the algorithm name for the returned key - reconcile it with the spec through resolveAlgorithm(KTSParameterSpec, String) first.

Returns:

the requested slice of the derived key.

resolveAlgorithm

public static java.lang.String resolveAlgorithm(KTSParameterSpec parameterSpec,
                                                java.lang.String algorithm)

Reconcile the algorithm name passed to a KEM's encapsulate/decapsulate with the one its KTSParameterSpec names: "Generic" on either side defers to the other, and a genuine mismatch is refused.

Parameters:

parameterSpec - the spec the KEM was created with.

algorithm - the algorithm name the caller asked for.

Returns:

the algorithm name to label the secret key with.

makeKeyBytes

public static byte[] makeKeyBytes(KEMKDFSpec kdfSpec,
                                  byte[] secret)

Generate a byte[] secret key from the passed in secret. Note: the passed in secret will be erased before this returns, on the failure paths included.

Parameters:

kdfSpec - definition of the KDF and the output size to produce.

secret - the secret value to initialize the KDF with (erased before this returns).

Returns:

a generated secret key.

Throws:

java.lang.IllegalArgumentException - if the spec asks for no KDF and the requested key size is larger than the shared secret the mechanism produced.