Класс KEM

java.lang.Object

javax.crypto.KEM

public final class KEM extends Object

Этот класс предоставляет функциональность механизма инкапсуляции ключей (KEM). KEM можно использовать для защиты симметричных ключей с помощью асимметричной или криптографии с открытым ключом между двумя сторонами. Отправитель вызывает метод encapsulate для генерации секретного ключа и сообщения инкапсуляции ключа, а получатель вызывает метод decapsulate для восстановления того же секретного ключа из сообщения инкапсуляции ключа.

Метод getInstance создаёт новый объект KEM, реализующий указанный алгоритм.

Объект KEM является неизменяемым. Безопасно вызывать несколько методов newEncapsulator и newDecapsulator на одном и том же объекте KEM одновременно.

Если поставщик не указан в методе getInstance при создании объекта KEM, методы newEncapsulator и newDecapsulator могут возвращать инкапсуляторы или деинкапсуляторы из разных поставщиков. Выбранный поставщик определяется параметрами, переданными в методы newEncapsulator или newDecapsulator: приватным или публичным ключом и необязательными AlgorithmParameterSpec. Методы KEM.Encapsulator.providerName() и KEM.Decapsulator.providerName() возвращают имя выбранного поставщика.

Объекты Encapsulator и Decapsulator также являются неизменяемыми. Безопасно вызывать несколько методов encapsulate и decapsulate на одном и том же объекте Encapsulator или Decapsulator одновременно. Каждый вызов encapsulate сгенерирует новый общий секрет и сообщение инкапсуляции ключа.

Пример:

   // Receiver side
   var kpg = KeyPairGenerator.getInstance("X25519");
   var kp = kpg.generateKeyPair();

   // Sender side
   var kem1 = KEM.getInstance("DHKEM");
   var sender = kem1.newEncapsulator(kp.getPublic());
   var encapsulated = sender.encapsulate();
   var k1 = encapsulated.key();

   // Receiver side
   var kem2 = KEM.getInstance("DHKEM");
   var receiver = kem2.newDecapsulator(kp.getPrivate());
   var k2 = receiver.decapsulate(encapsulated.encapsulation());

   assert Arrays.equals(k1.getEncoded(), k2.getEncoded());

С:: 21

Краткое описание вложенных классов

Модификатор и тип	Класс	Описание
`static final class`	`KEM.Decapsulator`	Деинкапсулятор, сгенерированный методом `newDecapsulator(java.security.PrivateKey)` со стороны получателя KEM.
`static final class`	`KEM.Encapsulated`	Этот класс определяет возвращаемое значение метода encapsulate механизма инкапсуляции ключей (KEM), включающее общий секрет (как `SecretKey`), сообщение инкапсуляции ключа и необязательные параметры.
`static final class`	`KEM.Encapsulator`	Инкапсулятор, сгенерированный методом `newEncapsulator(java.security.PublicKey)` со стороны отправителя KEM.

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

Модификатор и тип	Метод	Описание
`String`	`getAlgorithm()`	Возвращает имя алгоритма для данного объекта `KEM`.
`static KEM`	`getInstance(String algorithm)`	Возвращает объект `KEM`, реализующий указанный алгоритм.
`static KEM`	`getInstance(String algorithm, String provider)`	Возвращает объект `KEM`, реализующий указанный алгоритм из указанного поставщика безопасности.
`static KEM`	`getInstance(String algorithm, Provider provider)`	Возвращает объект `KEM`, реализующий указанный алгоритм из указанного поставщика безопасности.
`KEM.Decapsulator`	`newDecapsulator(PrivateKey privateKey)`	Создаёт деинкапсулятор KEM со стороны получателя KEM.
`KEM.Decapsulator`	`newDecapsulator(PrivateKey privateKey, AlgorithmParameterSpec spec)`	Создаёт деинкапсулятор KEM со стороны получателя KEM.
`KEM.Encapsulator`	`newEncapsulator(PublicKey publicKey)`	Создаёт инкапсулятор KEM со стороны отправителя KEM.
`KEM.Encapsulator`	`newEncapsulator(PublicKey publicKey, SecureRandom secureRandom)`	Создаёт инкапсулятор KEM со стороны отправителя KEM.
`KEM.Encapsulator`	`newEncapsulator(PublicKey publicKey, AlgorithmParameterSpec spec, SecureRandom secureRandom)`	Создаёт инкапсулятор KEM со стороны отправителя KEM.

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

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

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

getInstance

public static KEM getInstance(String algorithm) throws NoSuchAlgorithmException

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

Параметры:: algorithm - имя алгоритма KEM. См. раздел KEM в Спецификации имен стандартных алгоритмов Java Security для информации о стандартных именах алгоритмов KEM.
Возвращает:: новый объект KEM
Исключения:: NoSuchAlgorithmException - если ни один Provider не поддерживает реализацию KEM для указанного алгоритма; NullPointerException - если algorithm является null

getInstance

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

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

