Класс HPKEParameterSpec

java.lang.Object

javax.crypto.spec.HPKEParameterSpec

Все реализуемые интерфейсы:: AlgorithmParameterSpec

public final class HPKEParameterSpec extends Object implements AlgorithmParameterSpec

Этот неизменяемый класс задаёт набор параметров, используемых с Cipher для алгоритма гибридного шифрования с открытым ключом (HPKE). HPKE — это схема шифрования с открытым ключом для шифрования текстов произвольного размера с использованием открытого ключа получателя. Она объединяет механизм инкапсуляции ключа (KEM), функцию выработки ключа (KDF) и шифр аутентифицированного шифрования с дополнительными данными (AEAD).

Стандартное имя алгоритма шифра — "HPKE". В отличие от большинства других шифров, HPKE не задаётся строкой преобразования вида "алгоритм/режим/набивка". Поэтому аргументом Cipher.getInstance должно быть единственное имя алгоритма "HPKE".

В HPKE Cipher отправителя всегда инициализируется открытым ключом получателя в режиме шифрования, а объект Cipher получателя инициализируется его собственным закрытым ключом в режиме расшифрования.

При инициализации шифра HPKE необходимо предоставить объект HPKEParameterSpec.

Статический метод of(int, int, int) возвращает объект HPKEParameterSpec с заданными идентификаторами алгоритмов KEM, KDF и AEAD. Термины «идентификаторы алгоритмов KEM», «идентификаторы алгоритмов KDF» и «идентификаторы алгоритмов AEAD» обозначают соответствующие числовые значения (а именно kem_id, kdf_id и aead_id), определённые в разделе 7 RFC 9180 и поддерживаемые на странице IANA HPKE.

После создания объекта HPKEParameterSpec доступны дополнительные методы для создания новых объектов HPKEParameterSpec с другими параметрами:

Обе стороны могут передать информацию, предоставленную приложением, с помощью метода withInfo(byte[]).
Для аутентификации с использованием предварительно согласованного ключа (mode_psk) обе стороны должны передать этот ключ и его идентификатор с помощью метода withPsk(SecretKey, byte[]).
Для аутентификации с использованием асимметричного ключа (mode_auth) необходимо передать асимметричные ключи с помощью метода withAuthKey(AsymmetricKey). В частности, отправитель должен вызвать этот метод, указав собственный закрытый ключ, а получатель — указав открытый ключ отправителя.
Для аутентификации с использованием предварительно согласованного ключа и асимметричного ключа (mode_auth_psk) необходимо вызвать оба метода — withAuthKey(AsymmetricKey) и withPsk(SecretKey, byte[]) — как описано выше.
В HPKE на этапе KEM согласуется общий секрет, а от отправителя получателю передаётся сообщение инкапсуляции ключа, чтобы получатель мог восстановить общий секрет. На стороне отправителя после инициализации шифра сообщение инкапсуляции ключа можно получить с помощью метода Cipher.getIV(). На стороне получателя это сообщение необходимо передать как часть объекта HPKEParameterSpec, полученного с помощью метода withEncapsulation(byte[]).

Для успешного взаимодействия обе стороны должны использовать одинаковые идентификаторы алгоритмов и передавать одинаковые значения info, psk и psk_id либо соответствующие ключи аутентификации, если они заданы. Подробные сведения о режимах HPKE см. в разделе 5 RFC 9180.

Если шифр HPKE инициализирован без параметров, возникает исключение InvalidKeyException.

При инициализации шифра HPKE, если ни одна реализация HPKE не поддерживает указанный тип ключа, возникает исключение InvalidKeyException. Если ни одна реализация HPKE не принимает указанный HPKEParameterSpec, возникает исключение InvalidAlgorithmParameterException. Например:

