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