javax.crypto.KeyDerivation
==========================

/**
 * This class provides the functionality of a key derivation algorithm for the
 * Java Cryptographic Extension (JCE) framework.
 *
 * {@code KeyDerivation} objects will be instantiated
 * through the {@code getInstance} family of methods.
 * Input keying material, algorithm parameters, and the desired types and
 * lengths of output are provided through the {@code init} method, which
 * must be called before key derivation can begin.
 *
 * Keys may be derived singly or in a batch through the {@code deriveKey} and
 * {@code deriveKeys} methods, respectively.  Algorithms that support multiple
 * output keys from a single set of parameters can support repeated calls to
 * {@code deriveKey} and/or {@code deriveKeys}.  Algorithms intended for
 * single-key derivations may throw {@code IllegalStateException}.
 */

public class KeyDerivation {

    /**
     * Returns the algorithm name of this {@code KeyDerivation} object.
     *
     * <p>This is the same name that was specified in one of the
     * {@code getInstance} calls that created this
     * {@code KeyDerivation} object.
     *
     * @return the algorithm name of this {@code KeyDerivation} object.
     */
    public final String getAlgorithm();

    /**
     * Returns the provider of this {@code KeyDerivation} object.
     *
     * @return the provider of this {@code KeyDerivation} object.
     */
    public final Provider getProvider();

    /**
     * Creates an instance of the {@code KeyDerivation} object.
     *
     * @param algorithm the key derivation algorithm to use
     *
     * @return a {@code KeyDerivation} object
     *
     * @throws NoSuchAlgorithmException if no {@code Provider} supports a
     *         {@code KeyDerivationSpi} implementation for the
     *         specified algorithm.
     */
    public static final KeyDerivation getInstance(String algorithm)
            throws NoSuchAlgorithmException;

    /**
     * Creates an instance of the {@code KeyDerivation} object on a specific
     * {@code Provider}.
     *
     * @param algorithm the key derivation algorithm to use
     * @param provider the provider to use for this key derivation
     *
     * @return a {@code KeyDerivation} object
     *
     * @throws NoSuchAlgorithmException if no {@code Provider} supports a
     *         {@code KeyDerivationSpi} implementation for the
     *         specified algorithm.
     * @throws NoSuchProviderException if the specified provider is not
     *         registered in the security provider list.
     */
    public static final KeyDerivation getInstance(String algorithm,
            String provider) throws NoSuchAlgorithmException,
            NoSuchProviderException;

    /**
     * Creates an instance of the {@code KeyDerivation} object using a
     * supplied {@code Provider} instance.
     *
     * @param algorithm the key derivation algorithm to use
     * @param provider the provider
     *
     * @return a {@code KeyDerivation} object
     *
     * @throws NoSuchAlgorithmException if no {@code Provider} supports a
     *         {@code KeyDerivationSpi} implementation for the
     *         specified algorithm.
     */
    public static final KeyDerivation getInstance(String algorithm,
            Provider provider) throws NoSuchAlgorithmException;

    /**
     * Initializes the {@code KeyDerivation} object.  The {@code init} method
     * must be called prior to calling any of the derivation methods.
     * Subsequent calls to {@code init} may be performed, allowing the caller
     * to restart the key derivation process using different input keys,
     * KDF parameters and/or derived output parameters.
     *
     * @param secretKey the input keying material
     * @param kdfParams the parameters for the key derivation function
     * @param deriveParams a {@code List} of one or more
     *        {@code DerivationParameterSpec} objects detailing the
     *        characteristics for the output keys, data, and/or objects from
     *        this key derivation function.
     *
     * @throws InvalidKeyException if the given key is inappropriate for
     *         initializing this MAC
     * @throws InvalidParameterSpecException if the
     *         {@code AlgorithmParameterSpec} passed in contains invalid
     *         data or is an incorrect type for the selected algorithm.  This
     *         exception will also be thrown if the list of
     *         {@code DerivationParameterSpec} objects contains invalid data.
     */
    public void init(SecretKey secretKey, AlgorithmParameterSpec kdfParams,
            List<DerivationParameterSpec> deriveParams)
            throws InvalidKeyException, InvalidParameterSpecException;

