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

Вызывающая сторона получает экземпляр 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);

Новый созданный объект PRNG 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`, реализующий указанный алгоритм генератора псевдослучайных чисел (RNG) и поддерживающий указанную `SecureRandomParameters` заявку.
`static SecureRandom`	`getInstanceStrong()`	Возвращает объект `SecureRandom`, выбранный с помощью алгоритмов/поставщиков, указанных в `securerandom.strongAlgorithms` `Security` свойстве.
`SecureRandomParameters`	`getParameters()`	Возвращает эффективные параметры `SecureRandomParameters` для этого экземпляра `SecureRandom`.
`final Provider`	`getProvider()`	Возвращает поставщика этого объекта `SecureRandom`.
`static byte[]`	`getSeed(int numBytes)`	Возвращает заданное количество байтов семян, вычисленных с использованием алгоритма генерации семян, используемого этим классом для собственного посева.
`protected final int`	`next(int numBits)`	Генерирует целое число, содержащее указанное пользователем количество псевдослучайных битов (выровненных вправо, с ведущими нулями).
`void`	`nextBytes(byte[] bytes)`	Генерирует заданное пользователем количество случайных байтов.
`void`	`nextBytes(byte[] bytes, SecureRandomParameters params)`	Генерирует заданное пользователем количество случайных байтов с дополнительными параметрами.
`void`	`reseed()`	Перезапускает этот объект `SecureRandom` с использованием входных данных энтропии, считываемых из его источника энтропии.
`void`	`reseed(SecureRandomParameters params)`	Перезапускает этот объект `SecureRandom` с использованием входных данных энтропии, считываемых из его источника энтропии с дополнительными параметрами.
`void`	`setSeed(byte[] seed)`	Перезапускает этот случайный объект с заданным семенем.
`void`	`setSeed(long seed)`	Перезапускает этот случайный объект, используя восемь байтов, содержащихся в данном `long seed`.
`String`	`toString()`	Возвращает удобочитаемое строковое представление этого объекта `SecureRandom`.

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

doubles, doubles, doubles, doubles, from, 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()

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

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

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

См. раздел SecureRandom в спецификации имён стандартных алгоритмов Java Security по спецификации имён стандартных алгоритмов Java Security для получения информации о стандартных именах алгоритмов ГПСЧ.

SecureRandom

public SecureRandom(byte[] seed)

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

Параметры:: seed - начальное значение.
Исключения:: NullPointerException - если seed является null

SecureRandom

protected SecureRandom(SecureRandomSpi secureRandomSpi, Provider provider)

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

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

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

getInstance

public static SecureRandom getInstance(String algorithm) throws NoSuchAlgorithmException

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

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

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

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

Параметры:

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

Возвращаемое значение:

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

Исключения:

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

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

С момента:

1.2

См. также:

getInstance

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

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

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

Параметры:

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

Возвращаемое значение:

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

Исключения:

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

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

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

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

С момента:

1.2

См. также:

getInstance

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

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

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

Параметры:

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

Возвращаемое значение:

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

Исключения:

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

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

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

С момента:

1.4

См. также:

getInstance

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

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

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

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

Параметры:

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

Возвращаемое значение:

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

Исключения:

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

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

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

С момента:

См. также:

getInstance

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

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

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

Parameters:

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

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

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

Returns:

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

Throws:

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

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

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

NullPointerException - если algorithm null

Since:

See Also:

getInstance

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

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

Parameters:

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

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

Returns:

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

Throws:

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

NullPointerException - если algorithm null

Since:

See Also:

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:

setSeed

public void setSeed(byte[] seed)

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

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

Parameters:

seed - зерно.

Throws:

NullPointerException - если seed null

See Also:

setSeed

public void setSeed(long seed)

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

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

Overrides:

setSeed в классе Random

Parameters:

seed - зерно.

See Also:

nextBytes

public void nextBytes(byte[] bytes)

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

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

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:

END_OF_DOCUMENT_MARKER

generateSeed

public byte[] generateSeed(int numBytes)

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

Параметры:: numBytes - количество байтов семян для генерации.
Возвращает:: байты семян.
Выбрасывает:: 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

См. также:

reseed

public void reseed()

Переинициализирует этот SecureRandom с входными данными энтропии, считанными из его источника энтропии.

Выбрасывает:: UnsupportedOperationException - если реализация базового провайдера не переопределила этот метод.
С тех пор:: 9

reseed

public void reseed(SecureRandomParameters params)

Переинициализирует этот SecureRandom с входными данными энтропии, считанными из его источника энтропии с дополнительными параметрами.

Обратите внимание, что энтропия извлекается из источника энтропии. Хотя некоторые данные в params могут содержать энтропию, его основное использование заключается в предоставлении разнообразия.

Параметры:: params - дополнительные параметры
Выбрасывает:: UnsupportedOperationException - если реализация базового провайдера не переопределила этот метод.; IllegalArgumentException - если params является null, некорректным или неподдерживаемым этим SecureRandom
С тех пор:: 9

© 1993, 2023, 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/21/docs/api/java.base/java/security/SecureRandom.html