Класс 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

Этот алгоритм описан в разделе Ключи согласования спецификации стандартных имен алгоритмов безопасности Java. Обратитесь к документации выпуска вашей реализации, чтобы узнать, какие другие алгоритмы поддерживаются.

Since:

1.4

See Also:

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

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 для указанного алгоритма

NullPointerException - если algorithm является null

См. также:

getInstance

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

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

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

Параметры:

provider - имя поставщика.

Возвращает:

новый объект KeyAgreement

Исключения:

IllegalArgumentException - если provider пустое или пустое

NoSuchAlgorithmException - если реализация KeyAgreementSpi для указанного алгоритма недоступна от указанного поставщика

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

NullPointerException - если algorithm является null

См. также:

getInstance

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

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

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

Параметры:

provider - поставщик.

Возвращает:

новый объект KeyAgreement

Исключения:

IllegalArgumentException - если provider является null

NoSuchAlgorithmException - если реализация KeyAgreementSpi для указанного алгоритма недоступна от указанного объекта Provider

NullPointerException - если algorithm является null

См. также:

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

Инициализирует это согласование ключей с заданным ключом и набором параметров алгоритма.

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

init

public final void init(Key key, AlgorithmParameterSpec params, SecureRandom random) throws InvalidKeyException, InvalidAlgorithmParameterException

Инициализирует это согласование ключей с заданным ключом, набором параметров алгоритма и источником случайности.

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

END_OF_DOCUMENT_MARKER

doPhase

public final Key doPhase(Key key, boolean lastPhase) throws InvalidKeyException, IllegalStateException

Выполняет следующий этап этого соглашения о ключах с заданным ключом, полученным от одной из других сторон, участвующих в этом соглашении о ключах.

Параметры:: key - ключ для этого этапа. Например, в случае Диффи-Хеллмана между 2 сторонами это будет открытый ключ Диффи-Хеллмана другой стороны.; lastPhase - флаг, указывающий, является ли это последним этапом этого соглашения о ключах.
Возвращает:: полученный (промежуточный) ключ в результате этого этапа или null, если этот этап не приводит к ключу
Издает исключения:: InvalidKeyException - если заданный ключ не подходит для этого этапа.; IllegalStateException - если это соглашение о ключах не было инициализировано.

generateSecret

public final byte[] generateSecret() throws IllegalStateException

Генерирует общий секрет и возвращает его в новом буфере.

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

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

generateSecret

public final int generateSecret(byte[] sharedSecret, int offset) throws IllegalStateException, ShortBufferException

Генерирует общий секрет и помещает его в буфер sharedSecret, начиная с позиции offset включительно.

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

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

generateSecret

public final SecretKey generateSecret(String algorithm) throws IllegalStateException, NoSuchAlgorithmException, InvalidKeyException

Создает общий секрет и возвращает его как объект SecretKey указанного алгоритма.

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

© 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.
https://download.java.net/java/early_access/jdk24/docs/api/java.base/javax/crypto/KeyAgreement.html