Module  java.base
软件包  java.security

Class SecureRandom

  • All Implemented Interfaces:
    Serializable 

    public class SecureRandom
extends Random
    这个类提供了一个密码强的随机数生成器（RNG）。

    密码强的随机数最低限度符合FIPS 140-2, Security Requirements for Cryptographic Modules第4.9.1节中规定的统计随机数发生器测试。 此外， SecureRandom必须产生非确定性输出。 因此，传递给SecureRandom对象的任何种子材料必须是不可预测的，并且所有SecureRandom输出序列必须加密强度，如RFC 4086: Randomness Requirements for Security中所述 。

    许多SecureRandom实现是伪随机数生成器（PRNG，也称为确定性随机位生成器或DRBG）的形式，这意味着它们使用确定性算法从随机种子产生伪随机序列。 其他实现可以产生真正的随机数，而其他实现可以使用两种技术的组合。

    调用者通过无参数构造函数或getInstance方法之一获取SecureRandom实例。 例如： 

     SecureRandom r1 = new SecureRandom();
 SecureRandom r2 = SecureRandom.getInstance("NativePRNG");
 SecureRandom r3 = SecureRandom.getInstance("DRBG",
         DrbgParameters.instantiation(128, RESEED_ONLY, null));

    上述第三个语句返回支持特定实例参数的特定算法的一个SecureRandom对象。 实现的有效实例参数必须与此最小请求匹配，但不一定相同。 例如，即使请求不需要某个功能，实际的实例化也可以提供该功能。 实现可能会延迟实例化一个SecureRandom直到它被实际使用，但有效的实例参数必须在创建之后立即确定，并且getParameters()应始终返回相同的结果。

    典型的呼叫者SecureRandom调用以下方法来检索随机字节： 

     SecureRandom random = new SecureRandom();
 byte[] bytes = new byte[20];
 random.nextBytes(bytes);

    呼叫者还可以调用generateSeed(int)方法来生成给定数量的种子字节（例如，种子其他随机数生成器）： 

     byte[] seed = random.generateSeed(20);

    新创建的PRNG SecureRandom对象未被种子（除非由SecureRandom(byte[])创建）。 第一个呼叫nextBytes将迫使它从一个实现特定的熵源进行种子化。 如果以前打过setSeed ，这种自播不会发生。

    A SecureRandom可以随时通过调用reseed或setSeed方法重新进入。 reseed方法从熵源读取熵输入以重新设定自身。 setSeed方法要求调用者提供种子。

    请注意： reseed可能不是所有支持SecureRandom实现。

    一些SecureRandom实现可以在其nextBytes(byte[], SecureRandomParameters)和reseed(SecureRandomParameters)方法中接受SecureRandomParameters参数，以进一步控制方法的行为。

    注意：根据实施， generateSeed ， reseed和nextBytes方法可阻止作为熵被收集，例如，如果源熵是/ dev /上的各种类Unix操作系统随机的。

    线程安全

    SecureRandom对象可以安全地被多个并发线程使用。
    实现要求：
    A SecureRandom服务提供商可以通过在注册提供程序时将service provider attribute “ThreadSafe”设置为“true”来宣传其是线程安全的。 否则，此类将同步访问SecureRandomSpi实现的以下方法：
    从以下版本开始：
    1.1
    另请参见：
    SecureRandomSpi ， Random ， Serialized Form

    • 构造方法详细信息

      • SecureRandom

        public SecureRandom​()
        构造一个实现默认随机数算法的安全随机数生成器（RNG）。

        此构造函数遍历注册的安全提供程序列表，从最优选的提供程序开始。 SecureRandomSpi从支持SecureRandom （RNG）算法的第一个提供程序封装SecureRandomSpi实现的新的SecureRandom对象。 如果没有提供者支持RNG算法，则返回实现特定的默认值。

        请注意，可以通过Security.getProviders()方法检索已注册提供商的列表。

        见SecureRandom的部分Java Security Standard Algorithm Names Specification有关标准RNG算法名称的信息。

      • SecureRandom

        public SecureRandom​(byte[] seed)
        构造一个实现默认随机数算法的安全随机数生成器（RNG）。 SecureRandom实例用指定的种子字节种子。

        此构造函数遍历注册的安全提供程序列表，从最优选的提供程序开始。 SecureRandomSpi从支持SecureRandom （RNG）算法的第一个提供程序封装SecureRandomSpi实现的新的SecureRandom对象。 如果没有提供者支持RNG算法，则返回实现特定的默认值。

        请注意，可以通过Security.getProviders()方法检索注册提供商的列表。

        见SecureRandom的部分Java Security Standard Algorithm Names Specification有关标准RNG算法名称的信息。

        参数
        seed - 种子。

      • SecureRandom

        protected SecureRandom​(SecureRandomSpi secureRandomSpi,
                       Provider provider)
        创建一个 SecureRandom对象。
        参数
        secureRandomSpi - SecureRandom实现。
        provider - 提供商。

    • 方法详细信息

      • getInstance

        public static SecureRandom getInstance​(String algorithm)
                                throws NoSuchAlgorithmException
        返回实现指定的随机数生成器（RNG）算法的SecureRandom对象。

        此方法遍历已注册的安全提供程序列表，从最优选的提供程序开始。 SecureRandomSpi从支持指定算法的第一个提供者封装SecureRandomSpi实现的新的SecureRandom对象。

        请注意，注册提供商的列表可以通过Security.getProviders()方法检索。

        Implementation Note:
        JDK参考实现另外使用jdk.security.provider.preferred Security属性来确定指定算法的首选提供者顺序。 这可能与Security.getProviders()返回的提供商的顺序不同。
        参数
        algorithm - RNG算法的名称。 见SecureRandom的部分Java Security Standard Algorithm Names Specification有关标准RNG算法名称的信息。
        结果
        新的 SecureRandom对象
        异常
        NoSuchAlgorithmException - 如果没有 Provider支持指定算法的 SecureRandomSpi实现
        NullPointerException - 如果 algorithm是 null
        从以下版本开始：
        1.2
        另请参见：
        Provider

      • getInstance

        public static SecureRandom getInstance​(String algorithm,
                                       SecureRandomParameters params)
                                throws NoSuchAlgorithmException
        返回实现指定的随机数生成器（RNG）算法的SecureRandom对象，并支持指定的SecureRandomParameters请求。

        此方法遍历已注册的安全提供程序列表，从最优选的提供程序开始。 返回一个新的SecureRandom对象，该对象封装了来自第一个提供程序的SecureRandomSpi实现，该提供程序支持指定的算法和指定的SecureRandomParameters 。

        请注意，可以通过Security.getProviders()方法检索已注册提供商的列表。

        Implementation Note:
        JDK参考实现另外使用jdk.security.provider.preferred属性来确定指定算法的首选提供者顺序。 这可能与Security.getProviders()返回的提供商的顺序不同。
        参数
        algorithm - RNG算法的名称。 见SecureRandom的部分Java Security Standard Algorithm Names Specification有关标准RNG算法名称的信息。
        params -在 SecureRandomParameters新创建 SecureRandom对象必须支持。
        结果
        新的 SecureRandom对象
        异常
        IllegalArgumentException - 如果指定的参数是 null
        NoSuchAlgorithmException - 如果没有提供程序支持指定算法和参数的 SecureRandomSpi实现
        NullPointerException - 如果 algorithm是 null
        从以下版本开始：
        9
        另请参见：
        Provider

      • getInstance

        public static SecureRandom getInstance​(String algorithm,
                                       SecureRandomParameters params,
                                       Provider provider)
                                throws NoSuchAlgorithmException
        返回实现指定的随机数生成器（RNG）算法的SecureRandom对象，并支持指定的SecureRandomParameters请求。

        新SecureRandom对象封装SecureRandomSpi从指定执行Provider返回对象。 请注意，指定的Provider对象不必在提供者列表中注册。

        参数
        algorithm - RNG算法的名称。 见SecureRandom的部分Java Security Standard Algorithm Names Specification有关标准RNG算法名称的信息。
        params -在 SecureRandomParameters新创建 SecureRandom对象必须支持。
        provider - 提供商。
        结果
        新的 SecureRandom对象
        异常
        IllegalArgumentException - 如果指定的提供者或参数是 null
        NoSuchAlgorithmException - 如果指定的提供程序不支持针对指定算法和参数的 SecureRandomSpi实现
        NullPointerException - 如果 algorithm是 null
        从以下版本开始：
        9
        另请参见：
        Provider

      • getProvider

        public final Provider getProvider​()
        返回此 SecureRandom对象的提供者。
        结果
        这个 SecureRandom对象的提供者。

      • getAlgorithm

        public String getAlgorithm​()
        返回由该 SecureRandom对象实现的算法的名称。
        结果
        如果算法名称无法确定，则算法的名称为 unknown 。
        从以下版本开始：
        1.5

      • toString

        public String toString​()
        返回此 SecureRandom的人类可读字符串表示 SecureRandom 。
        重写：
        toString在 Object
        结果
        字符串表示

      • getParameters

        public SecureRandomParameters getParameters​()
        返回此SecureRandom实例的有效SecureRandomParameters 。

        返回的值可能与传递给getInstance方法的SecureRandomParameters对象不同，但在此SecureRandom对象的生命周期内不能更改。

        一个调用者可以使用返回的值来找出这个SecureRandom支持哪些特性。

        结果
        有效的SecureRandomParameters参数，如果没有使用参数， null 。
        从以下版本开始：
        9
        另请参见：
        SecureRandomSpi

      • setSeed

        public void setSeed​(byte[] seed)
        用给定的种子重新设定这个随机对象。 种子补充，而不是替代现有的种子。 因此，重复的呼叫保证不会减少随机性。

        一个PRNG SecureRandom如果不会自动种子本身setSeed之前任何所谓nextBytes或者reseed电话。 调用者应该确保seed参数包含足够的熵来确保这个SecureRandom的安全性。

        参数
        seed - 种子。
        另请参见：
        getSeed(int)

      • setSeed

        public void setSeed​(long seed)
        使用给定的long seed包含的八个字节重新设置此随机对象。 给定的种子补充，而不是替代现有的种子。 因此，重复的呼叫保证不会减少随机性。

        此方法的定义是与java.util.Random兼容性。

        重写：
        setSeed在 Random
        参数
        seed - 种子。
        另请参见：
        getSeed(int)

      • nextBytes

        public void nextBytes​(byte[] bytes)
        生成用户指定的随机字节数。
        重写：
        nextBytes在 Random
        参数
        bytes - 要用随机字节填充的数组。

      • next

        protected final int next​(int numBits)
        生成一个包含用户指定数量的伪随机位的整数（右对齐，带前导零）。 此方法重写一个java.util.Random方法，以及用于提供随机比特的源到所有的从类继承的方法（例如， nextInt ， nextLong ，和nextFloat ）。
        重写：
        next在 Random
        参数
        numBits - 要生成的伪随机比特数，其中 0 <= numBits <= 32 。
        结果
        一个 int包含用户指定的伪随机位数（右对齐，带前导零）。

      • getSeed

        public static byte[] getSeed​(int numBytes)
        返回给定数量的种子字节，使用该类用于种子本身的种子生成算法计算。 该呼叫可以用于种子其他随机数发生器。

        此方法仅用于向后兼容。 鼓励呼叫者使用另一种getInstance方法来获取一个SecureRandom对象，然后调用generateSeed方法从该对象获取种子字节。

        参数
        numBytes - 要生成的种子字节数。
        结果
        种子字节。
        异常
        IllegalArgumentException - 如果 numBytes为负数
        另请参见：
        setSeed(byte[])

      • generateSeed

        public byte[] generateSeed​(int numBytes)
        返回给定数量的种子字节，使用该类用于种子本身的种子生成算法计算。 该呼叫可以用于种子其他随机数发生器。
        参数
        numBytes - 要生成的种子字节数。
        结果
        种子字节。
        异常
        IllegalArgumentException - 如果 numBytes为负数

      • getInstanceStrong

        public static SecureRandom getInstanceStrong​()
                                      throws NoSuchAlgorithmException
        返回通过使用securerandom.strongAlgorithms Security属性中指定的算法/提供程序选择的一个SecureRandom对象。

        某些情况需要强大的随机值，例如创建高价值/长寿命秘密（如RSA公钥/私钥）时。 为了帮助指导应用程序选择合适的强大的SecureRandom实现，Java发行版包括securerandom.strongAlgorithms Security属性中已知的强大的SecureRandom实现列表。

        Java平台的每个实现都需要至少支持一个强大的SecureRandom实现。

        结果
        一个强大的 SecureRandom实施，如 securerandom.strongAlgorithms Security Properties所示
        异常
        NoSuchAlgorithmException - 如果没有算法可用
        从以下版本开始：
        1.8
        另请参见：
        Security.getProperty(String)

      • reseed

        public void reseed​()
        使用从其熵源读取的熵输入来确定此 SecureRandom 。
        异常
        UnsupportedOperationException - 如果底层提供者实现没有覆盖此方法。
        从以下版本开始：
        9

      • reseed

        public void reseed​(SecureRandomParameters params)
        重新设计这个SecureRandom其中熵输入从其熵源读取附加参数。

        注意，熵是从熵源获得的。 虽然params一些数据可能包含熵，但其主要用途是提供多样性。

        参数
        params - 额外的参数
        异常
        UnsupportedOperationException - 如果底层提供者实现没有覆盖此方法。
        IllegalArgumentException - 如果 params是 null ，非法或不支持此 SecureRandom
        从以下版本开始：
        9