Класс KDF

java.lang.Object

javax.crypto.KDF

public final class KDF extends Object

Этот класс предоставляет функциональность функции выработки ключа (KDF) — криптографического алгоритма для получения дополнительных ключей из исходного ключевого материала (IKM) и (необязательно) других данных.

Объекты KDF создаются с помощью семейства методов getInstance.

В классе есть два метода выработки ключа: deriveKey и deriveData. Метод deriveKey принимает имя алгоритма и возвращает объект SecretKey с указанным алгоритмом. Метод deriveData возвращает массив байтов с необработанными данными.

Пример использования API:

    KDF kdfHkdf = KDF.getInstance("HKDF-SHA256");

    AlgorithmParameterSpec derivationSpec =
             HKDFParameterSpec.ofExtract()
                              .addIKM(ikm)
                              .addSalt(salt).thenExpand(info, 32);

    SecretKey sKey = kdfHkdf.deriveKey("AES", derivationSpec);

Параллельный доступ

Если в документации реализации не указано иное, методы, определённые в этом классе, не являются потокобезопасными. Потоки, которым требуется одновременный доступ к одному объекту, должны синхронизировать свою работу и обеспечивать необходимую блокировку. Потокам, каждый из которых работает с отдельным объектом, синхронизация не требуется.

Отложенный выбор поставщика

Если при вызове одного из методов getInstance поставщик не указан, реализация откладывает его выбор до вызова метода deriveKey или deriveData. Это называется отложенным выбором поставщика. Основная причина такого подхода — убедиться, что выбранный поставщик может обрабатывать ключевой материал, передаваемый этим методам. Например, ключевой материал может находиться на аппаратном устройстве, доступном только определённому поставщику KDF. Метод


 getInstance

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

Если метод getProviderName или getParameters вызван до методов deriveKey или deriveData, выбирается первый поставщик, поддерживающий алгоритм KDF и необязательные KDFParameters. Этот поставщик может не поддерживать ключевой материал, который впоследствии передаётся методам deriveKey или deriveData. Поэтому рекомендуется не вызывать методы getProviderName или getParameters до выполнения операции выработки ключа. После выбора поставщика изменить его нельзя.

Начиная с:

См. также:

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

Модификатор и тип	Метод	Описание
`byte[]`	`deriveData(AlgorithmParameterSpec derivationSpec)`	Вырабатывает ключ и возвращает необработанные данные в виде массива байтов.
`SecretKey`	`deriveKey(String alg, AlgorithmParameterSpec derivationSpec)`	Вырабатывает ключ, возвращаемый в виде объекта `SecretKey`.
`String`	`getAlgorithm()`	Возвращает имя алгоритма этого объекта `KDF`.
`static KDF`	`getInstance(String algorithm)`	Возвращает объект `KDF`, реализующий указанный алгоритм.
`static KDF`	`getInstance(String algorithm, String provider)`	Возвращает объект `KDF`, реализующий указанный алгоритм от указанного поставщика безопасности.
`static KDF`	`getInstance(String algorithm, Provider provider)`	Возвращает объект `KDF`, реализующий указанный алгоритм от указанного поставщика безопасности.
`static KDF`	`getInstance(String algorithm, KDFParameters kdfParameters)`	Возвращает объект `KDF`, реализующий указанный алгоритм и инициализированный заданными параметрами.
`static KDF`	`getInstance(String algorithm, KDFParameters kdfParameters, String provider)`	Возвращает объект `KDF`, реализующий указанный алгоритм от указанного поставщика и инициализированный заданными параметрами.
`static KDF`	`getInstance(String algorithm, KDFParameters kdfParameters, Provider provider)`	Возвращает объект `KDF`, реализующий указанный алгоритм от указанного поставщика и инициализированный заданными параметрами.
`KDFParameters`	`getParameters()`	Возвращает `KDFParameters`, используемые с этим объектом `KDF`.
`String`	`getProviderName()`	Возвращает имя поставщика.

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

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

Модификатор и тип	Метод	Описание
`protected Object`	`clone()`	Создаёт и возвращает копию этого объекта.
`boolean`	`equals(Object obj)`	Показывает, равен ли какой-либо другой объект этому объекту.
`protected void`	`finalize()`	Устарело, будет удалено: этот элемент API может быть удалён в одной из будущих версий. Механизм финализации устарел и будет удалён в одном из следующих выпусков.
`final Class<?>`	`getClass()`	Возвращает класс времени выполнения этого объекта `Object`.
`int`	`hashCode()`	Возвращает хеш-код этого объекта.
`final void`	`notify()`	Пробуждает один поток, ожидающий на мониторе этого объекта.
`final void`	`notifyAll()`	Пробуждает все потоки, ожидающие на мониторе этого объекта.
`String`	`toString()`	Возвращает строковое представление объекта.
`final void`	`wait()`	Заставляет текущий поток ожидать пробуждения, обычно в результате вызова метода notify или interrupt.
`final void`	`wait(long timeoutMillis)`	Заставляет текущий поток ожидать пробуждения, обычно в результате вызова метода notify или interrupt, либо до истечения определённого времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Заставляет текущий поток ожидать пробуждения, обычно в результате вызова метода notify или interrupt, либо до истечения определённого времени.

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

getAlgorithm

public String getAlgorithm()

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

Возвращает:: имя алгоритма этого объекта KDF

getProviderName

