AbstractDrbg.java

/*
 * Copyright (c) 2016, 2020, 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. It is used as {@link DRBG#impl}.
 * <p>
 * This class has 5 abstract methods. 3 are defined by SP800-90A:
 * <ol>
 *  <li>{@link #generateAlgorithm(byte[], byte[])}
 *  <li>{@link #reseedAlgorithm(byte[], byte[])} (In fact this is not an
 *      abstract method, but any DRBG supporting reseeding must override it.)
 *  <li>{@link #instantiateAlgorithm(byte[])}
 * </ol>
 * and 2 for implementation purpose:
 * <ol>
 *  <li>{@link #initEngine()}
 *  <li>{@link #chooseAlgorithmAndStrength}
 * </ol>
 * Although this class is not a child class of {@link SecureRandomSpi}, it
 * implements all abstract methods there as final.
 * <p>
 * The initialization process of a DRBG is divided into 2 phases:
 * {@link #configure configuration} is eagerly called to set up parameters,
 * and {@link #instantiateIfNecessary instantiation} is lazily called only
 * when nextBytes or reseed is called.
 * <p>
 * SecureRandom methods like reseed and nextBytes are not thread-safe.
 * An implementation is required to protect shared access to instantiate states
 * (instantiated, nonce) and DRBG states (v, c, key, reseedCounter, etc).
 */
public abstract class AbstractDrbg {

    /**
     * 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 boolean instantiated;

    /**
     * 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}.
     *
     * Volatile, will be used in a double checked locking.
     */
    protected volatile int reseedCounter;