    /**
     * Derive a key, returned as a {@code Key}.
     *
     * This method may be called multiple times, depending on if the algorithm
     * and provider supports it.  Each call will build a {@code Key} object
     * in accordance with the next {@code DerivationParameterSpec} in the
     * {@code deriveParams} list provided at initialization time.
     *
     * @return a {@code Key} object corresponding to a key built from
     *      the KDF output and according to the derivation parameters.
     *
     * @throws InvalidParameterSpecException if the information contained
     *      within the {@code DerivationParameterSpec} is invalid or incorrect
     *      for the type of key to be derived, or specifies a type of output
     *      that is not a key (e.g. raw data)
     * @throws IllegalStateException if the key derivation implementation
     *      cannot support additional calls to {@code deriveKey} or if all
     *      {@code DerivationParameterSpec} objects provided at initialization
     *      have been processed.
     */
    public Key deriveKey() throws InvalidParameterSpecException;

    /**
     * Derive one or more {@code Key} objects.
     *
     * This method may be called multiple times, depending on if the algorithm
     * and provider supports it.  A single call will derive and return multiple
     * {@code Key} objects.  A {@code Key} will be returned for each
     * {@code DerivationParameterSpec} provided at initialization until either a
     * {@code DerivationParameterSpec} requesting output in another format
     * (e.g. raw data) is to be processed or the end of the
     * {@code deriveParams} list is reached.
     *
     * @return an unmodifiable {@code List} consisting of one or more
     *      {@code Key} objects, in the same order as the requested
     *      keys in the {@code deriveParams} parameter.
     *
     * @throws InvalidParameterSpecException if the information contained
     *      within any of the {@code DerivationParameterSpec} objects is
     *      incorrect for the derived key type.
     * @throws IllegalStateException if the key derivation implementation
     *      cannot support additional calls to {@code deriveKey} after the
     *      first.  This exception will also be thrown if the next unprocessed
     *      {@code DerivationParameterSpec} is of a non-key output type.
     */
    public List<Key> deriveKeys() throws InvalidParameterSpecException;

    /**
     * Derive a specified number of {@code Key} objects.
     *
     * This method may be called multiple times, depending on if the algorithm
     * and provider supports it.  A single call will derive and return multiple
     * {@code Key} objects.  A {@code Key} will be returned for each
     * {@code DerivationParameterSpec} provided at initialization until:
     *
     * <UL>
     * <li> The number of requested key objects in the {@code num} parameter
     * have been derived.
     * <li> A {@code DerivationParameterSpec} requesting output in another
     * format (e.g. raw data) is to be processed.
     * <li> The end of the {@code deriveParams} list is reached.
     * </UL>
     *
     * @param num the number of requested keys to be returned
     *
     * @return an unmodifiable {@code List} consisting of one or more
     *      {@code Key} objects, in the same order as the requested
     *      keys in the {@code deriveParams} parameter.  Depending on the
     *      number, type and ordering of the {@code DerivationParameterSpec}
     *      objects in the {@code deriveParams} list, the returned list may
     *      have fewer {@code Key} objects than were requested.
     *
     * @throws InvalidParameterSpecException if the information contained
     *      within any of the {@code DerivationParameterSpec} objects is
     *      incorrect for the derived key type.
     * @throws IllegalStateException if the key derivation implementation
     *      cannot support additional calls to {@code deriveKey} after the
     *      first.  This exception will also be thrown if the next unprocessed
     *      {@code DerivationParameterSpec} is of a non-key output type.
     */
    public List<Key> deriveKeys(int num) throws InvalidParameterSpecException;

