Класс 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 имеют вид псевдогенератора случайных чисел (ПГШ, также известного как генератор детерминированных случайных битов или ДГСБ), что означает, что они используют детерминированный алгоритм для получения псевдослучайной последовательности из случайного семени. Другие реализации могут генерировать истинные случайные числа, а другие могут использовать комбинацию обоих методов.

Вызывающий получает экземпляр SecureRandom через конструктор без аргументов или один из методов getInstance. Например:

 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);

Новый созданный объект ПГШ SecureRandom не инициализирован (за исключением случаев, когда он создан с помощью SecureRandom(byte[])). Первый вызов nextBytes заставит его инициализироваться из источника энтропии, специфичного для реализации. Эта самоинициализация не произойдёт, если setSeed был ранее вызван.

Объект SecureRandom может быть повторно инициализирован в любое время путём вызова метода reseed или setSeed. Метод reseed считывает входные данные энтропии из своего источника энтропии для повторной инициализации. Метод setSeed требует, чтобы вызывающий предоставил семя.

Обратите внимание, что reseed может не поддерживаться всеми реализациями SecureRandom.

Некоторые реализации SecureRandom могут принять параметр SecureRandomParameters в своих методах nextBytes(byte[], SecureRandomParameters) и reseed(SecureRandomParameters) для дальнейшего управления поведением методов.

Примечание: В зависимости от реализации методы generateSeed, reseed и nextBytes могут блокироваться, пока собирается энтропия, например, если источником энтропии является /dev/random на различных операционных системах Unix-подобных системах.

Безопасность потоков

Объекты SecureRandom безопасны для использования несколькими одновременными потоками.

Требования к реализации:

Поставщик услуг SecureRandom может объявить, что он безопасен для потоков, установив атрибут поставщика услуг атрибут поставщика услуг "ThreadSafe" в значение "true" при регистрации поставщика. В противном случае этот класс будет вместо этого синхронизировать доступ к следующим методам реализации SecureRandomSpi:

С:

1.1

См. также:

Краткое описание вложенных классов

Вложенные классы/интерфейсы, объявленные в интерфейсе java.util.random.RandomGenerator

RandomGenerator.ArbitrarilyJumpableGenerator, RandomGenerator.JumpableGenerator, RandomGenerator.LeapableGenerator, RandomGenerator.SplittableGenerator, RandomGenerator.StreamableGenerator

Краткое описание конструкторов

SecureRandom()

SecureRandom(byte[] seed)

SecureRandom(SecureRandomSpi secureRandomSpi,
 Provider provider)

Модификатор	Конструктор	Описание
	Создаёт генератор псевдослучайных чисел (RNG), реализующий стандартный алгоритм.
	Создаёт генератор псевдослучайных чисел (RNG), реализующий стандартный алгоритм.
`protected`	Создаёт объект `SecureRandom`.

Краткое описание методов

Модификатор и тип	Метод	Описание
`byte[]`	`generateSeed(int numBytes)`	Возвращает заданное количество байтов семян, вычисленных с использованием алгоритма генерации семян, используемого этим классом для инициализации.
`String`	`getAlgorithm()`	Возвращает имя алгоритма, реализованного этим объектом `SecureRandom`.
`static SecureRandom`	`getInstance(String algorithm)`	Возвращает объект `SecureRandom`, реализующий указанный алгоритм генератора псевдослучайных чисел (RNG).
`static SecureRandom`	`getInstance(String algorithm, String provider)`	Возвращает объект `SecureRandom`, реализующий указанный алгоритм генератора псевдослучайных чисел (RNG).
`static SecureRandom`	`getInstance(String algorithm, Provider provider)`	Возвращает объект `SecureRandom`, реализующий указанный алгоритм генератора псевдослучайных чисел (RNG).
`static SecureRandom`	`getInstance(String algorithm, SecureRandomParameters params)`	Возвращает объект `SecureRandom`, реализующий указанный алгоритм генератора псевдослучайных чисел (RNG) и поддерживающий указанный запрос `SecureRandomParameters`.
`static SecureRandom`	`getInstance(String algorithm, SecureRandomParameters params, String provider)`	Возвращает объект `SecureRandom`, реализующий указанный алгоритм генератора псевдослучайных чисел (RNG) и поддерживающий указанный запрос `SecureRandomParameters`.
`static SecureRandom`	`getInstance(String algorithm, SecureRandomParameters params, Provider provider)`	Возвращает объект `SecureRandom`, выбранный с использованием алгоритмов/провайдеров, указанных в свойстве `securerandom.strongAlgorithms` `Security`.
`static SecureRandom`	`getInstanceStrong()`	Возвращает эффективные параметры `SecureRandomParameters` для этого экземпляра `SecureRandom`.
`SecureRandomParameters`	`getParameters()`	Возвращает поставщика этого объекта `SecureRandom`.
`final Provider`	`getProvider()`	Возвращает заданное количество байтов семян, вычисленных с использованием алгоритма генерации семян, используемого этим классом для инициализации.
`static byte[]`	`getSeed(int numBytes)`	Генерирует целое число, содержащее указанное пользователем количество псевдослучайных бит (выровнены по правому краю, с ведущими нулями).
`protected final int`	`next(int numBits)`	Генерирует указанное пользователем количество случайных байтов.
`void`	`nextBytes(byte[] bytes)`	Генерирует указанное пользователем количество случайных байтов с дополнительными параметрами.
`void`	`nextBytes(byte[] bytes, SecureRandomParameters params)`	Перезапускает этот объект `SecureRandom` с вводом энтропии, считанным из его источника энтропии.
`void`	`reseed()`	Перезапускает этот объект `SecureRandom` с вводом энтропии, считанным из его источника энтропии, с дополнительными параметрами.
`void`	`reseed(SecureRandomParameters params)`	Перезапускает этот случайный объект с заданным семенем.
`void`	`setSeed(byte[] seed)`	Перезапускает этот случайный объект, используя восемь байтов, содержащихся в данном `long seed`.
`void`	`setSeed(long seed)`	Возвращает строковое представление этого объекта `SecureRandom`, понятное для человека.