    // 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()}.
     */
    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 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 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-224, 256)        IAE
     * (SHA-256, -1)         (SHA-256,128)
     * (SHA-256, 112)        (SHA-256,112)
     * (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}). This method is called during 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.

    protected final void engineNextBytes(byte[] result) {
        engineNextBytes(result, DrbgParameters.nextBytes(
                -1, predictionResistanceFlag, null));
    }

    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 (reseedCounter might overflow)
            // Double checked locking, safe because reseedCounter is volatile
            if (reseedCounter < 0 || reseedCounter > reseedInterval || pr) {
                synchronized (this) {
                    if (reseedCounter < 0 || 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());
        }
    }

    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.
     */
    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
     */
    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 is equal 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.
     */
    private static final EntropySource defaultES =
            (minE, minLen, maxLen, pr) -> {
        byte[] result = new byte[minLen];
        SeedGenerator.generateSeed(result);
        return result;
    };

    private static class SeederHolder {

        /**
         * Default EntropySource for SecureRandom with prediction resistance,
         */
        static final EntropySource prseeder;

        /**
         * Default EntropySource for SecureRandom without prediction resistance,
         * which is backed by a DRBG whose EntropySource is {@link #prseeder}.
         */
        static final EntropySource seeder;

        static {
            prseeder = defaultES;
            // According to SP800-90C section 7, a DRBG without live
            // entropy (drbg here, with pr being false) can instantiate
            // another DRBG with weaker strength. So we choose highest
            // strength we support.
            HashDrbg first = new HashDrbg(new MoreDrbgParameters(
                    prseeder, null, "SHA-256", null, false,
                    DrbgParameters.instantiation(
                            256, NONE,
                            SeedGenerator.getSystemEntropy())));
            seeder = (entropy, minLen, maxLen, pr) -> {
                if (pr) {
                    // This SEI does not support pr
                    throw new IllegalArgumentException("pr not supported");
                }
                byte[] result = new byte[minLen];
                first.engineNextBytes(result);
                return result;
            };
        }
    }

    // Constructor called by overridden methods, initializer...

    /**
     * A constructor without argument so that an implementation does not
     * need to always write {@code super(params)}.
     */
    protected AbstractDrbg() {
        // Nothing
    }

    /**
     * A mechanism shall override this constructor to setup {@link #mechName},
     * {@link #highestSupportedSecurityStrength},
     * {@link #supportPredictionResistance}, {@link #supportReseeding}
     * or other features like {@link #DEFAULT_STRENGTH}. Finally it shall
     * call {@link #configure} on {@code params}.
     *
     * @param params the {@link SecureRandomParameters} object.
     *               This argument can be {@code null}.
     * @throws IllegalArgumentException if {@code params} is
     *         inappropriate for this SecureRandom.
     */
    protected AbstractDrbg(SecureRandomParameters params) {
        // Nothing
    }

    /**
     * Returns the current configuration as a {@link DrbgParameters.Instantiation}
     * object.
     *
     * @return the curent configuration
     */
    protected SecureRandomParameters engineGetParameters() {
        // Or read from variable.
        return DrbgParameters.instantiation(
                securityStrength,
                predictionResistanceFlag ? PR_AND_RESEED :
                        (supportReseeding ? RESEED_ONLY : NONE),
                personalizationString);
    }

    /**
     * Configure this DRBG. This method calls
     * {@link #chooseAlgorithmAndStrength()} and {@link #initEngine()}
     * but does not do the actual instantiation.
     *
     * @param params configuration, if null, default configuration (default
     *               strength, pr_false, no personalization string) is used.
     * @throws IllegalArgumentException if {@code params} is
     *         inappropriate for this SecureRandom.
     */
    protected final void configure(SecureRandomParameters params) {
        if (debug != null) {
            debug.println(this, "configure " + this + " with " + params);
        }
        if (params == null) {
            params = DrbgParameters.instantiation(-1, RESEED_ONLY, null);
        }
        if (params instanceof MoreDrbgParameters) {
            MoreDrbgParameters m = (MoreDrbgParameters)params;
            this.requestedNonce = m.nonce;
            this.es = m.es;
            this.requestedAlgorithm = m.algorithm;
            this.usedf = m.usedf;
            params = DrbgParameters.instantiation(m.strength,
                    m.capability, m.personalizationString);
        }
        if (params != null) {
            if (params instanceof DrbgParameters.Instantiation) {
                DrbgParameters.Instantiation inst =
                        (DrbgParameters.Instantiation) params;

                // 800-90Ar1 9.1: Instantiate Process. Steps 1-5.

                // Step 1: Check requested_instantiation_security_strength
                if (inst.getStrength() > highestSupportedSecurityStrength) {
                    throw new IllegalArgumentException("strength too big: "
                            + inst.getStrength());
                }

                // Step 2: Check prediction_resistance_flag
                if (inst.getCapability().supportsPredictionResistance()
                        && !supportPredictionResistance) {
                    throw new IllegalArgumentException("pr not supported");
                }

                // Step 3: Check personalization_string
                byte[] ps = inst.getPersonalizationString();
                if (ps != null && ps.length > maxPersonalizationStringLength) {
                    throw new IllegalArgumentException("ps too long: "
                            + ps.length);
                }

                if (inst.getCapability().supportsReseeding()
                        && !supportReseeding) {
                    throw new IllegalArgumentException("reseed not supported");
                }
                this.personalizationString = ps;
                this.predictionResistanceFlag =
                        inst.getCapability().supportsPredictionResistance();
                this.requestedInstantiationSecurityStrength = inst.getStrength();
            } else {
                throw new IllegalArgumentException("unknown params: "
                        + params.getClass());
            }
        }

        // Step 4: Set security_strength
        chooseAlgorithmAndStrength();
        instantiated = false;

        // Step 5: no-op.

        if (debug != null) {
            debug.println(this, "configured " + this);
        }
    }

    /**
     * Instantiate if necessary,
     *
     * @param entropy a user-provided entropy, the length is already good.
     *                If null, will fetch entropy input automatically.
     */
    private synchronized void instantiateIfNecessary(byte[] entropy) {
        if (!instantiated) {

            // 800-90Ar1 9.1: Instantiate Process. Steps 6-12.

            // Step 6: Get_entropy_input
            // Step 7: check error (getEntropyInput throw no exception now)
            if (entropy == null) {
                entropy = getEntropyInput(predictionResistanceFlag);
            }

            // Step 8. nonce
            if (requestedNonce != null) {
                nonce = requestedNonce;
            } else {
                nonce = NonceProvider.next();
            }
            initEngine();

            // Step 9-11: Instantiate_algorithm
            instantiateAlgorithm(entropy);
            instantiated = true;

            // Step 12: Return
        }
    }

    // Nonce provider

    private static class NonceProvider {

        // 128 bits of nonce can be used by 256-bit strength DRBG
        private static final byte[] block = new byte[16];

        private static synchronized byte[] next() {
            int k = 15;
            while ((k >= 0) && (++block[k] == 0)) {
                k--;
            }
            return block.clone();
        }
    }

    // Misc

    /**
     * Returns the smallest standard strength (112, 128, 192, 256) that is
     * greater or equal to the input.
     *
     * @param input the input strength
     * @return the standard strength
     */
    protected static int getStandardStrength(int input) {
        if (input <= 112) return 112;
        if (input <= 128) return 128;
        if (input <= 192) return 192;
        if (input <= 256) return 256;
        throw new IllegalArgumentException("input too big: " + input);
    }

    @Override
    public String toString() {
        return mechName + ","  + algorithm
                + "," + securityStrength + ","
                + (predictionResistanceFlag ? "pr_and_reseed"
                        : (supportReseeding ? "reseed_only" : "none"));
    }
}