8187443: Forest Consolidation: Move files to unified layout

Reviewed-by: darcy, ihse

src/java.base/share/classes/java/security/SecureRandomSpi.java

@@ -0,0 +1,219 @@
+/*
+ * Copyright (c) 1998, 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 java.security;
+
+/**
+ * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)
+ * for the {@link SecureRandom} class.
+ * <p>
+ * All the abstract methods in this class must be implemented by each
+ * service provider who wishes to supply the implementation
+ * of a cryptographically strong pseudo-random number generator.
+ *
+ * @implSpec
+ * If the {@link #SecureRandomSpi(SecureRandomParameters)}
+ * constructor is overridden in an implementation, it will always be called
+ * whenever a {@code SecureRandom} is instantiated. Precisely, if an object is
+ * instantiated with one of {@code SecureRandom}'s {@code getInstance} methods
+ * <em>without</em> a {@link SecureRandomParameters} parameter,
+ * the constructor will be called with a {@code null} argument and the
+ * implementation is responsible for creating its own
+ * {@code SecureRandomParameters} parameter for use when
+ * {@link #engineGetParameters()} is called. If an object
+ * is instantiated with one of {@code SecureRandom}'s {@code getInstance}
+ * methods <em>with</em> a {@code SecureRandomParameters} argument,
+ * the constructor will be called with that argument. The
+ * {@link #engineGetParameters()} method must not return {@code null}.
+ * <p>
+ * Otherwise, if the {@code SecureRandomSpi(SecureRandomParameters)}
+ * constructor is not overridden in an implementation, the
+ * {@link #SecureRandomSpi()} constructor must be overridden and it will be
+ * called if an object is instantiated with one of {@code SecureRandom}'s
+ * {@code getInstance} methods <em>without</em> a
+ * {@code SecureRandomParameters} argument. Calling one of
+ * {@code SecureRandom}'s {@code getInstance} methods <em>with</em>
+ * a {@code SecureRandomParameters} argument will never
+ * return an instance of this implementation. The
+ * {@link #engineGetParameters()} method must return {@code null}.
+ * <p>
+ * See {@link SecureRandom} for additional details on thread safety. By
+ * default, a {@code SecureRandomSpi} implementation is considered to be
+ * not safe for use by multiple concurrent threads and {@code SecureRandom}
+ * will synchronize access to each of the applicable engine methods
+ * (see {@link SecureRandom} for the list of methods). However, if a
+ * {@code SecureRandomSpi} implementation is thread-safe, the <a href=
+ * "{@docRoot}/../specs/security/standard-names.html#service-attributes">
+ * service provider attribute</a> "ThreadSafe" should be set to "true" during
+ * its registration, as follows:
+ * <blockquote><pre>
+ * put("SecureRandom.AlgName ThreadSafe", "true");</pre>
+ * </blockquote>
+ * or
+ * <blockquote><pre>
+ * putService(new Service(this, "SecureRandom", "AlgName", className,
+ *          null, Map.of("ThreadSafe", "true")));</pre>
+ * </blockquote>
+ * {@code SecureRandom} will call the applicable engine methods
+ * without any synchronization.
+ *
+ * @since 1.2
+ */
+
+public abstract class SecureRandomSpi implements java.io.Serializable {
+
+    private static final long serialVersionUID = -2991854161009191830L;
+
+    /**
+     * Constructor without a parameter.
+     */
+    public SecureRandomSpi() {
+        // ignored
+    }
+
+    /**
+     * Constructor with a parameter.
+     *
+     * @param params the {@link SecureRandomParameters} object.
+     *               This argument can be {@code null}.
+     * @throws IllegalArgumentException if {@code params} is
+     *         unrecognizable or unsupported by this {@code SecureRandom}
+     *
+     * @since 9
+     */
+    protected SecureRandomSpi(SecureRandomParameters params) {
+        // ignored
+    }
+
+    /**
+     * Reseeds this random object with the given seed. The seed supplements,
+     * rather than replaces, the existing seed. Thus, repeated calls
+     * are guaranteed never to reduce randomness.
+     *
+     * @param seed the seed.
+     */
+    protected abstract void engineSetSeed(byte[] seed);
+
+    /**
+     * Generates a user-specified number of random bytes.
+     * <p>
+     * Some random number generators can only generate a limited amount
+     * of random bytes per invocation. If the size of {@code bytes}
+     * is greater than this limit, the implementation should invoke
+     * its generation process multiple times to completely fill the
+     * buffer before returning from this method.
+     *
+     * @param bytes the array to be filled in with random bytes.
+     */
+    protected abstract void engineNextBytes(byte[] bytes);
+
+    /**
+     * Generates a user-specified number of random bytes with
+     * additional parameters.
+     * <p>
+     * Some random number generators can only generate a limited amount
+     * of random bytes per invocation. If the size of {@code bytes}
+     * is greater than this limit, the implementation should invoke
+     * its generation process multiple times to completely fill the
+     * buffer before returning from this method.
+     *
+     * @implSpec The default implementation throws
+     * an {@link UnsupportedOperationException}.
+     *
+     * @param bytes the array to be filled in with random bytes
+     * @param params additional parameters
+     * @throws UnsupportedOperationException if the implementation
+     *         has not overridden this method
+     * @throws IllegalArgumentException if {@code params} is {@code null},
+     *         illegal or unsupported by this {@code SecureRandom}
+     *
+     * @since 9
+     */
+    protected void engineNextBytes(
+            byte[] bytes, SecureRandomParameters params) {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * Returns the given number of seed bytes.  This call may be used to
+     * seed other random number generators.
+     *
+     * @param numBytes the number of seed bytes to generate.
+     *
+     * @return the seed bytes.
+     */
+    protected abstract byte[] engineGenerateSeed(int numBytes);
+
+    /**
+     * Reseeds this random object with entropy input read from its
+     * entropy source with additional parameters.
+     * <p>
+     * If this method is called by {@link SecureRandom#reseed()},
+     * {@code params} will be {@code null}.
+     * <p>
+     * Do not override this method if the implementation does not
+     * support reseeding.
+     *
+     * @implSpec The default implementation throws
+     *           an {@link UnsupportedOperationException}.
+     *
+     * @param params extra parameters, can be {@code null}.
+     * @throws UnsupportedOperationException if the implementation
+     *         has not overridden this method
+     * @throws IllegalArgumentException if {@code params} is
+     *         illegal or unsupported by this {@code SecureRandom}
+     *
+     * @since 9
+     */
+    protected void engineReseed(SecureRandomParameters params) {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * Returns the effective {@link SecureRandomParameters} for this
+     * {@code SecureRandom} instance.
+     *
+     * @implSpec The default implementation returns {@code null}.
+     *
+     * @return the effective {@link SecureRandomParameters} parameters,
+     * or {@code null} if no parameters were used.
+     *
+     * @since 9
+     */
+    protected SecureRandomParameters engineGetParameters() {
+        return null;
+    }
+
+    /**
+     * Returns a Human-readable string representation of this
+     * {@code SecureRandom}.
+     *
+     * @return the string representation
+     */
+    @Override
+    public String toString() {
+        return getClass().getSimpleName();
+    }
+}