Методы, объявленные в классе java.util.Random

doubles, doubles, doubles, doubles, ints, ints, ints, ints, longs, longs, longs, longs, nextBoolean, nextDouble, nextFloat, nextGaussian, nextInt, nextInt, nextLong

Методы, объявленные в классе java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Методы, объявленные в интерфейсе java.util.random.RandomGenerator

isDeprecated, nextDouble, nextDouble, nextExponential, nextFloat, nextFloat, nextGaussian, nextInt, nextLong, nextLong

Подробное описание конструкторов

SecureRandom

public SecureRandom()

Создаёт генератор псевдослучайных чисел (RNG), реализующий алгоритм по умолчанию.

Этот конструктор проходит по списку зарегистрированных поставщиков безопасности, начиная с наиболее предпочтительного. Возвращает новый объект SecureRandom, encapsulating реализацию SecureRandomSpi из первого поставщика, поддерживающего алгоритм SecureRandom (RNG). Если ни один из поставщиков не поддерживает алгоритм RNG, возвращается значение по умолчанию, специфичное для реализации.

Обратите внимание, что список зарегистрированных поставщиков можно получить с помощью метода Security.getProviders().

См. раздел SecureRandom в Спецификации Java Security Standard Algorithm Names для получения информации о стандартных именах алгоритмов RNG.

SecureRandom

public SecureRandom(byte[] seed)

Создаёт генератор псевдослучайных чисел (RNG), реализующий алгоритм по умолчанию. Экземпляр SecureRandom инициализируется заданными байтами.

Параметры:: seed - seed.

SecureRandom

protected SecureRandom(SecureRandomSpi secureRandomSpi, Provider provider)

Создаёт объект SecureRandom.

Параметры:: secureRandomSpi - реализация SecureRandom.; provider - поставщик.

Подробное описание методов

getInstance

public static SecureRandom getInstance(String algorithm) throws NoSuchAlgorithmException

Возвращает объект SecureRandom, реализующий указанный алгоритм генератора псевдослучайных чисел (RNG).

Этот метод проходит по списку зарегистрированных поставщиков безопасности, начиная с наиболее предпочтительного. Возвращает новый объект SecureRandom, encapsulating реализацию SecureRandomSpi из первого поставщика, поддерживающего указанный алгоритм.

Примечание реализации:

Реализация JDK дополнительно использует свойство jdk.security.provider.preferred Security для определения порядка предпочтительных поставщиков для указанного алгоритма. Это может отличаться от порядка поставщиков, возвращаемых методом Security.getProviders().

Параметры:

algorithm - имя алгоритма RNG. См. раздел SecureRandom в Спецификации Java Security Standard Algorithm Names для получения информации о стандартных именах алгоритмов RNG.

Возвращает:

новый объект SecureRandom

Исключения:

NoSuchAlgorithmException - если ни один поставщик не поддерживает реализацию Provider для указанного алгоритма

NullPointerException - если algorithm является null

С:

1.2

См. также:

Provider

getInstance

public static SecureRandom getInstance(String algorithm, String provider) throws NoSuchAlgorithmException, NoSuchProviderException

Возвращает объект SecureRandom, реализующий указанный алгоритм генератора псевдослучайных чисел (RNG).

Возвращает новый объект SecureRandom, encapsulating реализацию SecureRandomSpi от указанного поставщика. Указанный поставщик должен быть зарегистрирован в списке поставщиков безопасности.

