Spec-Zone.ru › OpenJDK 21

Класс KeyAgreement

java.lang.Object
javax.crypto.KeyAgreement
public class KeyAgreement extends Object
Этот класс предоставляет функциональность протокола согласования ключей (или обмена ключами).

Ключи, участвующие в установлении общего секрета, создаются одним из генераторов ключей (KeyPairGenerator или KeyGenerator), KeyFactory, или в результате промежуточной фазы протокола согласования ключей.

Для каждого из корреспондентов в обмене ключами необходимо вызвать метод doPhase. Например, если этот обмен ключами происходит с одной другой стороной, метод doPhase необходимо вызвать один раз, установив флаг lastPhase в значение true. Если этот обмен ключами происходит с двумя другими сторонами, метод doPhase необходимо вызвать дважды, в первый раз установив флаг lastPhase в значение false, а во второй раз — в значение true. Может быть любое количество сторон, участвующих в обмене ключами. Однако поддержка обмена ключами с более чем двумя сторонами зависит от реализации или определена стандартным алгоритмом согласования ключей.

Каждая реализация Java платформы обязана поддерживать следующие стандартные KeyAgreement алгоритмы:

  • DiffieHellman
Этот алгоритм описан в разделе KeyAgreement спецификации Java Security Standard Algorithm Names. Обратитесь к документации к релизу вашей реализации, чтобы узнать, какие другие алгоритмы поддерживаются.
Since:
1.4
См. также:
  • KeyGenerator
  • SecretKey

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

KeyAgreement(KeyAgreementSpi keyAgreeSpi, Provider provider, String algorithm)
Модификатор Конструктор Описание
protected
Создаёт объект KeyAgreement.

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

Модификатор и тип Метод Описание
final Key doPhase(Key key, boolean lastPhase)
Выполняет следующую фазу этого согласования ключей с заданным ключом, полученным от одной из других сторон, участвующих в этом согласовании ключей.
final byte[] generateSecret()
Генерирует общий секрет и возвращает его в новом буфере.
final int generateSecret(byte[] sharedSecret, int offset)
Генерирует общий секрет и помещает его в буфер sharedSecret, начиная с индекса offset включительно.
final SecretKey generateSecret(String algorithm)
Создаёт общий секрет и возвращает его как объект SecretKey указанного алгоритма.
final String getAlgorithm()
Возвращает имя алгоритма этого объекта KeyAgreement.
static final KeyAgreement getInstance(String algorithm)
Возвращает объект KeyAgreement, реализующий указанный алгоритм согласования ключей.
static final KeyAgreement getInstance(String algorithm, String provider)
Возвращает объект KeyAgreement, реализующий указанный алгоритм согласования ключей.
static final KeyAgreement getInstance(String algorithm, Provider provider)
Возвращает объект KeyAgreement, реализующий указанный алгоритм согласования ключей.
final Provider getProvider()
Возвращает провайдера этого объекта KeyAgreement.
final void init(Key key)
Инициализирует это согласование ключей заданным ключом, который должен содержать все параметры алгоритма, необходимые для этого согласования ключей.
final void init(Key key, SecureRandom random)
Инициализирует это согласование ключей заданным ключом и источником случайности.
final void init(Key key, AlgorithmParameterSpec params)
Инициализирует это согласование ключей заданным ключом и набором параметров алгоритма.
final void init(Key key, AlgorithmParameterSpec params, SecureRandom random)
Инициализирует это согласование ключей заданным ключом, набором параметров алгоритма и источником случайности.

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

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

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

KeyAgreement

protected KeyAgreement(KeyAgreementSpi keyAgreeSpi, Provider provider, String algorithm)
Создаёт объект KeyAgreement.
Параметры:
keyAgreeSpi - делегат
provider - поставщик
algorithm - алгоритм

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

getAlgorithm

public final String getAlgorithm()
Возвращает имя алгоритма для этого объекта KeyAgreement.