    /**
     * Obtain raw data from a key derivation function.
     *
     * This method may be called multiple times, depending on if the algorithm
     * and provider supports it.  A single call will return a byte array
     * containing the number of bytes as requested in the corresponding
     * {@code DerivationParameterSpec} length field.
     *
     * For this method to succeed, the current {@code DerivationParameterSpec}
     * must be set as a "data" output type.  Attempting to call this method
     * using  {@code DerivationParameterSpec} objects of any other type will
     * cause an {@code InvalidParameterSpecException} to be thrown.
     *
     * @return a byte array whose length matches the length field in the
     * processed {@code DerivationParameterSpec} and containing the next
     * bytes of output from the key derivation function.
     *
     * @throws InvalidParameterSpecException if the
     *      {@code DerivationParameterSpec} being applied to this method is
     *      of a type other than "data".
     * @throws IllegalStateException if the key derivation implementation
     *      cannot support additional calls to {@code deriveData} or if
     *      all {@code DerivationParameterSpec} objects have been processed.
     */
    public byte[] deriveData() throws InvalidParameterSpecException;

    /**
     * Obtain an Object built from key derivation material.
     *
     * This method may be called multiple times, depending on if the algorithm
     * and provider supports it.  A single call will return an {@code Object}
     * that is built from the key derivation output.  Objects must be specified
     * by their {@code Class} and must have a constructor with the following
     * signature:
     * <pre>
     * {@code ClassName(byte[] data, int length);}
     * </pre>
     *
     * For this method to succeed, the current {@code DerivationParameterSpec}
     * must be created with the {@code Class} form of the constructor.
     * Attempting to call this method
     * using {@code DerivationParameterSpec} objects of any other type will
     * cause an {@code InvalidParameterSpecException} to be thrown.
     *
     * @return an Object built from the key derivation output.  The number of
     * bytes used to build the Object is determined by the {@code length}
     * field in the {@code DerivationParameterSpec}.
     *
     * @throws InvalidParameterSpecException if the
     *      {@code DerivationParameterSpec} being applied to this method
     *      was not designed to output an Object.
     * @throws IllegalStateException if the key derivation implementation
     *      cannot support additional calls to {@code deriveObject} or if
     *      all {@code DerivationParameterSpec} objects have been processed.
     */
    public Object deriveObject() throws InvalidParameterSpecException;

}


javax.crypto.KeyDerivationSpi
=============================

/**
 * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)
 * for the <code>KeyDerivation</code> class.
 *
 * All the abstract methods in this class must be implemented by each
 * cryptographic service provider who wishes to supply the implementation
 * of a particular key derivation algorithm.
 */

public abstract class  KeyDerivationSpi {

    /**
     * Initializes the key derivation object with a secret
     * key and algorithm parameters.
     *
     * @param secretKey the input keying material
     * @param kdfParams the parameters for the key derivation function
     * @param deriveParams a {@code List} of one or more
     *        {@code DerivationParameterSpec} objects detailing the
     *        characteristics for the output keys, data, and/or objects from
     *        this key derivation function.
     *
     * @throws InvalidKeyException if the given key is inappropriate for
     * initializing this key derivation algorithm.
     * @throws InvalidParameterSpecException if the given algorithm
     * parameters or derivation parameters are inappropriate for this key
     * derivation algorithm.
     */
    protected abstract void engineInit(SecretKey secretKey,
            AlgorithmParameterSpec kdfParams,
            List<DerivationParameterSpec> deriveParams)
            throws InvalidKeyException, InvalidParameterSpecException;

    /**
     * Derive a key, returned as a {@code Key}.
     *
     * This method may be called multiple times, depending on if the algorithm
     * and provider supports it.  Each call will build a {@code Key} object
     * in accordance with the next {@code DerivationParameterSpec} in the
     * {@code deriveParams} list provided at initialization time.
     *
     * @return a {@code Key} object corresponding to a key built from
     *      the KDF output and according to the derivation parameters.
     *
     * @throws InvalidParameterSpecException if the information contained
     *      within the {@code DerivationParameterSpec} is invalid or incorrect
     *      for the type of key to be derived, or specifies a type of output
     *      that is not a key (e.g. raw data)
     * @throws IllegalStateException if the key derivation implementation
     *      cannot support additional calls to {@code deriveKey} or if all
     *      {@code DerivationParameterSpec} objects provided at initialization
     *      have been processed.
     */
    protected abstract Key engineDeriveKey()
            throws InvalidParameterSpecException;

