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

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(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 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.