Это то же самое имя, которое было указано в одном из вызовов getInstance, создавших этот объект KeyAgreement.

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

getInstance

public static final KeyAgreement getInstance(String algorithm) throws NoSuchAlgorithmException
Возвращает объект KeyAgreement, реализующий указанный алгоритм согласования ключей.

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

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

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

getInstance

public static final KeyAgreement getInstance(String algorithm, String provider) throws NoSuchAlgorithmException, NoSuchProviderException
Возвращает объект KeyAgreement, реализующий указанный алгоритм согласования ключей.

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

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

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

getInstance

public static final KeyAgreement getInstance(String algorithm, Provider provider) throws NoSuchAlgorithmException
Возвращает объект KeyAgreement, реализующий указанный алгоритм согласования ключей.

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

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

getProvider

public final Provider getProvider()
Возвращает поставщика этого объекта KeyAgreement.
Возвращает:
поставщик этого объекта KeyAgreement

init

public final void init(Key key) throws InvalidKeyException
Инициализирует согласование ключей с заданным ключом, который должен содержать все параметры алгоритма, необходимые для этого согласования.

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

Параметры:
key - приватная информация стороны. Например, в случае согласования ключей Диффи-Хеллмана это собственный приватный ключ Диффи-Хеллмана стороны.
Исключения:
InvalidKeyException - если заданный ключ не подходит для этого согласования ключей, например, имеет неправильный тип или несовместимый тип алгоритма.

init

public final void init(Key key, SecureRandom random) throws InvalidKeyException
Инициализирует это согласование ключей с заданным ключом и источником случайности. Заданный ключ должен содержать все параметры алгоритма, необходимые для этого согласования.

Если алгоритму согласования ключей требуются случайные байты, они получаются из заданного источника случайности, random. Однако, если реализация базового алгоритма не требует случайных байтов, random игнорируется.

Параметры:
key - приватная информация стороны. Например, в случае согласования ключей Диффи-Хеллмана это собственный приватный ключ Диффи-Хеллмана стороны.
random - источник случайности
Исключения:
InvalidKeyException - если заданный ключ не подходит для этого согласования ключей, например, имеет неправильный тип или несовместимый тип алгоритма.

init

public final void init(Key key, AlgorithmParameterSpec params) throws InvalidKeyException, InvalidAlgorithmParameterException
Инициализирует это согласование ключей с заданным ключом и набором параметров алгоритма.

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

Параметры:
key - приватная информация стороны. Например, в случае согласования ключей Диффи-Хеллмана это собственный приватный ключ Диффи-Хеллмана стороны.
params - параметры согласования ключей
Исключения:
InvalidKeyException - если заданный ключ не подходит для этого согласования ключей, например, имеет неправильный тип или несовместимый тип алгоритма.
InvalidAlgorithmParameterException - если заданные параметры не подходят для этого согласования ключей.

init

public final void init(Key key, AlgorithmParameterSpec params, SecureRandom random) throws InvalidKeyException, InvalidAlgorithmParameterException
Инициализирует это согласование ключей с заданным ключом, набором параметров алгоритма и источником случайности.
Параметры:
key - приватная информация стороны. Например, в случае согласования ключей Диффи-Хеллмана это собственный приватный ключ Диффи-Хеллмана стороны.
params - параметры согласования ключей
random - источник случайности
Исключения:
InvalidKeyException - если заданный ключ не подходит для этого согласования ключей, например, имеет неправильный тип или несовместимый тип алгоритма.
InvalidAlgorithmParameterException - если заданные параметры не подходят для этого согласования ключей.

doPhase

public final Key doPhase(Key key, boolean lastPhase) throws InvalidKeyException, IllegalStateException
Выполняет следующую фазу этого соглашения о ключах с заданным ключом, полученным от одной из других сторон, участвующих в этом соглашении о ключах.
Parameters:
key - ключ для этой фазы. Например, в случае Диффи-Хеллмана между 2 сторонами это будет открытый ключ Диффи-Хеллмана другой стороны.
lastPhase - флаг, указывающий, является ли эта фаза последней фазой этого соглашения о ключах.
Returns:
полученный (промежуточный) ключ в результате этой фазы или null, если эта фаза не приводит к получению ключа
Throws:
InvalidKeyException - если заданный ключ не подходит для этой фазы.
IllegalStateException - если это соглашение о ключах не было инициализировано.