Параметры:: algorithm - имя алгоритма KEM. См. раздел KEM в Спецификации имен стандартных алгоритмов Java Security для информации о стандартных именах алгоритмов KEM.; provider - поставщик. Если null, этот метод эквивалентен getInstance(String).
Возвращает:: новый объект KEM
Исключения:: NoSuchAlgorithmException - если указан поставщик provider и он не поддерживает указанный алгоритм KEM, или если provider является null и нет поставщика, который поддерживает реализацию KEM указанного алгоритма; NullPointerException - если algorithm является null

getInstance

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

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

Параметры:: algorithm - имя алгоритма KEM. См. раздел KEM в Спецификации имен стандартных алгоритмов Java Security для информации о стандартных именах алгоритмов KEM.; provider - поставщик. Если null, этот метод эквивалентен getInstance(String).
Возвращает:: новый объект KEM
Исключения:: NoSuchAlgorithmException - если указан поставщик provider и он не поддерживает указанный алгоритм KEM, или если provider является null и нет поставщика, который поддерживает реализацию KEM указанного алгоритма; NoSuchProviderException - если указанный поставщик не зарегистрирован в списке поставщиков безопасности; NullPointerException - если algorithm является null

newEncapsulator

public KEM.Encapsulator newEncapsulator(PublicKey publicKey) throws InvalidKeyException

Создает инкапсулятор KEM со стороны отправителя KEM.

Этот метод эквивалентен newEncapsulator(publicKey, null, null).

Параметры:: publicKey - открытый ключ получателя, не должен быть null
Возвращает:: инкапсулятор для этого ключа
Исключения:: InvalidKeyException - если publicKey является null или некорректен; UnsupportedOperationException - если этот метод не поддерживается, так как должен быть предоставлен AlgorithmParameterSpec

newEncapsulator

public KEM.Encapsulator newEncapsulator(PublicKey publicKey, SecureRandom secureRandom) throws InvalidKeyException

Создает инкапсулятор KEM со стороны отправителя KEM.

Этот метод эквивалентен newEncapsulator(publicKey, null, secureRandom).

Параметры:: publicKey - открытый ключ получателя, не должен быть null; secureRandom - источник случайности для инкапсуляции. Если null, будет использован стандартный источник из реализации.
Возвращает:: инкапсулятор для этого ключа
Исключения:: InvalidKeyException - если publicKey является null или некорректен; UnsupportedOperationException - если этот метод не поддерживается, так как должен быть предоставлен AlgorithmParameterSpec

newEncapsulator

public KEM.Encapsulator newEncapsulator(PublicKey publicKey, AlgorithmParameterSpec spec, SecureRandom secureRandom) throws InvalidAlgorithmParameterException, InvalidKeyException

Создает инкапсулятор KEM со стороны отправителя KEM.

Алгоритм может определить подкласс AlgorithmParameterSpec для предоставления дополнительной информации в этом методе. Это особенно полезно, если один и тот же ключ можно использовать для вывода общих секретов различными способами. Если любая дополнительная информация в этом объекте должна передаваться вместе с сообщением инкапсуляции ключа, чтобы получатель мог создать соответствующий декапсулятор, она будет включена в виде массива байтов в поле KEM.Encapsulated.params в выходе инкапсуляции. В этом случае поставщик безопасности должен предоставить реализацию AlgorithmParameters с тем же именем алгоритма, что и KEM. Получатель может инициировать такой экземпляр AlgorithmParameters с полученным массивом байтов params и восстановить объект AlgorithmParameterSpec для использования в вызове newDecapsulator(PrivateKey, AlgorithmParameterSpec).

Параметры:: publicKey - открытый ключ получателя, не должен быть null; spec - необязательный параметр, может быть null; secureRandom - источник случайности для инкапсуляции. Если null, будет использован стандартный источник из реализации.
Возвращает:: инкапсулятор для этого ключа
Исключения:: InvalidAlgorithmParameterException - если spec некорректен или требуется, но spec является null; InvalidKeyException - если publicKey является null или некорректен

newDecapsulator

public KEM.Decapsulator newDecapsulator(PrivateKey privateKey) throws InvalidKeyException

Создает декапсулятор KEM со стороны получателя KEM.

Этот метод эквивалентен newDecapsulator(privateKey, null).

Параметры:: privateKey - закрытый ключ получателя, не должен быть null
Возвращает:: декапсулятор для этого ключа
Исключения:: InvalidKeyException - если privateKey является null или некорректен; UnsupportedOperationException - если этот метод не поддерживается, так как должен быть предоставлен AlgorithmParameterSpec

newDecapsulator

public KEM.Decapsulator newDecapsulator(PrivateKey privateKey, AlgorithmParameterSpec spec) throws InvalidAlgorithmParameterException, InvalidKeyException

Создает декапсулятор KEM со стороны получателя KEM.

Параметры:: privateKey - закрытый ключ получателя, не должен быть null; spec - параметр, может быть null
Возвращает:: декапсулятор для этого ключа
Исключения:: InvalidAlgorithmParameterException - если spec некорректен или требуется, но spec является null; InvalidKeyException - если privateKey является null или некорректен

getAlgorithm

public String getAlgorithm()

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

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

© 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/javax/crypto/KEM.html