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 and initialized
 * through the {@code getInstance} family of methods.  Any algorithm parameters,
 * including secret values must be provided through those methods.
 *
 * 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 {

    /**
     * Creates an instance of the {@code KeyDerivation} object.
     *
     * @param algorithm the key derivation algorithm to use
     * @param params parameters used to initialize the algorithm selected
     *
     * @return a {@code KeyDerivation} object
     *
     * @throws NoSuchAlgorithmException if no {@code Provider} supports a
     *         {@code KeyDerivationSpi} implementation for the
     *         specified algorithm.
     * @throws InvalidParameterSpecException if the
     *         {@code AlgorithmParameterSpec} passed in contains invalid
     *         data or is an incorrect type for the selected algorithm.
     */
    public static final KeyDerivation getInstance(String algorithm,
            AlgorithmParameterSpec params)
            throws NoSuchAlgorithmException, InvalidParameterSpecException;

    /**
     * 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
     * @param params parameters used to initialize the algorithm selected
     *
     * @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.
     * @throws InvalidParameterSpecException if the
     *         {@code AlgorithmParameterSpec} passed in contains invalid
     *         data or is an incorrect type for the selected algorithm.
     */
    public static final KeyDerivation getInstance(String algorithm,
            String provider, AlgorithmParameterSpec params)
            throws NoSuchAlgorithmException, NoSuchProviderException,
            InvalidParameterSpecException;

    /**
     * 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
     * @param params parameters used to initialize the algorithm selected
     *
     * @return a {@code KeyDerivation} object
     *
     * @throws NoSuchAlgorithmException if no {@code Provider} supports a
     *         {@code KeyDerivationSpi} implementation for the
     *         specified algorithm.
     * @throws InvalidParameterSpecException if the
     *         {@code AlgorithmParameterSpec} passed in contains invalid
     *         data or is an incorrect type for the selected algorithm.
     */
    public static final KeyDerivation getInstance(String algorithm,
            Provider provider, AlgorithmParameterSpec params)
            throws NoSuchAlgorithmException, InvalidParameterSpecException;

    /**
     * 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();

    /**
     * Derive a key, returned as a {@code SecretKey}.
     *
     * This method may be called multiple times, depending on if the algorithm
     * and provider supports it.  Subsequent calls after the first will return
     * key objects with values as if all keys were generated together using
     * the {@code deriveKeys} method.  Those algorithms or providers not
     * supporting multiple output keys from a single set of inputs will
     * throw {@code IllegalStateException} after the first call successfully
     * returns.
     *
     * @param params any algorithm parameters specific to the key being
     *      derived, if required
     *
     * @return a {@code SecretKey} containing the key
     *
     * @throws InvalidParameterSpecException if the information contained
     *      within the {@code DerivedKeyParameterSpec} is invalid or incorrect
     *      for the type of key to be derived.
     * @throws IllegalStateException if the key derivation implementation
     *      cannot support additional calls to {@code deriveKey} after the
     *      first.
     * @throws NullPointerException if the {@code params} parameters are
     *      {@code null}.
     */
    public SecretKey deriveKey(DerivedKeyParameterSpec params)
            throws InvalidParameterSpecException;

    /**
     * Derive one or more {@code SecretKey} objects.
     *
     * This method may be called multiple times, depending on if the algorithm
     * and provider supports it.  Subsequent calls after the first will return
     * additional key objects with values as if the key derivation function
     * resumed generation of key material from its last known state.  Those
     * algorithms or providers not supporting multiple {@code deriveKeys} calls
     * from a single set of inputs will throw {@code IllegalStateException}
     * after the first call successfully returns.
     *
     * @param params a {@code List} of {@code DerivedKeyParameterSpec} objects,
     *      in the desired order the caller wishes the keys to be returned.
     *
     * @return an unmodifiable {@code List} consisting of one or more
     *      {@code SecretKey} objects, in the same order as the requested
     *      objects in the {@code params} parameter.
     *
     * @throws InvalidParameterSpecException if the information contained
     *      within any of the {@code DerivedKeyParameterSpec} 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.
     * @throws NullPointerException if the {@code params} field is null
     *      or any elements within are {@code null}.
     */
    public List<SecretKey> deriveKeys(List<DerivedKeyParameterSpec> params)
            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 params the algorithm parameters
     *
     * @throws InvalidKeyException if the given key is inappropriate for
     * initializing this key derivation algorithm.
     * @throws InvalidParameterSpecException if the given algorithm
     * parameters are inappropriate for this key derivation algorithm.
     */
    protected abstract void engineInit(AlgorithmParameterSpec params)
            throws InvalidKeyException, InvalidParameterSpecException;

    /**
     * Derive one or more {@code SecretKey} objects using a specified
     * algorithm and parameters.
     *
     * @param params a {@code List} of key-specific parameters.  There should
     *      be one {@code DerivedKeyParameterSpec} object in the list for
     *      each secret key to be derived by the selected KDF implementation.
     *
     * @return a {@code List} of {@code SecretKey} objects containing key
     *      material derived from the {@code KeyDerivation} implementation.
     *      Returned {@code SecretKey} objects will be in the same order
     *      as their matching {@code DerivedKeyParameterSpec} objects in the
     *      {@code params} parameter.
     *
     * @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<SecretKey> engineDeriveKeys(
            List<DerivedKeyParameterSpec> params)
            throws InvalidParameterSpecException;
}


java.security.spec.DerivedKeyParameterSpec
==========================================

/**
 * 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 DerivedKeyParameterSpec {

    /**
     * Create a {@code DerivedKeyParameterSpec} 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 DerivedKeyParameterSpec(String algorithm, int length);

    /**
     * Create a {@code DerivedKeyParameterSpec} 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.
     *
     * @throws NullPointerException if the {@code algorithm} parameter
     * is {@code null}.
     * @throws IllegalArgumentException if the {@code length} parameter is
     * not a positive integer.
     */
    public DerivedKeyParameterSpec(String algorithm, int length,
            AlgorithmParameterSpec params);

    /**
     * Returns the algorithm name for this {@code DerivedKeyParameterSpec}.
     *
     * @return the algorithm name.
     */
    public String getAlgorithm();

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

    /**
     * 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();

}