    /**
     * Derive one or more {@code Key} objects using a specified
     * algorithm and parameters.
     *
     * @return a {@code List} of {@code Key} objects containing key
     *      material derived from the {@code KeyDerivation} implementation.
     *      Returned {@code Key} objects will be in the same order
     *      as their matching {@code DerivationParameterSpec} objects during
     *      initialization.  This method will return as many keys as possible
     *      until a non-key {@code DerivationParameterSpec} is reached or
     *      all {@code DerivationParameterSpec} objects have been processed.
     *
     * @throws InvalidParameterSpecException if the given key-specific
     *      parameters are inappropriate for this derived key type.
     * @throws IllegalStateException if the key derivation implementation
     *      cannot support additional calls to {@code deriveKey} after the
     *      first.
     * @throws NullPointerException if either {@code params} is null, or any
     *      entry in the {@code params} list is null
     */
    protected abstract List<Key> engineDeriveKeys()
            throws InvalidParameterSpecException;

    /**
     * Derive a specified number of {@code Key} objects.
     *
     * This method may be called multiple times, depending on if the algorithm
     * and provider supports it.  A single call will derive and return multiple
     * {@code Key} objects.  A {@code Key} will be returned for each
     * {@code DerivationParameterSpec} provided at initialization until:
     *
     * <UL>
     * <li> The number of requested key objects in the {@code num} parameter
     * have been derived.
     * <li> A {@code DerivationParameterSpec} requesting output in another
     * format (e.g. raw data) is to be processed.
     * <li> The end of the {@code deriveParams} list is reached.
     * </UL>
     *
     * @param num the number of requested keys to be returned
     *
     * @return an unmodifiable {@code List} consisting of one or more
     *      {@code Key} objects, in the same order as the requested
     *      keys in the {@code deriveParams} parameter.  Depending on the
     *      number, type and ordering of the {@code DerivationParameterSpec}
     *      objects in the {@code deriveParams} list, the returned list may
     *      have fewer {@code Key} objects than were requested.
     *
     * @throws InvalidParameterSpecException if the information contained
     *      within any of the {@code DerivationParameterSpec} objects is
     *      incorrect for the derived key type.
     * @throws IllegalStateException if the key derivation implementation
     *      cannot support additional calls to {@code deriveKey} after the
     *      first.  This exception will also be thrown if the next unprocessed
     *      {@code DerivationParameterSpec} is of a non-key output type.
     */
    protected abstract List<Key> engineDeriveKeys(int num)
            throws InvalidParameterSpecException;

    /**
     * Obtain raw data from a key derivation function.
     *
     * This method may be called multiple times, depending on if the algorithm
     * and provider supports it.  A single call will return a byte array
     * containing the number of bytes as requested in the corresponding
     * {@code DerivationParameterSpec} length field.
     *
     * For this method to succeed, the current {@code DerivationParameterSpec}
     * must be set as a "data" output type.  Attempting to call this method
     * using  {@code DerivationParameterSpec} objects of any other type will
     * cause an {@code InvalidParameterSpecException} to be thrown.
     *
     * @return a byte array whose length matches the length field in the
     * processed {@code DerivationParameterSpec} and containing the next
     * bytes of output from the key derivation function.
     *
     * @throws InvalidParameterSpecException if the
     *      {@code DerivationParameterSpec} being applied to this method is
     *      of a type other than "data".
     * @throws IllegalStateException if the key derivation implementation
     *      cannot support additional calls to {@code deriveData} or if
     *      all {@code DerivationParameterSpec} objects have been processed.
     */
    protected abstract byte[] engineDeriveData()
            throws InvalidParameterSpecException;

