Module java.base
Package java.security

Class SecureRandom

java.lang.Object
java.util.Random
java.security.SecureRandom
所有已实现的接口:
Serializable, RandomGenerator

public class SecureRandom extends Random
该类提供了一个密码强度的随机数生成器(RNG)。

密码强度的随机数生成器至少符合《FIPS 140-2,密码模块安全要求》第4.9.1节中指定的统计随机数生成器测试。此外,SecureRandom 必须产生不确定性输出。因此,传递给SecureRandom对象的任何种子材料必须是不可预测的,并且所有SecureRandom输出序列必须是密码强度的,如《RFC 4086:安全性的随机性要求》中所述。

许多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,则不会发生自种子化。

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

请注意,并非所有SecureRandom实现都支持reseed

一些SecureRandom实现可能在其nextBytes方法中接受一个SecureRandomParameters参数,以进一步控制方法的行为。

注意:根据实现的不同,generateSeedreseednextBytes方法可能会在收集熵时阻塞,例如,如果熵源是各种类Unix-like操作系统上的/dev/random。

线程安全

SecureRandom对象可安全用于多个并发线程。
实现要求:
SecureRandom服务提供者可以通过将服务提供者属性“ThreadSafe”设置为“true”来宣传其是线程安全的。否则,此类将同步访问SecureRandomSpi实现的以下方法:
自 JDK 版本:
1.1
参见:
  • Constructor Details

    • SecureRandom

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

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

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

      有关标准RNG算法名称的信息,请参阅Java安全标准算法名称规范中的SecureRandom部分。

    • SecureRandom

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

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

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

      有关标准RNG算法名称的信息,请参阅Java安全标准算法名称规范中的SecureRandom部分。

      参数:
      seed - 种子。
      抛出:
      NullPointerException - 如果seednull
    • SecureRandom

      protected SecureRandom(SecureRandomSpi secureRandomSpi, Provider provider)
      创建一个SecureRandom对象。
      参数:
      secureRandomSpi - SecureRandom的实现。
      provider - 提供者。
  • Method Details

    • getInstance

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

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

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

      实现注意:
      JDK参考实现还使用jdk.security.provider.preferred Security属性来确定指定算法的首选提供者顺序。这可能与由Security.getProviders()返回的提供者顺序不同。
      参数:
      algorithm - RNG算法的名称。有关标准RNG算法名称的信息,请参阅Java安全标准算法名称规范中的SecureRandom部分。
      返回:
      新的SecureRandom对象
      抛出:
      NoSuchAlgorithmException - 如果没有Provider支持指定算法的SecureRandomSpi实现
      NullPointerException - 如果algorithmnull
      自:
      1.2
      另请参阅:
    • getInstance

      public static SecureRandom getInstance(String algorithm, String provider) throws NoSuchAlgorithmException, NoSuchProviderException
      返回一个实现指定随机数生成器(RNG)算法的SecureRandom对象。

      返回一个封装了指定提供者的SecureRandomSpi实现的新SecureRandom对象。指定的提供者必须在安全提供者列表中注册。

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

      参数:
      algorithm - RNG算法的名称。有关标准RNG算法名称的信息,请参阅Java安全标准算法名称规范中的SecureRandom部分。
      provider - 提供者的名称。
      返回:
      新的SecureRandom对象
      抛出:
      IllegalArgumentException - 如果提供者名称为null或空
      NoSuchAlgorithmException - 如果指定提供者不提供指定算法的SecureRandomSpi实现
      NoSuchProviderException - 如果指定提供者未在安全提供者列表中注册
      NullPointerException - 如果algorithmnull
      自:
      1.2
      另请参阅:
    • getInstance

      public static SecureRandom getInstance(String algorithm, Provider provider) throws NoSuchAlgorithmException
      返回一个实现指定随机数生成器(RNG)算法的SecureRandom对象。

      返回一个封装了指定提供者的SecureRandomSpi实现的新SecureRandom对象。请注意,指定的提供者不必在提供者列表中注册。

      参数:
      algorithm - RNG算法的名称。有关标准RNG算法名称的信息,请参阅Java安全标准算法名称规范中的SecureRandom部分。
      provider - 提供者。
      返回:
      新的SecureRandom对象
      抛出:
      IllegalArgumentException - 如果指定提供者为null
      NoSuchAlgorithmException - 如果指定提供者对象不提供指定算法的SecureRandomSpi实现
      NullPointerException - 如果algorithmnull
      自:
      1.4
      另请参阅:
    • getInstance

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

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

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

      实现注意:
      JDK参考实现还使用jdk.security.provider.preferred属性来确定指定算法的首选提供者顺序。这可能与由Security.getProviders()返回的提供者顺序不同。
      参数:
      algorithm - RNG算法的名称。有关标准RNG算法名称的信息,请参阅Java安全标准算法名称规范中的SecureRandom部分。
      params - 新创建的SecureRandom对象必须支持的SecureRandomParameters
      返回:
      新的SecureRandom对象
      抛出:
      IllegalArgumentException - 如果指定的参数为null
      NoSuchAlgorithmException - 如果没有提供者支持指定算法和参数的SecureRandomSpi实现
      NullPointerException - 如果algorithmnull
      自:
      9
      另请参阅:
    • getInstance

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

      返回一个封装了指定提供者的SecureRandomSpi实现的新SecureRandom对象。指定的提供者必须在安全提供者列表中注册。

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

      参数:
      algorithm - RNG算法的名称。有关标准RNG算法名称的信息,请参阅Java安全标准算法名称规范中的SecureRandom部分。
      params - 新创建的SecureRandom对象必须支持的SecureRandomParameters
      provider - 提供者的名称。
      返回:
      新的SecureRandom对象
      抛出:
      IllegalArgumentException - 如果提供者名称为null或空,或params为null
      NoSuchAlgorithmException - 如果指定提供者不支持指定算法和参数的SecureRandomSpi实现
      NoSuchProviderException - 如果指定提供者未在安全提供者列表中注册
      NullPointerException - 如果algorithmnull
      自:
      9
      另请参阅:
    • getInstance

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

      返回一个封装了指定提供者的SecureRandomSpi实现的新SecureRandom对象。请注意,指定的提供者不必在提供者列表中注册。

      参数:
      algorithm - RNG算法的名称。有关标准RNG算法名称的信息,请参阅Java安全标准算法名称规范中的SecureRandom部分。
      params - 新创建的SecureRandom对象必须支持的SecureRandomParameters
      provider - 提供者。
      返回:
      新的SecureRandom对象
      抛出:
      IllegalArgumentException - 如果指定的提供者或参数为null
      NoSuchAlgorithmException - 如果指定的提供者不支持指定算法和参数的SecureRandomSpi实现
      NullPointerException - 如果algorithmnull
      自版本:
      9
      参见:
    • getProvider

      public final Provider getProvider()
      返回此SecureRandom对象的提供者。
      返回:
      SecureRandom对象的提供者。
    • getAlgorithm

      public String getAlgorithm()
      返回此SecureRandom对象实现的算法名称。
      返回:
      算法名称,如果无法确定算法名称,则返回unknown
      自版本:
      1.5
    • toString

      public String toString()
      返回此SecureRandom的可读字符串表示形式。
      覆盖:
      toString 在类中 Object
      返回:
      字符串表示形式
    • getParameters

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

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

      调用者可以使用返回的值了解此SecureRandom支持的功能。

      返回:
      有效的SecureRandomParameters参数,如果未使用参数,则返回null
      自版本:
      9
      参见:
    • setSeed

      public void setSeed(byte[] seed)
      使用给定的种子重新初始化此随机对象。种子是对现有种子的补充,而不是替换。因此,重复调用永远不会减少随机性。

      如果在任何nextBytesreseed调用之前调用setSeed,PRNG SecureRandom不会自动进行种子化。调用者应确保seed参数包含足够的熵以确保此SecureRandom的安全性。

      参数:
      seed - 种子。
      抛出:
      NullPointerException - 如果seednull
      参见:
    • setSeed

      public void setSeed(long seed)
      使用给定的long seed中包含的八个字节重新初始化此随机对象。给定的种子是对现有种子的补充,而不是替换。因此,重复调用永远不会减少随机性。

      如果在任何nextBytesreseed调用之前调用setSeed,PRNG SecureRandom不会自动进行种子化。调用者应确保seed参数包含足够的熵以确保此SecureRandom的安全性。

      此方法是为了与java.util.Random兼容而定义的。

      覆盖:
      setSeed 在类中 Random
      参数:
      seed - 种子。
      参见:
    • nextBytes

      public void nextBytes(byte[] bytes)
      生成用户指定数量的随机字节。
      指定者:
      nextBytes 在接口中 RandomGenerator
      覆盖:
      nextBytes 在类中 Random
      参数:
      bytes - 用随机字节填充的数组。
      抛出:
      NullPointerException - 如果bytesnull
    • nextBytes

      public void nextBytes(byte[] bytes, SecureRandomParameters params)
      生成具有附加参数的用户指定数量的随机字节。
      参数:
      bytes - 用随机字节填充的数组
      params - 附加参数
      抛出:
      NullPointerException - 如果bytesnull
      UnsupportedOperationException - 如果底层提供者实现未覆盖此方法
      IllegalArgumentException - 如果paramsnull,非法或不受此SecureRandom支持
      自版本:
      9
    • next

      protected final int next(int numBits)
      生成包含用户指定数量伪随机位(右对齐,带前导零)的整数。此方法覆盖了java.util.Random方法,并用于为从该类继承的所有方法(例如nextIntnextLongnextFloat)提供随机位的来源。
      覆盖:
      next 在类中 Random
      参数:
      numBits - 要生成的伪随机位数,其中0 <= numBits <= 32
      返回:
      包含用户指定数量伪随机位(右对齐,带前导零)的int
    • getSeed

      public static byte[] getSeed(int numBytes)
      返回使用此类用于对自身进行种子化的种子生成算法计算的给定数量的种子字节。此调用可用于对其他随机数生成器进行种子化。

      此方法仅用于向后兼容。建议调用者使用其中一种替代的getInstance方法获取SecureRandom对象,然后调用generateSeed方法从该对象获取种子字节。

      参数:
      numBytes - 要生成的种子字节数。
      返回:
      种子字节。
      抛出:
      IllegalArgumentException - 如果numBytes为负数
      参见:
    • 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安全属性中包含已知的强SecureRandom实现列表。

      Java平台的每个实现都必须支持至少一种强SecureRandom实现。

      返回:
      根据securerandom.strongAlgorithms安全属性指示的强SecureRandom实现
      抛出:
      NoSuchAlgorithmException - 如果没有可用的算法
      自版本:
      1.8
      参见:
    • reseed

      public void reseed()
      使用从熵源读取的熵输入重新对此SecureRandom进行种子化。
      抛出:
      UnsupportedOperationException - 如果底层提供者实现未覆盖此方法。
      自版本:
      9
    • reseed

      public void reseed(SecureRandomParameters params)
      使用额外参数从熵源读取熵输入重新生成此SecureRandom

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

      参数:
      params - 额外参数
      抛出:
      UnsupportedOperationException - 如果基础提供程序实现未覆盖此方法。
      IllegalArgumentException - 如果paramsnull,非法或不受此SecureRandom支持。
      自:
      9