Идентификатор алгоритма не поддерживается или не соответствует указанному типу ключа.
На стороне отправителя указано сообщение инкапсуляции ключа.
На стороне получателя не указано сообщение инкапсуляции ключа.
Предпринимается попытка использовать withAuthKey(key) с несовместимым ключом.
Предпринимается попытка использовать withAuthKey(key), но используемый алгоритм KEM не поддерживает mode_auth или mode_auth_psk.

После инициализации отправитель и получатель могут последовательно обрабатывать несколько сообщений, многократно вызывая doFinal, которым при необходимости предшествует один или несколько вызовов updateAAD и update. Каждый вызов doFinal выполняет полную операцию шифрования или расшифрования HPKE с использованием отдельного IV, полученного из внутреннего счётчика последовательности, как указано в разделе 5.2 RFC 9180. На стороне получателя каждый вызов doFinal должен соответствовать ровно одному полному шифротексту, а количество и порядок вызовов должны совпадать с вызовами на стороне отправителя. Это отличается от непосредственного использования шифра AEAD, при котором вызывающий код должен предоставлять новый IV и повторно инициализировать шифр для каждого сообщения. Управляя IV внутри себя, HPKE позволяет обрабатывать несколько сообщений после одной инициализации, обеспечивая при этом уникальность IV и гарантии безопасности AEAD.

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

// Recipient key pair generation
KeyPairGenerator g = KeyPairGenerator.getInstance("X25519");
KeyPair kp = g.generateKeyPair();

// The HPKE sender cipher is initialized with the recipient's public
// key and an HPKEParameterSpec using specified algorithm identifiers
// and application-supplied info.
Cipher senderCipher = Cipher.getInstance("HPKE");
HPKEParameterSpec ps = HPKEParameterSpec.of(
                HPKEParameterSpec.KEM_DHKEM_X25519_HKDF_SHA256,
                HPKEParameterSpec.KDF_HKDF_SHA256,
                HPKEParameterSpec.AEAD_AES_128_GCM)
        .withInfo(HexFormat.of().parseHex("010203040506"));
senderCipher.init(Cipher.ENCRYPT_MODE, kp.getPublic(), ps);

// Retrieve the key encapsulation message (from the KEM step) from
// the sender.
byte[] kemEncap = senderCipher.getIV();

// The HPKE recipient cipher is initialized with its own private key,
// an HPKEParameterSpec using the same algorithm identifiers as used by
// the sender, and the key encapsulation message from the sender.
Cipher recipientCipher = Cipher.getInstance("HPKE");
HPKEParameterSpec pr = HPKEParameterSpec.of(
                HPKEParameterSpec.KEM_DHKEM_X25519_HKDF_SHA256,
                HPKEParameterSpec.KDF_HKDF_SHA256,
                HPKEParameterSpec.AEAD_AES_128_GCM)
        .withInfo(HexFormat.of().parseHex("010203040506"))
        .withEncapsulation(kemEncap);
recipientCipher.init(Cipher.DECRYPT_MODE, kp.getPrivate(), pr);

// Encryption and decryption
byte[] msg = "Hello World".getBytes(StandardCharsets.UTF_8);
byte[] ct = senderCipher.doFinal(msg);
byte[] pt = recipientCipher.doFinal(ct);

assert Arrays.equals(msg, pt);

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

Этот класс определяет константы для некоторых стандартных идентификаторов алгоритмов, например KEM_DHKEM_P_256_HKDF_SHA256, KDF_HKDF_SHA256 и AEAD_AES_128_GCM. Реализация Cipher HPKE может поддерживать все, некоторые или ни один из определённых здесь идентификаторов алгоритмов. Реализация также может поддерживать дополнительные идентификаторы, не перечисленные здесь, включая частные или экспериментальные значения.

Начиная с:

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

Краткое описание полей