    /**
     * Obtain an Object built from key derivation material.
     *
     * This method may be called multiple times, depending on if the algorithm
     * and provider supports it.  A single call will return an {@code Object}
     * that is built from the key derivation output.  Objects must be specified
     * by their {@code Class} and must have a constructor with the following
     * signature:
     * <pre>
     * {@code ClassName(byte[] data, int length);}
     * </pre>
     *
     * For this method to succeed, the current {@code DerivationParameterSpec}
     * must be created with the {@code Class} form of the constructor.
     * Attempting to call this method
     * using {@code DerivationParameterSpec} objects of any other type will
     * cause an {@code InvalidParameterSpecException} to be thrown.
     *
     * @return an Object built from the key derivation output.  The number of
     * bytes used to build the Object is determined by the {@code length}
     * field in the {@code DerivationParameterSpec}.
     *
     * @throws InvalidParameterSpecException if the
     *      {@code DerivationParameterSpec} being applied to this method
     *      was not designed to output an Object.
     * @throws IllegalStateException if the key derivation implementation
     *      cannot support additional calls to {@code deriveObject} or if
     *      all {@code DerivationParameterSpec} objects have been processed.
     */
    protected abstract Object engineDeriveObject()
            throws InvalidParameterSpecException;

}


java.security.spec.DerivationParameterSpec
==========================================

/**
 * A specification of cryptographic parameters for keys derived from a
 * Key Derivation Function (KDF).  Key properties like algorithm name and
 * key length, as well as provider-specific properties can be specified
 * through this class.  These can then be provided to {@code KeyDerivation}
 * objects through the {@code deriveKey} and {@code deriveKeys} methods.
 */

public class DerivationParameterSpec {

    /**
     * Create a {@code DerivationParameterSpec} that has no key or
     * provider-specific parameters.
     *
     * @param algorithm the algorithm assigned to the resulting key.
     * @param length the length of the key in bytes.
     *
     * @throws IllegalArgumentException if the {@code algorithm} parameter
     * is {@code null} or the {@code length} parameter is not a positive
     * integer.
     */
    public DerivationParameterSpec(String algorithm, int length);

    /**
     * Create a {@code DerivationParameterSpec} that has additional
     * key or provider-specific parameters.
     *
     * @param algorithm the algorithm assigned to the resulting key.
     * @param length the length of the key in bytes.
     * @param params an {@code AlgorithmParameterSpec} implementation
     * containing parameters specific to the key being derived.  This parameter
     * may be {@code null}.
     *
     * @throws NullPointerException if the {@code algorithm} parameter
     * is {@code null}.
     * @throws IllegalArgumentException if the {@code length} parameter is
     * not a positive integer.
     */
    public DerivationParameterSpec(String algorithm, int length,
            AlgorithmParameterSpec params);

    /**
     * Create a {@code DerivationParameterSpec} designed to return an object
     * when used with the {@code KeyDerivation.deriveObject} method.
     *
     * For a class to be successfully used with the {@code deriveObject} method
     * the class must have a constructor of the form:
     *
     * <pre>
     * {@code ClassName(byte[] data, int length);}
     * </pre>
     *
     * @param clazz the desired return type from the derivation
     * @param length the amount of data from the KDF used to instantiate this
     * object.
     * @param params an {@code AlgorithmParameterSpec} implementation
     * containing additional parameters specific to the object being derived.
     * This parameter may be {@code null}.
     */
    public DerivationParameterSpec(Class<?> clazz, int length,
            AlgorithmParameterSpec params)

    /**
     * Returns the algorithm name for this {@code DerivationParameterSpec}.
     *
     * @return the algorithm name or an empty string if the {@code Class}
     * form of the constructor is used.
     */
    public String getAlgorithm();

    /**
     * Obtains the length in bytes for this {@code DerivationParameterSpec}.
     *
     * @return the length in bytes.
     */
    public int getLength();

    /**
     * Returns the desired output class from a {@code deriveObject} call.
     *
     * @return the {@code Class} of the desired return type or {@code null}
     * if this {@code DerivationParameterSpec} was created using a
     * constructor that does not specify the class.
     */
    public Class getOutputClass();

    /**
     * Retrieve any parameters specific to the key being derived.
     *
     * @return an {@code AlgorithmParameterSpec} if one was provided during
     * construction of this object, otherwise {@code null}.
     */
    public AlgorithmParameterSpec getParameterSpec();

}