Class KdfUtil

java.lang.Object
org.bouncycastle.jcajce.provider.asymmetric.util.KdfUtil
public class KdfUtil extends 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(AlgorithmParameterSpec, String, String, int) to validate the caller's KTSParameterSpec (or build the default) when the encapsulator or decapsulator is created, resolveAlgorithm(KTSParameterSpec, String) to reconcile the requested algorithm name with the spec's per operation, and makeSecretKey(KTSParameterSpec, byte[], int, int, String) to derive the key - or makeKeyBytes(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 Details

    • KdfUtil

      public KdfUtil()

  • Method Details

    • resolveKemSpec

      public static KTSParameterSpec resolveKemSpec(AlgorithmParameterSpec spec, String algorithmName, String parameterSetName, int sessionKeySize) throws 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:
      InvalidAlgorithmParameterException - if the spec cannot be honoured.

    • makeSecretKey

      public static SecretKey makeSecretKey(KTSParameterSpec parameterSpec, byte[] kemSecret, int from, int to, 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 String resolveAlgorithm(KTSParameterSpec parameterSpec, 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:
      IllegalArgumentException - if the spec asks for no KDF and the requested key size is larger than the shared secret the mechanism produced.