Модификатор и тип	Поле	Описание
`static final int`	`AEAD_AES_128_GCM`	Идентификатор алгоритма AEAD для AES-128-GCM, определённый в RFC 9180.
`static final int`	`AEAD_AES_256_GCM`	Идентификатор алгоритма AEAD для AES-256-GCM, определённый в RFC 9180.
`static final int`	`AEAD_CHACHA20_POLY1305`	Идентификатор алгоритма AEAD для ChaCha20Poly1305, определённый в RFC 9180.
`static final int`	`EXPORT_ONLY`	Идентификатор алгоритма AEAD для режима только экспорта, определённый в RFC 9180.
`static final int`	`KDF_HKDF_SHA256`	Идентификатор алгоритма KDF для HKDF-SHA256, определённый в RFC 9180.
`static final int`	`KDF_HKDF_SHA384`	Идентификатор алгоритма KDF для HKDF-SHA384, определённый в RFC 9180.
`static final int`	`KDF_HKDF_SHA512`	Идентификатор алгоритма KDF для HKDF-SHA512, определённый в RFC 9180.
`static final int`	`KEM_DHKEM_P_256_HKDF_SHA256`	Идентификатор алгоритма KEM для DHKEM(P-256, HKDF-SHA256), определённый в RFC 9180.
`static final int`	`KEM_DHKEM_P_384_HKDF_SHA384`	Идентификатор алгоритма KEM для DHKEM(P-384, HKDF-SHA384), определённый в RFC 9180.
`static final int`	`KEM_DHKEM_P_521_HKDF_SHA512`	Идентификатор алгоритма KEM для DHKEM(P-521, HKDF-SHA512), определённый в RFC 9180.
`static final int`	`KEM_DHKEM_X25519_HKDF_SHA256`	Идентификатор алгоритма KEM для DHKEM(X25519, HKDF-SHA256), определённый в RFC 9180.
`static final int`	`KEM_DHKEM_X448_HKDF_SHA512`	Идентификатор алгоритма KEM для DHKEM(X448, HKDF-SHA512), определённый в RFC 9180.

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

Модификатор и тип	Метод	Описание
`int`	`aead_id()`	Возвращает идентификатор алгоритма AEAD.
`AsymmetricKey`	`authKey()`	Возвращает ключ для аутентификации; если ключ отсутствует, возвращает `null`.
`byte[]`	`encapsulation()`	Возвращает копию сообщения инкапсуляции ключа; если сообщение отсутствует, возвращает `null`.
`byte[]`	`info()`	Возвращает копию информации, предоставленной приложением; если она отсутствует, возвращает пустое значение.
`int`	`kdf_id()`	Возвращает идентификатор алгоритма KDF.
`int`	`kem_id()`	Возвращает идентификатор алгоритма KEM.
`static HPKEParameterSpec`	`of(int kem_id, int kdf_id, int aead_id)`	Фабричный метод для создания нового объекта `HPKEParameterSpec` с заданными идентификаторами алгоритмов KEM, KDF и AEAD в режиме `mode_base` с пустым значением `info`.
`SecretKey`	`psk()`	Возвращает предварительно согласованный ключ; если ключ отсутствует, возвращает `null`.
`byte[]`	`psk_id()`	Возвращает копию идентификатора предварительно согласованного ключа; если он отсутствует, возвращает пустое значение.
`HPKEParameterSpec`	`withAuthKey(AsymmetricKey kS)`	Создаёт новый объект `HPKEParameterSpec` с указанным значением ключа аутентификации.
`HPKEParameterSpec`	`withEncapsulation(byte[] encapsulation)`	Создаёт новый объект `HPKEParameterSpec` с указанным значением сообщения инкапсуляции ключа, которое будет использоваться получателем.
`HPKEParameterSpec`	`withInfo(byte[] info)`	Создаёт новый объект `HPKEParameterSpec` с указанным значением `info`.
`HPKEParameterSpec`	`withPsk(SecretKey psk, byte[] psk_id)`	Создаёт новый объект `HPKEParameterSpec` с указанными значениями `psk` и `psk_id`.