generateSecret

public final byte[] generateSecret() throws IllegalStateException
Генерирует общий секрет и возвращает его в новом буфере.

Этот метод сбрасывает этот KeyAgreement объект до состояния, в котором он находился после последнего вызова одного из init методов. После вызова generateSecret, объект можно повторно использовать для дальнейших операций по согласованию ключей, вызвав doPhase, чтобы предоставить новые ключи, а затем вызвав generateSecret, чтобы создать новый секрет. В этом случае приватная информация и параметры алгоритма, предоставленные init, будут использоваться для нескольких операций согласования ключей. Метод init можно вызвать после generateSecret, чтобы изменить приватную информацию, используемую в последующих операциях.

Returns:
новый буфер с общим секретом
Throws:
IllegalStateException - если это соглашение о ключах не было инициализировано или если doPhase не был вызван для предоставления ключей для всех участников соглашения

generateSecret

public final int generateSecret(byte[] sharedSecret, int offset) throws IllegalStateException, ShortBufferException
Генерирует общий секрет и помещает его в буфер sharedSecret, начиная с offset включительно.

Если буфер sharedSecret слишком мал для хранения результата, выбрасывается ShortBufferException. В этом случае этот вызов следует повторить с буфером вывода большего размера.

Этот метод сбрасывает этот KeyAgreement объект до состояния, в котором он находился после последнего вызова одного из init методов. После вызова generateSecret, объект можно повторно использовать для дальнейших операций по согласованию ключей, вызвав doPhase, чтобы предоставить новые ключи, а затем вызвав generateSecret, чтобы создать новый секрет. В этом случае приватная информация и параметры алгоритма, предоставленные init, будут использоваться для нескольких операций согласования ключей. Метод init можно вызвать после generateSecret, чтобы изменить приватную информацию, используемую в последующих операциях.

Parameters:
sharedSecret - буфер для общего секрета
offset - смещение в sharedSecret, где будет храниться общий секрет
Returns:
количество байтов, помещенных в sharedSecret
Throws:
IllegalStateException - если это соглашение о ключах не было инициализировано или если doPhase не был вызван для предоставления ключей для всех участников соглашения
ShortBufferException - если предоставленный буфер вывода слишком мал для хранения секрета

generateSecret

public final SecretKey generateSecret(String algorithm) throws IllegalStateException, NoSuchAlgorithmException, InvalidKeyException
Создает общий секрет и возвращает его как SecretKey объект указанного алгоритма.

Этот метод сбрасывает этот KeyAgreement объект до состояния, в котором он находился после последнего вызова одного из init методов. После вызова generateSecret, объект можно повторно использовать для дальнейших операций по согласованию ключей, вызвав doPhase, чтобы предоставить новые ключи, а затем вызвав generateSecret, чтобы создать новый секрет. В этом случае приватная информация и параметры алгоритма, предоставленные init, будут использоваться для нескольких операций согласования ключей. Метод init можно вызвать после generateSecret, чтобы изменить приватную информацию, используемую в последующих операциях.

Parameters:
algorithm - запрашиваемый алгоритм ключа-секрета
Returns:
ключ общего секрета
Throws:
IllegalStateException - если это соглашение о ключах не было инициализировано или если doPhase не был вызван для предоставления ключей для всех участников соглашения
NoSuchAlgorithmException - если указанный алгоритм ключа-секрета недоступен
InvalidKeyException - если материал общего секретного ключа не может быть использован для генерации ключа-секрета указанного алгоритма (например, материал ключа слишком короткий)

© 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/KeyAgreement.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API