Класс SecureRandom
- java.lang.Object
-
- java.util.Random
-
- java.security.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) | Создаёт объект |
Методы
| Модификатор и тип | Метод | Описание |
|---|---|---|
byte[] | generateSeed(int numBytes) | Возвращает заданное количество байтов начального значения, вычисленных с использованием алгоритма генерации начального значения, используемого этим классом для инициализации самого себя. |
String | getAlgorithm() | Возвращает имя алгоритма, реализованного этим объектом |
static SecureRandom | getInstance(String algorithm) | Возвращает объект |
static SecureRandom | getInstance(String algorithm,
String provider) | Возвращает объект |
static SecureRandom | getInstance(String algorithm,
Provider provider) | Возвращает объект |
static SecureRandom | getInstance(String algorithm,
SecureRandomParameters params) | Возвращает объект |
static SecureRandom | getInstance(String algorithm,
SecureRandomParameters params,
String provider) | Возвращает объект |
static SecureRandom | getInstance(String algorithm,
SecureRandomParameters params,
Provider provider) | Возвращает объект |
static SecureRandom | getInstanceStrong() | Возвращает объект |
SecureRandomParameters | getParameters() | Возвращает эффективный |
Provider | getProvider() | Возвращает поставщика этого объекта |
static byte[] | getSeed(int numBytes) | Возвращает заданное количество байтов начального значения, вычисленных с использованием алгоритма генерации начального значения, используемого этим классом для инициализации самого себя. |
protected int | next(int numBits) | Генерирует целое число, содержащее заданное количество псевдослучайных битов (справа, с ведущими нулями). |
void | nextBytes(byte[] bytes) | Генерирует заданное количество случайных байтов. |
void | nextBytes(byte[] bytes,
SecureRandomParameters params) | Генерирует заданное количество случайных байтов с дополнительными параметрами. |
void | reseed() | Переинициализирует этот объект |
void | reseed(SecureRandomParameters params) | Переинициализирует этот объект |
void | setSeed(byte[] seed) | Переинициализирует этот объект с заданным начальным значением. |
void | setSeed(long seed) | Переинициализирует этот объект, используя восемь байтов, содержащихся в указанном |
String | toString() | Возвращает строковое представление этого объекта |
Методы, унаследованные от класса 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.preferredSecurityдля определения предпочтительного порядка поставщиков для указанного алгоритма. Это может отличаться от порядка поставщиков, возвращаемого методом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()
Возвращает строковое представление этого объекта в удобочитаемом формате.
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.strongAlgorithmsSecurity - Исключения:
-
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