/*

 * Copyright (c) 2016, 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 sun.security.provider;

import sun.security.util.Debug;

import java.security.*;

import java.util.Arrays;

import java.util.Objects;

import static java.security.DrbgParameters.Capability.*;

/**

 * The abstract base class for all DRBGs.

 * <p>

 * This class creates 5 new abstract methods. 3 are defined by the SP800-90A:

 * <ol>

 *  <li>{@link #generateAlgorithm(byte[], byte[])}

 *  <li>{@link #reseedAlgorithm(byte[], byte[])} (might not be supported)

 *  <li>{@link #instantiateAlgorithm(byte[])}

 * </ol>

 * and 2 for implementation purpose:

 * <ol>

 *  <li>{@link #initEngine()}

 *  <li>{@link #chooseAlgorithmAndStrength}

 * </ol>

 * All existing {@link SecureRandomSpi} methods are implemented based on the

 * methods above as final. The initialization process is divided into 2 phases:

 * configuration is eagerly called to set up parameters, and instantiation

 * is lazily called only when nextBytes or reseed is called.

 * <p>

 * Synchronized keyword should be added to all externally callable engine

 * methods including {@link #engineReseed}, {@link #engineSetSeed}, and

 * {@link #engineNextBytes} (but not {@link #engineGenerateSeed}).

 * Internal methods like {@link #configure} and {@link #instantiateAlgorithm}

 * are not synchronized. They will either be called in a constructor or

 * in another synchronized method.

 */

public abstract class AbstractDrbg extends SecureRandomSpi {

    private static final long serialVersionUID = 9L;

    /**

     * This field is not null if {@code -Djava.security.debug=securerandom} is

     * specified on the command line. An implementation can print useful

     * debug info.

     */

    protected static final Debug debug = Debug.getInstance(

            "securerandom", "drbg");

    // Common working status

    private transient boolean instantiated = false;

    /**

     * Reseed counter of a DRBG instance. A mechanism should increment it

     * after each random bits generation and reset it in reseed. A mechanism

     * does <em>not</em> need to compare it to {@link #reseedInterval}.

     */

    protected transient int reseedCounter = 0;

    // Mech features. If not same as below, must be redefined in constructor.

    /**

     * Default strength of a DRBG instance if it is not configured.

     * 128 is considered secure enough now. A mechanism

     * can change it in a constructor.

     *

     * Remember to sync with "securerandom.drbg.config" in java.security.

     */

    protected static final int DEFAULT_STRENGTH = 128;

    /**

     * Mechanism name, say, {@code HashDRBG}. Must be set in constructor.

     * This value will be used in {@code toString}.

     */

    protected String mechName = "DRBG";

    /**

     * highest_supported_security_strength of this mechanism for all algorithms

     * it supports. A mechanism should update the value in its constructor

     * if the value is not 256.

     */

    protected int highestSupportedSecurityStrength = 256;

    /**

     * Whether prediction resistance is supported. A mechanism should update

     * the value in its constructor if it is <em>not</em> supported.

     */

    protected boolean supportPredictionResistance = true;

    /**

     * Whether reseed is supported. A mechanism should update

     * the value in its constructor if it is <em>not</em> supported.

     */

    protected boolean supportReseeding = true;

    // Strength features. If not same as below, must be redefined in

    // chooseAlgorithmAndStrength. Among these, minLength and seedLen have no

    // default value and must be redefined. If personalization string or

    // additional input is not supported, set maxPersonalizationStringLength

    // or maxAdditionalInputLength to -1.

    /**

     * Minimum entropy input length in bytes for this DRBG instance.

     * Must be assigned in {@link #chooseAlgorithmAndStrength}.

     */

    protected int minLength;

    /**

     * Maximum entropy input length in bytes for this DRBG instance.

     * Should be assigned in {@link #chooseAlgorithmAndStrength} if it is not

     * {@link Integer#MAX_VALUE}.

     * <p>

     * In theory this value (and the values below) can be bigger than

     * {@code Integer.MAX_VALUE} but a Java array can only have an int32 index.

     */

    protected int maxLength = Integer.MAX_VALUE;

    /**

     * Maximum personalization string length in bytes for this DRBG instance.

     * Should be assigned in {@link #chooseAlgorithmAndStrength} if it is not

     * {@link Integer#MAX_VALUE}.

     */

