2  * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.

     2  * Copyright (c) 1998, 2016, Oracle and/or its affiliates. All rights reserved.

    30  * for the {@code SecureRandom} class.

    30  * for the {@link SecureRandom} class.

    31  * <p>

    35  *

    36  * @implSpec

    36  * @see SecureRandom

    37  * If the {@link #SecureRandomSpi(SecureRandomParameters)}

    38  * constructor is overridden in an implementation, it will always be called

    39  * whenever a {@code SecureRandom} is instantiated. Precisely, if an object is

    40  * instantiated with one of {@code SecureRandom}'s {@code getInstance} methods

    41  * <em>without</em> a {@link SecureRandomParameters} parameter,

    42  * the constructor will be called with a {@code null} argument and the

    43  * implementation is responsible for creating its own

    44  * {@code SecureRandomParameters} parameter for use when

    45  * {@link #engineGetParameters()} is called. If an object

    46  * is instantiated with one of {@code SecureRandom}'s {@code getInstance}

    47  * methods <em>with</em> a {@code SecureRandomParameters} argument,

    48  * the constructor will be called with that argument. The

    49  * {@link #engineGetParameters()} method must not return {@code null}.

    50  * <p>

    51  * Otherwise, if the {@code SecureRandomSpi(SecureRandomParameters)}

    52  * constructor is not overridden in an implementation, the

    53  * {@link #SecureRandomSpi()} constructor must be overridden and it will be

    54  * called if an object is instantiated with one of {@code SecureRandom}'s

    55  * {@code getInstance} methods <em>without</em> a

    56  * {@code SecureRandomParameters} argument. Calling one of

    57  * {@code SecureRandom}'s {@code getInstance} methods <em>with</em>

    58  * a {@code SecureRandomParameters} argument will never

    59  * return an instance of this implementation. The

    60  * {@link #engineGetParameters()} method must return {@code null}.

    61  *

    45      * Reseeds this random object. The given seed supplements, rather than

    70      * Constructor without a parameter.

    46      * replaces, the existing seed. Thus, repeated calls are guaranteed

    71      */

    47      * never to reduce randomness.

    72     public SecureRandomSpi() {

    73         // ignored

    74     }

    75 

    76     /**

    77      * Constructor with a parameter.

    78      *

    79      * @param params the {@link SecureRandomParameters} object.

    80      *               This argument can be {@code null}.

    81      * @throws IllegalArgumentException if {@code params} is

    82      *         unrecognizable or unsupported by this {@code SecureRandom}

    83      *

    84      * @since 9

    85      */

    86     protected SecureRandomSpi(SecureRandomParameters params) {

    87         // ignored

    88     }

    89 

    90     /**

    91      * Reseeds this random object with the given seed. The seed supplements,

    92      * rather than replaces, the existing seed. Thus, repeated calls

    93      * are guaranteed never to reduce randomness.

    55      *

   101      * <p>

    56      * <p> If a call to {@code engineSetSeed} had not occurred previously,

   102      * Some random number generators can only generate a limited amount

    57      * the first call to this method forces this SecureRandom implementation

   103      * of random bytes per invocation. If the size of {@code bytes}

    58      * to seed itself.  This self-seeding will not occur if

   104      * is greater than this limit, the implementation should invoke

    59      * {@code engineSetSeed} was previously called.

   105      * its generation process multiple times to completely fill the

   106      * buffer before returning from this method.

    73      protected abstract byte[] engineGenerateSeed(int numBytes);

   147     protected abstract byte[] engineGenerateSeed(int numBytes);

   148 

   149     /**

   150      * Reseeds this random object with entropy input read from its

   151      * entropy source with additional parameters.

   152      * <p>

   153      * If this method is called by {@link SecureRandom#reseed()},

   154      * {@code params} will be {@code null}.

   155      * <p>

   156      * Do not override this method if the implementation does not

   157      * support reseeding.

   158      *

   159      * @implSpec The default implementation throws

   160      *           an {@link UnsupportedOperationException}.

   161      *

   162      * @param params extra parameters, can be {@code null}.

   163      * @throws UnsupportedOperationException if the implementation

   164      *         has not overridden this method

   165      * @throws IllegalArgumentException if {@code params} is

   166      *         illegal or unsupported by this {@code SecureRandom}

   167      *

   168      * @since 9

   169      */

   170     protected void engineReseed(SecureRandomParameters params) {

   171         throw new UnsupportedOperationException();

   172     }

   173 

   174     /**

   175      * Returns the effective {@link SecureRandomParameters} for this

   176      * {@code SecureRandom} instance.

   177      *

   178      * @implSpec The default implementation returns {@code null}.

   179      *

   180      * @return the effective {@link SecureRandomParameters} parameters,

   181      * or {@code null} if no parameters were used.

   182      *

   183      * @since 9

   184      */

   185     protected SecureRandomParameters engineGetParameters() {

   186         return null;

   187     }

   188 

   189     /**

   190      * Returns a Human-readable string representation of this

   191      * {@code SecureRandom}.

   192      *

   193      * @return the string representation

   194      *

   195      * @since 9

   196      */

   197     @Override

   198     public String toString() {

   199         return getClass().getSimpleName();

   200     }