public String getProviderName()

Возвращает имя поставщика.

Возвращает:

имя поставщика

См. также:

getParameters

public KDFParameters getParameters()

Возвращает KDFParameters, используемые с этим объектом KDF.

Возвращённые параметры могут совпадать с использованными для инициализации этого объекта KDF либо содержать дополнительные значения параметров по умолчанию или случайные значения, используемые базовым алгоритмом KDF. Если необходимые параметры не были заданы и могут быть сгенерированы объектом KDF, возвращаются сгенерированные параметры; в противном случае возвращается null.

Возвращает:

параметры, использованные с этим объектом KDF, или null

См. также:

getInstance

public static KDF getInstance(String algorithm) throws NoSuchAlgorithmException

Возвращает объект KDF, реализующий указанный алгоритм.

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

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

Параметры:

algorithm — используемый алгоритм выработки ключа. Сведения о стандартных именах алгоритмов KDF см. в разделе KDF документа Спецификация стандартных имён алгоритмов безопасности Java.

Возвращает:

объект KDF

Вызывает исключение:

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

NullPointerException — если algorithm равен null

Внешние спецификации

См. также:

getInstance

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

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

Параметры:

provider — поставщик, используемый для выработки этого ключа

Возвращает:

объект KDF

Вызывает исключение:

NoSuchAlgorithmException — если указанный поставщик не поддерживает указанный алгоритм KDF

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

NullPointerException — если algorithm или provider равен null

Внешние спецификации

getInstance

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

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

Параметры:

provider — поставщик, используемый для выработки этого ключа

Возвращает:

объект KDF

Вызывает исключение:

NoSuchAlgorithmException — если указанный поставщик не поддерживает указанный алгоритм KDF

NullPointerException — если algorithm или provider равен null

Внешние спецификации

getInstance

public static KDF getInstance(String algorithm, KDFParameters kdfParameters) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException

Возвращает объект KDF, реализующий указанный алгоритм и инициализированный заданными параметрами.

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

Параметры:

kdfParameters — KDFParameters, используемые для настройки алгоритма выработки ключа, или null, если параметры не заданы

Возвращает:

объект KDF

Вызывает исключение:

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

InvalidAlgorithmParameterException — если хотя бы один Provider поддерживает реализацию KDF для указанного алгоритма, но ни один из них не поддерживает заданные параметры

NullPointerException — если algorithm равен null

Внешние спецификации

См. также:

getInstance

public static KDF getInstance(String algorithm, KDFParameters kdfParameters, String provider) throws NoSuchAlgorithmException, NoSuchProviderException, InvalidAlgorithmParameterException

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

Параметры:

kdfParameters — KDFParameters, используемые для настройки алгоритма выработки ключа, или null, если параметры не заданы

provider — поставщик, используемый для выработки этого ключа

Возвращает:

объект KDF

Вызывает исключение:

NoSuchAlgorithmException — если указанный поставщик не поддерживает указанный алгоритм KDF

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

InvalidAlgorithmParameterException — если указанный поставщик поддерживает указанный алгоритм KDF, но не поддерживает заданные параметры

NullPointerException — если algorithm или provider равен null

Внешние спецификации

getInstance

public static KDF getInstance(String algorithm, KDFParameters kdfParameters, Provider provider) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException

Возвращает объект KDF, реализующий указанный алгоритм от указанного поставщика и инициализированный заданными параметрами.

Параметры:

kdfParameters — KDFParameters, используемые для настройки алгоритма выработки ключа, или null, если параметры не заданы

provider — поставщик, используемый для выработки этого ключа

Возвращает:

объект KDF

Вызывает исключение:

NoSuchAlgorithmException — если указанный поставщик не поддерживает указанный алгоритм KDF

NullPointerException — если algorithm или provider равен null

Внешние спецификации

deriveKey

public SecretKey deriveKey(String alg, AlgorithmParameterSpec derivationSpec) throws InvalidAlgorithmParameterException, NoSuchAlgorithmException

Вырабатывает ключ, возвращаемый в виде объекта SecretKey.

Параметры:

alg — алгоритм результирующего объекта SecretKey. Сведения о стандартных именах алгоритмов секретных ключей см. в разделе «Алгоритмы SecretKey» документа Спецификация стандартных имён алгоритмов безопасности Java.

derivationSpec — объект, описывающий входные данные функции выработки ключа

Возвращает:

выработанный ключ

Вызывает исключение:

InvalidAlgorithmParameterException — если сведения, содержащиеся в derivationSpec, недействительны или сочетание alg и derivationSpec приводит к недопустимому результату

NoSuchAlgorithmException — если alg пуст или недействителен

NullPointerException — если alg или derivationSpec равен null

Внешние спецификации

См. также:

deriveData

public byte[] deriveData(AlgorithmParameterSpec derivationSpec) throws InvalidAlgorithmParameterException

Вырабатывает ключ и возвращает необработанные данные в виде массива байтов.

Параметры:

derivationSpec — объект, описывающий входные данные функции выработки ключа

Возвращает:

выработанный ключ в виде необработанных байтов

Вызывает исключение:

InvalidAlgorithmParameterException — если сведения, содержащиеся в derivationSpec, недействительны

UnsupportedOperationException — если выработанный ключевой материал нельзя извлечь

NullPointerException — если derivationSpec равен null

См. также:

© 1993, 2025, 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.