    protected int maxPersonalizationStringLength = Integer.MAX_VALUE;

    /**

     * Maximum additional input length in bytes for this DRBG instance.

     * Should be assigned in {@link #chooseAlgorithmAndStrength} if it is not

     * {@link Integer#MAX_VALUE}.

     */

    protected int maxAdditionalInputLength = Integer.MAX_VALUE;

    /**

     * max_number_of_bits_per_request in bytes for this DRBG instance.

     * Should be assigned in {@link #chooseAlgorithmAndStrength} if it is not

     * {@link Integer#MAX_VALUE}.

     */

    protected int maxNumberOfBytesPerRequest = Integer.MAX_VALUE;

    /**

     * Maximum number of requests between reseeds for this DRBG instance.

     * Should be assigned in {@link #chooseAlgorithmAndStrength} if it is not

     * {@link Integer#MAX_VALUE}.

     */

    protected int reseedInterval = Integer.MAX_VALUE;

    /**

     * Algorithm used by this instance (SHA-512 or AES-256). Must be assigned

     * in {@link #chooseAlgorithmAndStrength}. This field is used in

     * {@link #toString()} and {@link DRBG#algorithmName}.

     */

    protected String algorithm;

    // Configurable parameters

    /**

     * Security strength for this instance. Must be assigned in

     * {@link #chooseAlgorithmAndStrength}. Should be at least the requested

     * strength. Might be smaller than the highest strength

     * {@link #algorithm} supports. Must not be -1.

     */

    protected int securityStrength;     // in bits

    /**

     * Strength requested in {@link DrbgParameters.Instantiation}.

     * The real strength is based on it. Do not modify it in a mechanism.

     */

    protected int requestedInstantiationSecurityStrength = -1;

    /**

     * The personalization string used by this instance. Set inside

     * {@link #configure(SecureRandomParameters)} and

     * can be used in a mechanism. Do not modify it in a mechanism.

     */

    protected byte[] personalizationString;

    /**

     * The prediction resistance flag used by this instance. Set inside

     * {@link #configure(SecureRandomParameters)}.

     */

    private boolean predictionResistanceFlag;

    // Non-standard configurable parameters

    /**

     * Whether a derivation function is used. Requested in

     * {@link MoreDrbgParameters}. Only CtrDRBG uses it.

     * Do not modify it in a mechanism.

     */

    protected boolean usedf;

    /**

     * The nonce for this instance. Set in {@link #instantiateIfNecessary}.

     * After instantiation, this field is not null. Do not modify it

     * in a mechanism.

     */

    protected transient byte[] nonce;

    /**

     * Requested nonce in {@link MoreDrbgParameters}. If set to null,

     * nonce will be chosen by system, and a reinstantiated DRBG will get a

     * new system-provided nonce.

     */

    private byte[] requestedNonce;

    /**

     * Requested algorithm in {@link MoreDrbgParameters}.

     * Do not modify it in a mechanism.

     */

    protected String requestedAlgorithm;

    /**

     * The entropy source used by this instance. Set inside

     * {@link #configure(SecureRandomParameters)}. This field

     * can be null. {@link #getEntropyInput} will take care of null check.

     */

    private transient EntropySource es;

    // Five abstract methods for SP 800-90A DRBG

    /**

     * Decides what algorithm and strength to use (SHA-256 or AES-256,

     * 128 or 256). Strength related fields must also be defined or redefined

     * here. Called in {@link #configure}. A mechanism uses

     * {@link #requestedAlgorithm},

     * {@link #requestedInstantiationSecurityStrength}, and

     * {@link #DEFAULT_STRENGTH} to decide which algorithm and strength to use.

     * <p>

     * If {@code requestedAlgorithm} is provided, it will always be used.

     * If {@code requestedInstantiationSecurityStrength} is also provided,

     * the algorithm will use the strength (an exception will be thrown if

     * the strength is not supported), otherwise, the smaller one of

     * the highest supported strength of the algorithm and the default strength

     * will be used.

     * <p>

     * If {@code requestedAlgorithm} is not provided, an algorithm will be

     * chosen that supports {@code requestedInstantiationSecurityStrength}

     * (or {@code DEFAULT_STRENGTH} if there is no request).

     * <p>

     * Since every call to {@link #configure} will call this method,

     * make sure to the calls do not contradict with each other.

     * <p>

     * Here are some examples of the algorithm and strength chosen (suppose

     * {@code DEFAULT_STRENGTH} is 128) for HashDRBG:

     * <pre>

     * requested             effective

     * (SHA-1, -1)           (SHA-1,128)

     * (SHA-1, 112)          (SHA-1,112)

     * (SHA-1, 192)          IAE

     * (SHA-256, -1)         (SHA-256,128)

     * (SHA-256, 128)        (SHA-256,128)

     * (SHA-3, -1)           IAE

     * (null, -1)            (SHA-256,128)

     * (null, 112)           (SHA-256,112)

     * (null, 192)           (SHA-256,192)

     * (null, 256)           (SHA-256,256)

     * (null, 384)           IAE

     * </pre>

     *

     * @throws IllegalArgumentException if the requested parameters

     *      can not be supported or contradict with each other.

     */

