8187443: Forest Consolidation: Move files to unified layout

Reviewed-by: darcy, ihse

src/java.base/share/classes/javax/crypto/KeyGenerator.java

@@ -0,0 +1,579 @@
+/*
+ * Copyright (c) 1997, 2017, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package javax.crypto;
+
+import java.util.*;
+
+import java.security.*;
+import java.security.Provider.Service;
+import java.security.spec.*;
+
+import sun.security.jca.*;
+import sun.security.jca.GetInstance.Instance;
+import sun.security.util.Debug;
+
+/**
+ * This class provides the functionality of a secret (symmetric) key generator.
+ *
+ * <p>Key generators are constructed using one of the {@code getInstance}
+ * class methods of this class.
+ *
+ * <p>KeyGenerator objects are reusable, i.e., after a key has been
+ * generated, the same KeyGenerator object can be re-used to generate further
+ * keys.
+ *
+ * <p>There are two ways to generate a key: in an algorithm-independent
+ * manner, and in an algorithm-specific manner.
+ * The only difference between the two is the initialization of the object:
+ *
+ * <ul>
+ * <li><b>Algorithm-Independent Initialization</b>
+ * <p>All key generators share the concepts of a <i>keysize</i> and a
+ * <i>source of randomness</i>.
+ * There is an
+ * {@link #init(int, java.security.SecureRandom) init}
+ * method in this KeyGenerator class that takes these two universally
+ * shared types of arguments. There is also one that takes just a
+ * {@code keysize} argument, and uses the SecureRandom implementation
+ * of the highest-priority installed provider as the source of randomness
+ * (or a system-provided source of randomness if none of the installed
+ * providers supply a SecureRandom implementation), and one that takes just a
+ * source of randomness.
+ *
+ * <p>Since no other parameters are specified when you call the above
+ * algorithm-independent {@code init} methods, it is up to the
+ * provider what to do about the algorithm-specific parameters (if any) to be
+ * associated with each of the keys.
+ *
+ * <li><b>Algorithm-Specific Initialization</b>
+ * <p>For situations where a set of algorithm-specific parameters already
+ * exists, there are two
+ * {@link #init(java.security.spec.AlgorithmParameterSpec) init}
+ * methods that have an {@code AlgorithmParameterSpec}
+ * argument. One also has a {@code SecureRandom} argument, while the
+ * other uses the SecureRandom implementation
+ * of the highest-priority installed provider as the source of randomness
+ * (or a system-provided source of randomness if none of the installed
+ * providers supply a SecureRandom implementation).
+ * </ul>
+ *
+ * <p>In case the client does not explicitly initialize the KeyGenerator
+ * (via a call to an {@code init} method), each provider must
+ * supply (and document) a default initialization.
+ * See the Keysize Restriction sections of the
+ * {@extLink security_guide_jdk_providers JDK Providers}
+ * document for information on the KeyGenerator defaults used by
+ * JDK providers.
+ * However, note that defaults may vary across different providers.
+ * Additionally, the default value for a provider may change in a future
+ * version. Therefore, it is recommended to explicitly initialize the
+ * KeyGenerator instead of relying on provider-specific defaults.
+ *
+ * <p> Every implementation of the Java platform is required to support the
+ * following standard {@code KeyGenerator} algorithms with the keysizes in
+ * parentheses:
+ * <ul>
+ * <li>{@code AES} (128)</li>
+ * <li>{@code DES} (56)</li>
+ * <li>{@code DESede} (168)</li>
+ * <li>{@code HmacSHA1}</li>
+ * <li>{@code HmacSHA256}</li>
+ * </ul>
+ * These algorithms are described in the <a href=
+ * "{@docRoot}/../specs/security/standard-names.html#keygenerator-algorithms">
+ * KeyGenerator section</a> of the
+ * Java Security Standard Algorithm Names Specification.
+ * Consult the release documentation for your implementation to see if any
+ * other algorithms are supported.
+ *
+ * @author Jan Luehe
+ *
+ * @see SecretKey
+ * @since 1.4
+ */
+
+public class KeyGenerator {
+
+    private static final Debug pdebug =
+                        Debug.getInstance("provider", "Provider");
+    private static final boolean skipDebug =
+        Debug.isOn("engine=") && !Debug.isOn("keygenerator");
+
+    // see java.security.KeyPairGenerator for failover notes
+
+    private static final int I_NONE   = 1;
+    private static final int I_RANDOM = 2;
+    private static final int I_PARAMS = 3;
+    private static final int I_SIZE   = 4;
+
+    // The provider
+    private Provider provider;
+
+    // The provider implementation (delegate)
+    private volatile KeyGeneratorSpi spi;
+
+    // The algorithm
+    private final String algorithm;
+
+    private final Object lock = new Object();
+
+    private Iterator<Service> serviceIterator;
+
+    private int initType;
+    private int initKeySize;
+    private AlgorithmParameterSpec initParams;
+    private SecureRandom initRandom;
+
+    /**
+     * Creates a KeyGenerator object.
+     *
+     * @param keyGenSpi the delegate
+     * @param provider the provider
+     * @param algorithm the algorithm
+     */
+    protected KeyGenerator(KeyGeneratorSpi keyGenSpi, Provider provider,
+                           String algorithm) {
+        this.spi = keyGenSpi;
+        this.provider = provider;
+        this.algorithm = algorithm;
+
+        if (!skipDebug && pdebug != null) {
+            pdebug.println("KeyGenerator." + algorithm + " algorithm from: " +
+                getProviderName());
+        }
+    }
+
+    private KeyGenerator(String algorithm) throws NoSuchAlgorithmException {
+        this.algorithm = algorithm;
+        List<Service> list =
+                GetInstance.getServices("KeyGenerator", algorithm);
+        serviceIterator = list.iterator();
+        initType = I_NONE;
+        // fetch and instantiate initial spi
+        if (nextSpi(null, false) == null) {
+            throw new NoSuchAlgorithmException
+                (algorithm + " KeyGenerator not available");
+        }
+
+        if (!skipDebug && pdebug != null) {
+            pdebug.println("KeyGenerator." + algorithm + " algorithm from: " +
+                getProviderName());
+        }
+    }
+
+    private String getProviderName() {
+        return (provider == null) ? "(no provider)" : provider.getName();
+    }
+
+    /**
+     * Returns the algorithm name of this {@code KeyGenerator} object.
+     *
+     * <p>This is the same name that was specified in one of the
+     * {@code getInstance} calls that created this
+     * {@code KeyGenerator} object.
+     *
+     * @return the algorithm name of this {@code KeyGenerator} object.
+     */
+    public final String getAlgorithm() {
+        return this.algorithm;
+    }
+
+    /**
+     * Returns a {@code KeyGenerator} object that generates secret keys
+     * for the specified algorithm.
+     *
+     * <p> This method traverses the list of registered security Providers,
+     * starting with the most preferred Provider.
+     * A new KeyGenerator object encapsulating the
+     * KeyGeneratorSpi implementation from the first
+     * Provider that supports the specified algorithm is returned.
+     *
+     * <p> Note that the list of registered providers may be retrieved via
+     * the {@link Security#getProviders() Security.getProviders()} method.
+     *
+     * @implNote
+     * The JDK Reference Implementation additionally uses the
+     * {@code jdk.security.provider.preferred}
+     * {@link Security#getProperty(String) Security} property to determine
+     * the preferred provider order for the specified algorithm. This
+     * may be different than the order of providers returned by
+     * {@link Security#getProviders() Security.getProviders()}.
+     *
+     * @param algorithm the standard name of the requested key algorithm.
+     * See the KeyGenerator section in the <a href=
+     * "{@docRoot}/../specs/security/standard-names.html#keygenerator-algorithms">
+     * Java Security Standard Algorithm Names Specification</a>
+     * for information about standard algorithm names.
+     *
+     * @return the new {@code KeyGenerator} object
+     *
+     * @throws NoSuchAlgorithmException if no {@code Provider} supports a
+     *         {@code KeyGeneratorSpi} implementation for the
+     *         specified algorithm
+     *
+     * @throws NullPointerException if {@code algorithm} is {@code null}
+     *
+     * @see java.security.Provider
+     */
+    public static final KeyGenerator getInstance(String algorithm)
+            throws NoSuchAlgorithmException {
+        Objects.requireNonNull(algorithm, "null algorithm name");
+        return new KeyGenerator(algorithm);
+    }
+
+    /**
+     * Returns a {@code KeyGenerator} object that generates secret keys
+     * for the specified algorithm.
+     *
+     * <p> A new KeyGenerator object encapsulating the
+     * KeyGeneratorSpi implementation from the specified provider
+     * is returned.  The specified provider must be registered
+     * in the security provider list.
+     *
+     * <p> Note that the list of registered providers may be retrieved via
+     * the {@link Security#getProviders() Security.getProviders()} method.
+     *
+     * @param algorithm the standard name of the requested key algorithm.
+     * See the KeyGenerator section in the <a href=
+     * "{@docRoot}/../specs/security/standard-names.html#keygenerator-algorithms">
+     * Java Security Standard Algorithm Names Specification</a>
+     * for information about standard algorithm names.
+     *
+     * @param provider the name of the provider.
+     *
+     * @return the new {@code KeyGenerator} object
+     *
+     * @throws IllegalArgumentException if the {@code provider}
+     *         is {@code null} or empty
+     *
+     * @throws NoSuchAlgorithmException if a {@code KeyGeneratorSpi}
+     *         implementation for the specified algorithm is not
+     *         available from the specified provider
+     *
+     * @throws NoSuchProviderException if the specified provider is not
+     *         registered in the security provider list
+     *
+     * @throws NullPointerException if {@code algorithm} is {@code null}
+     *
+     * @see java.security.Provider
+     */
+    public static final KeyGenerator getInstance(String algorithm,
+            String provider) throws NoSuchAlgorithmException,
+            NoSuchProviderException {
+        Objects.requireNonNull(algorithm, "null algorithm name");
+        Instance instance = JceSecurity.getInstance("KeyGenerator",
+                KeyGeneratorSpi.class, algorithm, provider);
+        return new KeyGenerator((KeyGeneratorSpi)instance.impl,
+                instance.provider, algorithm);
+    }
+
+    /**
+     * Returns a {@code KeyGenerator} object that generates secret keys
+     * for the specified algorithm.
+     *
+     * <p> A new KeyGenerator object encapsulating the
+     * KeyGeneratorSpi implementation from the specified Provider
+     * object is returned.  Note that the specified Provider object
+     * does not have to be registered in the provider list.
+     *
+     * @param algorithm the standard name of the requested key algorithm.
+     * See the KeyGenerator section in the <a href=
+     * "{@docRoot}/../specs/security/standard-names.html#keygenerator-algorithms">
+     * Java Security Standard Algorithm Names Specification</a>
+     * for information about standard algorithm names.
+     *
+     * @param provider the provider.
+     *
+     * @return the new {@code KeyGenerator} object
+     *
+     * @throws IllegalArgumentException if the {@code provider}
+     *         is {@code null}
+     *
+     * @throws NoSuchAlgorithmException if a {@code KeyGeneratorSpi}
+     *         implementation for the specified algorithm is not available
+     *         from the specified {@code Provider} object
+     *
+     * @throws NullPointerException if {@code algorithm} is {@code null}
+     *
+     * @see java.security.Provider
+     */
+    public static final KeyGenerator getInstance(String algorithm,
+            Provider provider) throws NoSuchAlgorithmException {
+        Objects.requireNonNull(algorithm, "null algorithm name");
+        Instance instance = JceSecurity.getInstance("KeyGenerator",
+                KeyGeneratorSpi.class, algorithm, provider);
+        return new KeyGenerator((KeyGeneratorSpi)instance.impl,
+                instance.provider, algorithm);
+    }
+
+    /**
+     * Returns the provider of this {@code KeyGenerator} object.
+     *
+     * @return the provider of this {@code KeyGenerator} object
+     */
+    public final Provider getProvider() {
+        synchronized (lock) {
+            disableFailover();
+            return provider;
+        }
+    }
+
+    /**
+     * Update the active spi of this class and return the next
+     * implementation for failover. If no more implementations are
+     * available, this method returns null. However, the active spi of
+     * this class is never set to null.
+     */
+    private KeyGeneratorSpi nextSpi(KeyGeneratorSpi oldSpi,
+            boolean reinit) {
+        synchronized (lock) {
+            // somebody else did a failover concurrently
+            // try that spi now
+            if ((oldSpi != null) && (oldSpi != spi)) {
+                return spi;
+            }
+            if (serviceIterator == null) {
+                return null;
+            }
+            while (serviceIterator.hasNext()) {
+                Service s = serviceIterator.next();
+                if (JceSecurity.canUseProvider(s.getProvider()) == false) {
+                    continue;
+                }
+                try {
+                    Object inst = s.newInstance(null);
+                    // ignore non-spis
+                    if (inst instanceof KeyGeneratorSpi == false) {
+                        continue;
+                    }
+                    KeyGeneratorSpi spi = (KeyGeneratorSpi)inst;
+                    if (reinit) {
+                        if (initType == I_SIZE) {
+                            spi.engineInit(initKeySize, initRandom);
+                        } else if (initType == I_PARAMS) {
+                            spi.engineInit(initParams, initRandom);
+                        } else if (initType == I_RANDOM) {
+                            spi.engineInit(initRandom);
+                        } else if (initType != I_NONE) {
+                            throw new AssertionError
+                                ("KeyGenerator initType: " + initType);
+                        }
+                    }
+                    provider = s.getProvider();
+                    this.spi = spi;
+                    return spi;
+                } catch (Exception e) {
+                    // ignore
+                }
+            }
+            disableFailover();
+            return null;
+        }
+    }
+
+    void disableFailover() {
+        serviceIterator = null;
+        initType = 0;
+        initParams = null;
+        initRandom = null;
+    }
+
+    /**
+     * Initializes this key generator.
+     *
+     * @param random the source of randomness for this generator
+     */
+    public final void init(SecureRandom random) {
+        if (serviceIterator == null) {
+            spi.engineInit(random);
+            return;
+        }
+        RuntimeException failure = null;
+        KeyGeneratorSpi mySpi = spi;
+        do {
+            try {
+                mySpi.engineInit(random);
+                initType = I_RANDOM;
+                initKeySize = 0;
+                initParams = null;
+                initRandom = random;
+                return;
+            } catch (RuntimeException e) {
+                if (failure == null) {
+                    failure = e;
+                }
+                mySpi = nextSpi(mySpi, false);
+            }
+        } while (mySpi != null);
+        throw failure;
+    }
+
+    /**
+     * Initializes this key generator with the specified parameter set.
+     *
+     * <p> If this key generator requires any random bytes, it will get them
+     * using the
+     * {@link java.security.SecureRandom}
+     * implementation of the highest-priority installed
+     * provider as the source of randomness.
+     * (If none of the installed providers supply an implementation of
+     * SecureRandom, a system-provided source of randomness will be used.)
+     *
+     * @param params the key generation parameters
+     *
+     * @exception InvalidAlgorithmParameterException if the given parameters
+     * are inappropriate for this key generator
+     */
+    public final void init(AlgorithmParameterSpec params)
+        throws InvalidAlgorithmParameterException
+    {
+        init(params, JceSecurity.RANDOM);
+    }
+
+    /**
+     * Initializes this key generator with the specified parameter
+     * set and a user-provided source of randomness.
+     *
+     * @param params the key generation parameters
+     * @param random the source of randomness for this key generator
+     *
+     * @exception InvalidAlgorithmParameterException if {@code params} is
+     * inappropriate for this key generator
+     */
+    public final void init(AlgorithmParameterSpec params, SecureRandom random)
+        throws InvalidAlgorithmParameterException
+    {
+        if (serviceIterator == null) {
+            spi.engineInit(params, random);
+            return;
+        }
+        Exception failure = null;
+        KeyGeneratorSpi mySpi = spi;
+        do {
+            try {
+                mySpi.engineInit(params, random);
+                initType = I_PARAMS;
+                initKeySize = 0;
+                initParams = params;
+                initRandom = random;
+                return;
+            } catch (Exception e) {
+                if (failure == null) {
+                    failure = e;
+                }
+                mySpi = nextSpi(mySpi, false);
+            }
+        } while (mySpi != null);
+        if (failure instanceof InvalidAlgorithmParameterException) {
+            throw (InvalidAlgorithmParameterException)failure;
+        }
+        if (failure instanceof RuntimeException) {
+            throw (RuntimeException)failure;
+        }
+        throw new InvalidAlgorithmParameterException("init() failed", failure);
+    }
+
+    /**
+     * Initializes this key generator for a certain keysize.
+     *
+     * <p> If this key generator requires any random bytes, it will get them
+     * using the
+     * {@link java.security.SecureRandom}
+     * implementation of the highest-priority installed
+     * provider as the source of randomness.
+     * (If none of the installed providers supply an implementation of
+     * SecureRandom, a system-provided source of randomness will be used.)
+     *
+     * @param keysize the keysize. This is an algorithm-specific metric,
+     * specified in number of bits.
+     *
+     * @exception InvalidParameterException if the keysize is wrong or not
+     * supported.
+     */
+    public final void init(int keysize) {
+        init(keysize, JceSecurity.RANDOM);
+    }
+
+    /**
+     * Initializes this key generator for a certain keysize, using a
+     * user-provided source of randomness.
+     *
+     * @param keysize the keysize. This is an algorithm-specific metric,
+     * specified in number of bits.
+     * @param random the source of randomness for this key generator
+     *
+     * @exception InvalidParameterException if the keysize is wrong or not
+     * supported.
+     */
+    public final void init(int keysize, SecureRandom random) {
+        if (serviceIterator == null) {
+            spi.engineInit(keysize, random);
+            return;
+        }
+        RuntimeException failure = null;
+        KeyGeneratorSpi mySpi = spi;
+        do {
+            try {
+                mySpi.engineInit(keysize, random);
+                initType = I_SIZE;
+                initKeySize = keysize;
+                initParams = null;
+                initRandom = random;
+                return;
+            } catch (RuntimeException e) {
+                if (failure == null) {
+                    failure = e;
+                }
+                mySpi = nextSpi(mySpi, false);
+            }
+        } while (mySpi != null);
+        throw failure;
+    }
+
+    /**
+     * Generates a secret key.
+     *
+     * @return the new key
+     */
+    public final SecretKey generateKey() {
+        if (serviceIterator == null) {
+            return spi.engineGenerateKey();
+        }
+        RuntimeException failure = null;
+        KeyGeneratorSpi mySpi = spi;
+        do {
+            try {
+                return mySpi.engineGenerateKey();
+            } catch (RuntimeException e) {
+                if (failure == null) {
+                    failure = e;
+                }
+                mySpi = nextSpi(mySpi, true);
+            }
+        } while (mySpi != null);
+        throw failure;
+   }
+}