Методы, объявленные в классе 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()`	Приостанавливает текущий поток до его пробуждения, обычно в результате уведомления или прерывания.
`final void`	`wait(long timeoutMillis)`	Приостанавливает текущий поток до его пробуждения, обычно в результате уведомления или прерывания, либо до истечения заданного промежутка реального времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Приостанавливает текущий поток до его пробуждения, обычно в результате уведомления или прерывания, либо до истечения заданного промежутка реального времени.

Подробное описание полей

KEM_DHKEM_P_256_HKDF_SHA256

public static final int KEM_DHKEM_P_256_HKDF_SHA256

Идентификатор алгоритма KEM для DHKEM(P-256, HKDF-SHA256), определённый в RFC 9180.

См. также:

KEM_DHKEM_P_384_HKDF_SHA384

public static final int KEM_DHKEM_P_384_HKDF_SHA384

Идентификатор алгоритма KEM для DHKEM(P-384, HKDF-SHA384), определённый в RFC 9180.

См. также:

KEM_DHKEM_P_521_HKDF_SHA512

public static final int KEM_DHKEM_P_521_HKDF_SHA512

Идентификатор алгоритма KEM для DHKEM(P-521, HKDF-SHA512), определённый в RFC 9180.

См. также:

KEM_DHKEM_X25519_HKDF_SHA256

public static final int KEM_DHKEM_X25519_HKDF_SHA256

Идентификатор алгоритма KEM для DHKEM(X25519, HKDF-SHA256), определённый в RFC 9180.

См. также:

KEM_DHKEM_X448_HKDF_SHA512

public static final int KEM_DHKEM_X448_HKDF_SHA512

Идентификатор алгоритма KEM для DHKEM(X448, HKDF-SHA512), определённый в RFC 9180.

См. также:

KDF_HKDF_SHA256

public static final int KDF_HKDF_SHA256

Идентификатор алгоритма KDF для HKDF-SHA256, определённый в RFC 9180.

См. также:

KDF_HKDF_SHA384

public static final int KDF_HKDF_SHA384

Идентификатор алгоритма KDF для HKDF-SHA384, определённый в RFC 9180.

См. также:

KDF_HKDF_SHA512

public static final int KDF_HKDF_SHA512

Идентификатор алгоритма KDF для HKDF-SHA512, определённый в RFC 9180.

См. также:

AEAD_AES_128_GCM

public static final int AEAD_AES_128_GCM

Идентификатор алгоритма AEAD для AES-128-GCM, определённый в RFC 9180.

См. также:

AEAD_AES_256_GCM

public static final int AEAD_AES_256_GCM

Идентификатор алгоритма AEAD для AES-256-GCM, определённый в RFC 9180.

См. также:

AEAD_CHACHA20_POLY1305

public static final int AEAD_CHACHA20_POLY1305

Идентификатор алгоритма AEAD для ChaCha20Poly1305, определённый в RFC 9180.

См. также:

EXPORT_ONLY

public static final int EXPORT_ONLY

Идентификатор алгоритма AEAD для режима только экспорта, определённый в RFC 9180.

См. также:

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

of

public static HPKEParameterSpec of(int kem_id, int kdf_id, int aead_id)

Фабричный метод для создания нового объекта HPKEParameterSpec с заданными идентификаторами алгоритмов KEM, KDF и AEAD в режиме mode_base с пустым значением info.

Параметры:: kem_id — идентификатор алгоритма KEM; должен находиться в диапазоне от 0 до 65535 включительно; kdf_id — идентификатор алгоритма KDF; должен находиться в диапазоне от 0 до 65535 включительно; aead_id — идентификатор алгоритма AEAD; должен находиться в диапазоне от 0 до 65535 включительно
Возвращает:: новый объект HPKEParameterSpec
Выбрасывает:: IllegalArgumentException — если какое-либо входное значение выходит за допустимые пределы (должно находиться в диапазоне от 0 до 65535 включительно).

withInfo

public HPKEParameterSpec withInfo(byte[] info)

Создаёт новый объект HPKEParameterSpec с указанным значением info.

Для обеспечения совместимости раздел 7.2.1 RFC 9180 рекомендует ограничить это значение максимум 64 байтами.

Параметры:: info — информация, предоставленная приложением. Содержимое массива копируется для защиты от последующего изменения.
Возвращает:: новый объект HPKEParameterSpec
Выбрасывает:: NullPointerException — если info имеет значение null; IllegalArgumentException — если info пусто.

withPsk

public HPKEParameterSpec withPsk(SecretKey psk, byte[] psk_id)

Создаёт новый объект HPKEParameterSpec с указанными значениями psk и psk_id.

Согласно разделу 5.1.2 RFC 9180, энтропия предварительно согласованного ключа должна составлять не менее 32 байт. Для обеспечения совместимости раздел 7.2.1 RFC 9180 рекомендует ограничить размер ключа и длину идентификатора максимум 64 байтами.

Параметры:: psk — предварительно согласованный ключ; psk_id — идентификатор предварительно согласованного ключа. Содержимое массива копируется для защиты от последующего изменения.
Возвращает:: новый объект HPKEParameterSpec
Выбрасывает:: NullPointerException — если psk или psk_id имеет значение null; IllegalArgumentException — если psk короче 32 байт или psk_id пусто

withEncapsulation

public HPKEParameterSpec withEncapsulation(byte[] encapsulation)

Создаёт новый объект HPKEParameterSpec с указанным значением сообщения инкапсуляции ключа, которое будет использоваться получателем.

Параметры:: encapsulation — сообщение инкапсуляции ключа. Содержимое массива копируется для защиты от последующего изменения.
Возвращает:: новый объект HPKEParameterSpec
Выбрасывает:: NullPointerException — если encapsulation имеет значение null

withAuthKey

public HPKEParameterSpec withAuthKey(AsymmetricKey kS)

Создаёт новый объект HPKEParameterSpec с указанным значением ключа аутентификации.

Примечание: этот метод не проверяет, поддерживает ли алгоритм KEM mode_auth или mode_auth_psk. Если полученный объект используется для инициализации шифра HPKE в неподдерживаемом режиме, в этот момент будет выброшено исключение InvalidAlgorithmParameterException.

Параметры:: kS — ключ аутентификации
Возвращает:: новый объект HPKEParameterSpec
Выбрасывает:: NullPointerException — если kS имеет значение null

kem_id

public int kem_id()

Возвращает идентификатор алгоритма KEM.

Возвращает:: идентификатор алгоритма KEM

kdf_id

public int kdf_id()

Возвращает идентификатор алгоритма KDF.

Возвращает:: идентификатор алгоритма KDF

aead_id

public int aead_id()

Возвращает идентификатор алгоритма AEAD.

Возвращает:: идентификатор алгоритма AEAD

info

public byte[] info()

Возвращает копию информации, предоставленной приложением; если она отсутствует, возвращает пустое значение.

Возвращает:: копию информации, предоставленной приложением; если она отсутствует, возвращает пустое значение

psk

public SecretKey psk()

Возвращает предварительно согласованный ключ; если ключ отсутствует, возвращает null.

Возвращает:: предварительно согласованный ключ; если ключ отсутствует, возвращает null

psk_id

public byte[] psk_id()

Возвращает копию идентификатора предварительно согласованного ключа; если он отсутствует, возвращает пустое значение.

Возвращает:: копию идентификатора предварительно согласованного ключа; если он отсутствует, возвращает пустое значение

authKey

public AsymmetricKey authKey()

Возвращает ключ для аутентификации; если ключ отсутствует, возвращает null.

Возвращает:: ключ для аутентификации; если ключ отсутствует, возвращает null

encapsulation

public byte[] encapsulation()

Возвращает копию сообщения инкапсуляции ключа; если сообщение отсутствует, возвращает null.

Возвращает:: копию сообщения инкапсуляции ключа; если сообщение отсутствует, возвращает 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.