    protected abstract void chooseAlgorithmAndStrength();

    /**

     * Initiates security engines ({@code MessageDigest}, {@code Mac},

     * or {@code Cipher}). Must be called in deserialization. Please note

     * that before instantiation the algorithm might not be available yet.

     * In this case, just return and this method will be called

     * automatically at instantiation.

     */

    protected abstract void initEngine();

    /**

     * Instantiates a DRBG. Called automatically before the first

     * {@code nextBytes} call.

     * <p>

     * Note that the other parameters (nonce, strength, ps) are already

     * stored inside at configuration.

     *

     * @param ei the entropy input, its length is already conditioned to be

     *           between {@link #minLength} and {@link #maxLength}.

     */

    protected abstract void instantiateAlgorithm(byte[] ei);

    /**

     * The generate function.

     *

     * @param result fill result here, not null

     * @param additionalInput additional input, can be null. If not null,

     *          its length is smaller than {@link #maxAdditionalInputLength}

     */

    protected abstract void generateAlgorithm(

            byte[] result, byte[] additionalInput);

    /**

     * The reseed function.

     *

     * @param ei the entropy input, its length is already conditioned to be

     *           between {@link #minLength} and {@link #maxLength}.

     * @param additionalInput additional input, can be null. If not null,

     *          its length is smaller than {@link #maxAdditionalInputLength}

     * @throws UnsupportedOperationException if reseed is not supported

     */

    protected void reseedAlgorithm(

            byte[] ei, byte[] additionalInput) {

        throw new UnsupportedOperationException("No reseed function");

    }

    // SecureRandomSpi methods taken care of here. All final.

    @Override

    protected final void engineNextBytes(byte[] result) {

        engineNextBytes(result, DrbgParameters.nextBytes(

                -1, predictionResistanceFlag, null));

    }

    @Override

    protected final void engineNextBytes(

            byte[] result, SecureRandomParameters params) {

        Objects.requireNonNull(result);

        if (debug != null) {

            debug.println(this, "nextBytes");

        }

        if (params instanceof DrbgParameters.NextBytes) {

            // 800-90Ar1 9.3: Generate Process.

            DrbgParameters.NextBytes dp = (DrbgParameters.NextBytes) params;

            // Step 2: max_number_of_bits_per_request

            if (result.length > maxNumberOfBytesPerRequest) {

                // generateAlgorithm should be called multiple times to fill

                // up result. Unimplemented since maxNumberOfBytesPerRequest

                // is now Integer.MAX_VALUE.

            }

            // Step 3: check requested_security_strength

            if (dp.getStrength() > securityStrength) {

                throw new IllegalArgumentException("strength too high: "

                        + dp.getStrength());

            }

            // Step 4: check max_additional_input_length

            byte[] ai = dp.getAdditionalInput();

            if (ai != null && ai.length > maxAdditionalInputLength) {

                throw new IllegalArgumentException("ai too long: "

                        + ai.length);

            }

            // Step 5: check prediction_resistance_flag

            boolean pr = dp.getPredictionResistance();

            if (!predictionResistanceFlag && pr) {

                throw new IllegalArgumentException("pr not available");

            }

            instantiateIfNecessary(null);

            // Step 7: Auto reseed

            if (reseedCounter > reseedInterval || pr) {

                reseedAlgorithm(getEntropyInput(pr), ai);

                ai = null;

            }

            // Step 8, 10: Generate_algorithm

            // Step 9: Unnecessary. reseedCounter only updated after generation

            generateAlgorithm(result, ai);

            // Step 11: Return

        } else {

            throw new IllegalArgumentException("unknown params type:"

                    + params.getClass());

        }

    }