Параметры:

provider - имя поставщика.

Возвращает:

новый объект SecureRandom

Исключения:

IllegalArgumentException - если имя поставщика null или пустое

NoSuchAlgorithmException - если реализация SecureRandomSpi для указанного алгоритма недоступна от указанного поставщика

NoSuchProviderException - если указанный поставщик не зарегистрирован в списке поставщиков безопасности

NullPointerException - если algorithm является null

С:

1.2

См. также:

Provider

getInstance

public static SecureRandom getInstance(String algorithm, Provider provider) throws NoSuchAlgorithmException

Возвращает объект SecureRandom, реализующий указанный алгоритм генератора псевдослучайных чисел (RNG).

Возвращает новый объект SecureRandom, encapsulating реализацию SecureRandomSpi из указанного объекта Provider. Обратите внимание, что указанный объект Provider не обязательно должен быть зарегистрирован в списке поставщиков.

Параметры:

provider - поставщик.

Возвращает:

новый объект SecureRandom

Исключения:

IllegalArgumentException - если указанный поставщик null

NoSuchAlgorithmException - если реализация SecureRandomSpi для указанного алгоритма недоступна от указанного объекта Provider

NullPointerException - если algorithm является null

С:

1.4

См. также:

Provider

getInstance

public static SecureRandom getInstance(String algorithm, SecureRandomParameters params) throws NoSuchAlgorithmException

Возвращает объект SecureRandom, реализующий указанный алгоритм генератора псевдослучайных чисел (RNG) и поддерживающий указанный запрос SecureRandomParameters.

Примечание реализации:

Реализация JDK дополнительно использует свойство jdk.security.provider.preferred для определения порядка предпочтительных поставщиков для указанного алгоритма. Это может отличаться от порядка поставщиков, возвращаемых методом Security.getProviders().

Параметры:

params - SecureRandomParameters the newly created SecureRandom object must support.

Возвращает:

новый объект SecureRandom

Исключения:

IllegalArgumentException - если указанные параметры null

NoSuchAlgorithmException - если ни один поставщик не поддерживает реализацию SecureRandomSpi для указанного алгоритма и параметров

NullPointerException - если algorithm является null

С:

См. также:

Provider

getInstance

public static SecureRandom getInstance(String algorithm, SecureRandomParameters params, String provider) throws NoSuchAlgorithmException, NoSuchProviderException

Возвращается новый объект SecureRandom, инкапсулирующий реализацию SecureRandomSpi из указанного провайдера. Указанный провайдер должен быть зарегистрирован в списке провайдеров безопасности.

Обратите внимание, что список зарегистрированных провайдеров можно получить с помощью метода Security.getProviders().

Parameters:

algorithm - имя алгоритма RNG. См. раздел SecureRandom в Спецификации имен стандартных алгоритмов Java Security для получения информации об именах стандартных алгоритмов RNG.

params - SecureRandomParameters, который должен поддерживать создаваемый объект SecureRandom.

provider - имя провайдера.

Returns:

новый объект SecureRandom

Throws:

IllegalArgumentException - если имя провайдера null или пустое, или params null

NoSuchAlgorithmException - если указанный провайдер не поддерживает реализацию SecureRandomSpi для указанного алгоритма и параметров

NoSuchProviderException - если указанный провайдер не зарегистрирован в списке провайдеров безопасности

NullPointerException - если algorithm null

Since:

See Also:

Provider

getInstance

public static SecureRandom getInstance(String algorithm, SecureRandomParameters params, Provider provider) throws NoSuchAlgorithmException

Возвращается новый объект SecureRandom, инкапсулирующий реализацию SecureRandomSpi из указанного объекта Provider объекта. Обратите внимание, что указанный объект Provider не обязательно должен быть зарегистрирован в списке провайдеров.

Parameters:

params - SecureRandomParameters, который должен поддерживать создаваемый объект SecureRandom.

provider - провайдер.

Returns:

новый объект SecureRandom

Throws:

IllegalArgumentException - если указанный провайдер или params null

NullPointerException - если algorithm null

Since:

See Also:

Provider

getProvider

public final Provider getProvider()

Возвращает провайдер данного объекта SecureRandom.

Returns:: провайдер данного объекта SecureRandom.

getAlgorithm

public String getAlgorithm()

Возвращает имя алгоритма, реализованного этим объектом SecureRandom.

Returns:: имя алгоритма или unknown, если имя алгоритма определить невозможно.
Since:: 1.5

toString

public String toString()

Возвращает удобочитаемую строковую форму представления этого объекта SecureRandom.

Overrides:: toString в классе Object
Returns:: строковое представление

getParameters

public SecureRandomParameters getParameters()

