Класс SecureRandom

Все реализованные интерфейсы:
Serializable
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
См. также:
SecureRandomSpi, Random, Сериализованная форма

Конструкторы

Модификатор Конструктор Описание
SecureRandom()

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

SecureRandom​(byte[] seed)

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

protected SecureRandom​(SecureRandomSpi secureRandomSpi, Provider provider)

Создаёт объект 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.

Provider getProvider()

Возвращает поставщика этого объекта SecureRandom.

static byte[] getSeed​(int numBytes)

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

protected 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, 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

Конструкторы

SecureRandom

public SecureRandom()

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

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

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

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

SecureRandom

public SecureRandom(byte[] seed)

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

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

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

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

Parameters:
seed - семя.

SecureRandom

protected SecureRandom(SecureRandomSpi secureRandomSpi,
                       Provider provider)

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

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

Методы

getInstance

public static SecureRandom getInstance(String algorithm)
                                throws NoSuchAlgorithmException

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

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

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

Примечание реализации:
Реализация JDK дополнительно использует свойство jdk.security.provider.preferred Security для определения предпочтительного порядка поставщиков для указанного алгоритма. Это может отличаться от порядка поставщиков, возвращаемого методом Security.getProviders().
Параметры:
algorithm - имя алгоритма ГПЧ. См. раздел SecureRandom в Спецификации имен стандартных алгоритмов Java Security для получения информации об именах стандартных алгоритмов ГПЧ.
Возвращает:
новый объект SecureRandom
Исключения:
NoSuchAlgorithmException - если ни один поставщик Provider не поддерживает реализацию SecureRandomSpi для указанного алгоритма
NullPointerException - если algorithm имеет значение null
С тех пор:
1.2
См. также:
Provider

getInstance

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

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

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

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

Параметры:
algorithm - имя алгоритма ГПЧ. См. раздел SecureRandom в Спецификации имен стандартных алгоритмов Java Security для получения информации об именах стандартных алгоритмов ГПЧ.
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, реализующий указанный алгоритм генератора псевдослучайных чисел (ГПЧ).

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

Параметры:
algorithm - имя алгоритма ГПЧ. См. раздел SecureRandom в Спецификации имен стандартных алгоритмов Java Security для получения информации об именах стандартных алгоритмов ГПЧ.
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, реализующий указанный алгоритм генератора псевдослучайных чисел (ГПЧ) и поддерживающий указанный запрос SecureRandomParameters.

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

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

Примечание реализации:
Реализация JDK дополнительно использует свойство jdk.security.provider.preferred для определения предпочтительного порядка поставщиков для указанного алгоритма. Это может отличаться от порядка поставщиков, возвращаемого методом Security.getProviders().
Параметры:
algorithm - имя алгоритма ГПЧ. См. раздел SecureRandom в Спецификации имен стандартных алгоритмов Java Security для получения информации об именах стандартных алгоритмов ГПЧ.
params - SecureRandomParameters, который должен поддерживать созданный объект SecureRandom.
Возвращает:
новый объект SecureRandom
Исключения:
IllegalArgumentException - если указанный params имеет значение null
NoSuchAlgorithmException - если ни один поставщик не поддерживает реализацию SecureRandomSpi для указанного алгоритма и параметров
NullPointerException - если algorithm имеет значение null
С тех пор:
9
См. также:
Provider

getInstance

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

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

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

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

Параметры:
algorithm - имя алгоритма ГПЧ. См. раздел SecureRandom в Спецификации имен стандартных алгоритмов Java Security для получения информации об именах стандартных алгоритмов ГПЧ.
params - SecureRandomParameters, который должен поддерживать созданный объект SecureRandom.
provider - имя поставщика.
Возвращает:
новый объект SecureRandom
Исключения:
IllegalArgumentException - если имя поставщика null или пустое, или params имеет значение null
NoSuchAlgorithmException - если указанный поставщик не поддерживает реализацию SecureRandomSpi для указанного алгоритма и параметров
NoSuchProviderException - если указанный поставщик не зарегистрирован в списке поставщиков безопасности
NullPointerException - если algorithm имеет значение null
С тех пор:
9
См. также:
Provider

getInstance

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

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

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

Параметры:
algorithm - имя алгоритма ГПЧ. См. раздел SecureRandom в Спецификации имен стандартных алгоритмов Java Security для получения информации об именах стандартных алгоритмов ГПЧ.
params - SecureRandomParameters, который должен поддерживать созданный объект SecureRandom.
provider - поставщик.
Возвращает:
новый объект SecureRandom
Исключения:
IllegalArgumentException - если указанный поставщик или params имеют значение 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()

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

Переопределяет:
toString в классе Object
Возвращает:
строковое представление

getParameters

public SecureRandomParameters getParameters()

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

Возвращаемое значение может отличаться от объекта SecureRandomParameters , переданного в метод getInstance, но оно не может изменяться в течение всего жизненного цикла этого объекта 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 - массив, который будет заполнен случайными байтами.

nextBytes

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

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

Параметры:
bytes - массив, который будет заполнен случайными байтами
params - дополнительные параметры
Исключения:
NullPointerException - если bytes равно null
UnsupportedOperationException - если реализация базового поставщика не переопределила этот метод
IllegalArgumentException - если params равно null, некорректно или не поддерживается этим объектом SecureRandom
С:
9

next

protected final int next(int numBits)

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

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

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, выбранный с помощью алгоритмов/поставщиков, указанных в свойстве securerandom.strongAlgorithms Security.

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

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

Возвращает:
реализацию сильного генератора случайных чисел, указанную свойством 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, 2020, 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/11/docs/api/java.base/java/security/SecureRandom.html

Spec-Zone .ru
спецификации, руководства, описания, API