/*
 * Copyright 2018 Scytl Secure Electronic Voting SA
 *
 * All rights reserved
 *
 * See our extended copyright notice in *file 'Copyright.txt' which is part of this source code package
 */
package com.scytl.cryptolib.securerandom.cryptoapi;

import java.util.Set;

import com.scytl.cryptolib.api.exceptions.GeneralCryptoLibException;

/**
 * Interface that provides the functionality to obtain random bytes.
 */
public interface CryptoAPIRandomBytes {

    /**
     * Given a positive integer {@code lengthInBytes}, this method generates a
     * byte array of {@code lengthInBytes} bytes.
     * 
     * @param lengthInBytes
     *            The lengthInBytes that specifies how many bytes are to be
     *            generated.
     * @return a byte array generated by {@link java.security.SecureRandom}.
     * @throws GeneralCryptoLibException
     *             if {@code lengthInBytes} is out of the range for this
     *             generator.
     * @see java.security.SecureRandom#nextBytes(byte[] bytes)
     */
    byte[] nextRandom(final int lengthInBytes)
            throws GeneralCryptoLibException;

    /**
     * Given a positive integer {@code lengthInBytes}, this method generates a
     * byte array of {@code lengthInBytes} bytes. The output is not equal to any
     * of the byte arrays of the given {@code blackList}. Note: the
     * {@code blackList} cannot contain more elements than: (2^(8*
     * {@code lengthInBytes})-1). Moreover, the {@code blackList} should only
     * contain byte arrays of size equal to {@code lengthInBytes}.
     * 
     * @param lengthInBytes
     *            The lengthInBytes that specifies how many bytes are to be
     *            generated
     * @param blackList
     *            Set of byte arrays.
     * @return a byte array generated by {@link java.security.SecureRandom}.
     * @throws GeneralCryptoLibException
     *             if {@code lengthInBytes} is out of the range for this
     *             generator.
     * @throws GeneralCryptoLibException
     *             if the {@code blackList} contains too many elements.
     * @throws GeneralCryptoLibException
     *             if the {@code blackList} contains any element with a
     *             different length than the given {@code lengthInBytes}.
     * @see java.security.SecureRandom#nextBytes(byte[] bytes)
     */
    byte[] nextRandom(final int lengthInBytes, Set<Byte[]> blackList)
            throws GeneralCryptoLibException;

}