Возвращает эффективные параметры SecureRandomParameters для этого экземпляра SecureRandom.

Возвращаемое значение может отличаться от объекта SecureRandomParameters, переданного в метод getInstance, но оно не может изменяться в течение жизненного цикла этого объекта SecureRandom.

Вызывающий код может использовать возвращаемое значение, чтобы узнать, какие функции поддерживает этот объект SecureRandom.

Returns:

эффективные параметры SecureRandomParameters, или null если параметры не использовались.

Since:

See Also:

SecureRandomSpi

setSeed

public void setSeed(byte[] seed)

Переинициализирует этот объект генератора случайных чисел заданным значением. Значение-семя дополняет, а не заменяет, существующее значение-семя. Таким образом, повторяющиеся вызовы гарантируют, что случайность не уменьшается.

Объект PRNG SecureRandom не будет автоматически инициализироваться, если setSeed вызывается до любых вызовов nextBytes или reseed. Вызывающий код должен убедиться, что аргумент seed содержит достаточную энтропию для обеспечения безопасности этого объекта SecureRandom.

Parameters:

seed - значение-семя.

See Also:

getSeed(int)

setSeed

public void setSeed(long seed)

Переинициализирует этот объект генератора случайных чисел, используя восемь байтов, содержащихся в заданном long seed. Значение-семя дополняет, а не заменяет, существующее значение-семя. Таким образом, повторяющиеся вызовы гарантируют, что случайность не уменьшается.

Этот метод определён для совместимости с java.util.Random.

Overrides:

setSeed в классе Random

Parameters:

seed - значение-семя.

See Also:

getSeed(int)

nextBytes

public void nextBytes(byte[] bytes)

Генерирует указанное количество случайных байтов.

Specified by:: nextBytes в интерфейсе RandomGenerator
Overrides:: nextBytes в классе Random
Parameters:: bytes - массив, который будет заполнен случайными байтами.

nextBytes

public void nextBytes(byte[] bytes, SecureRandomParameters params)

Генерирует указанное количество случайных байтов с дополнительными параметрами.

Parameters:: bytes - массив, который будет заполнен случайными байтами; params - дополнительные параметры
Throws:: NullPointerException - если bytes равно null; UnsupportedOperationException - если реализация провайдера не переопределила этот метод; IllegalArgumentException - если params null, некорректное или неподдерживаемое этим объектом SecureRandom
Since:: 9

protected final int next(int numBits)

Генерирует целое число, содержащее указанное количество псевдослучайных битов (справа, с ведущими нулями). Этот метод переопределяет метод java.util.Random, и служит для обеспечения источника случайных битов для всех методов, унаследованных от этого класса (например, nextInt, nextLong, и nextFloat).

Overrides:: next в классе Random
Parameters:: numBits - количество псевдослучайных битов для генерации, где 0 <= numBits <= 32.
Returns:: целое число, содержащее указанное количество псевдослучайных битов (справа, с ведущими нулями).

getSeed

public static byte[] getSeed(int numBytes)

Возвращает указанное количество байтов-семян, вычисленных с использованием алгоритма генерации семян, используемого этим классом для инициализации. Этот вызов можно использовать для инициализации других генераторов случайных чисел.

Этот метод включён только для обратной совместимости. Вызывающий код должен использовать один из альтернативных методов getInstance для получения объекта SecureRandom, а затем вызывать метод generateSeed для получения байтов-семян из этого объекта.

Parameters:

numBytes - количество байтов-семян для генерации.

Returns:

байты-семя.

Throws:

IllegalArgumentException - если numBytes отрицательное

See Also:

setSeed(byte[])

generateSeed

public byte[] generateSeed(int numBytes)

Parameters:: numBytes - количество байтов-семян для генерации.
Returns:: байты-семя.
Throws:: IllegalArgumentException - если numBytes отрицательное

getInstanceStrong

public static SecureRandom getInstanceStrong() throws NoSuchAlgorithmException

Возвращает объект SecureRandom, выбранный с помощью алгоритмов/поставщиков, указанных в свойстве


 securerandom.strongAlgorithms

Security.

В некоторых ситуациях требуются сильные случайные значения, например, при создании секретов высокой важности/длительного срока действия, таких как ключи RSA public/private. Для помощи приложениям в выборе подходящей сильной SecureRandom реализации, в дистрибутивах Java имеется список известных сильных SecureRandom реализаций в свойстве securerandom.strongAlgorithms Security.

Каждая реализация платформы Java обязана поддерживать, по меньшей мере, одну сильную SecureRandom реализацию.

Возвращает:

реализация сильной SecureRandom , как указано в свойстве securerandom.strongAlgorithms Security

Исключения:

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

© 1993, 2021, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/security/SecureRandom.html