    @Override

    public final void engineReseed(SecureRandomParameters params) {

        if (debug != null) {

            debug.println(this, "reseed with params");

        }

        if (!supportReseeding) {

            throw new UnsupportedOperationException("Reseed not supported");

        }

        if (params == null) {

            params = DrbgParameters.reseed(predictionResistanceFlag, null);

        }

        if (params instanceof DrbgParameters.Reseed) {

            DrbgParameters.Reseed dp = (DrbgParameters.Reseed) params;

            // 800-90Ar1 9.2: Reseed Process.

            // Step 2: Check prediction_resistance_request

            boolean pr = dp.getPredictionResistance();

            if (!predictionResistanceFlag && pr) {

                throw new IllegalArgumentException("pr not available");

            }

            // Step 3: Check additional_input length

            byte[] ai = dp.getAdditionalInput();

            if (ai != null && ai.length > maxAdditionalInputLength) {

                throw new IllegalArgumentException("ai too long: "

                        + ai.length);

            }

            instantiateIfNecessary(null);

            // Step 4: Get_entropy_input

            // Step 5: Check step 4

            // Step 6-7: Reseed_algorithm

            reseedAlgorithm(getEntropyInput(pr), ai);

            // Step 8: Return

        } else {

            throw new IllegalArgumentException("unknown params type: "

                    + params.getClass());

        }

    }

    /**

     * Returns the given number of seed bytes. A DRBG always uses

     * {@link SeedGenerator} to get an array with full-entropy.

     * <p>

     * The implementation is identical to SHA1PRNG's

     * {@link SecureRandom#engineGenerateSeed}.

     *

     * @param numBytes the number of seed bytes to generate.

     * @return the seed bytes.

     */

    @Override

    public final byte[] engineGenerateSeed(int numBytes) {

        byte[] b = new byte[numBytes];

        SeedGenerator.generateSeed(b);

        return b;

    }

    /**

     * Reseeds this random object with the given seed. A DRBG always expands

     * or truncates the input to be between {@link #minLength} and

     * {@link #maxLength} and uses it to instantiate or reseed itself

     * (depending on whether the DRBG is instantiated).

     *

     * @param input the seed

     */

    @Override

    public final synchronized void engineSetSeed(byte[] input) {

        if (debug != null) {

            debug.println(this, "setSeed");

        }

        if (input.length < minLength) {

            input = Arrays.copyOf(input, minLength);

        } else if (input.length > maxLength) {

            input = Arrays.copyOf(input, maxLength);

        }

        if (!instantiated) {

            instantiateIfNecessary(input);

        } else {

            reseedAlgorithm(input, null);

        }

    }

    // get_entropy_input

    private byte[] getEntropyInput(boolean isPr) {

        // Should the 1st arg be minEntropy or minLength?

        //

        // Technically it should be minEntropy, but CtrDRBG

        // (not using derivation function) is so confusing

        // (does it need only strength or seedlen of entropy?)

        // that it's safer to assume minLength. In all other

        // cases minLength equals to minEntropy.

        return getEntropyInput(minLength, minLength, maxLength, isPr);

    }

    private byte[] getEntropyInput(int minEntropy, int minLength,

                                   int maxLength, boolean pr) {

        if (debug != null) {

            debug.println(this, "getEntropy(" + minEntropy + "," + minLength +

                    "," + maxLength + "," + pr + ")");

        }

        EntropySource esNow = es;

        if (esNow == null) {

            esNow = pr ? SeederHolder.prseeder : SeederHolder.seeder;

        }

        return esNow.getEntropy(minEntropy, minLength, maxLength, pr);

    }

    // Defaults

    /**

     * The default {@code EntropySource} determined by system property

     * "java.security.egd" or security property "securerandom.source".

     * <p>

     * This object uses {@link SeedGenerator#generateSeed(byte[])} to

     * return a byte array containing {@code minLength} bytes. It is

     * assumed to support prediction resistance and always contains

     * full-entropy. A trusted application can update this field.

     */

    private final static EntropySource defaultES =

            (minE, minLen, maxLen, pr) -> {

        byte[] result = new byte[minLen];

        SeedGenerator.generateSeed(result);

        return result;

    };