Класс 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. Для алгоритма "ECDH" реализации должны поддерживать указанные в скобках кривые.

DiffieHellman
ECDH (secp256r1, secp384r1)
X25519

Эти алгоритмы описаны в разделе KeyAgreement спецификации стандартных имен алгоритмов безопасности Java. Сведения о поддержке других алгоритмов см. в документации к выпуску вашей реализации.

Начиная с:

1.4

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

См. также:

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

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)`	Инициализирует это согласование ключей заданным ключом, набором параметров алгоритма и источником случайных чисел.

Методы, объявленные в классе 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.

Возвращает:

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

Вызывает:

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

NullPointerException — если algorithm имеет значение null

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

См. также:

getInstance

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

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

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

Параметры:

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

Возвращает:

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

Вызывает:

IllegalArgumentException — если provider имеет значение null или является пустым

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 — закрытая информация участника. Например, при согласовании ключей Diffie-Hellman это будет собственный закрытый ключ Diffie-Hellman участника.
Вызывает:: InvalidKeyException — если заданный ключ не подходит для этого согласования ключей, например имеет неверный тип или несовместимый тип алгоритма.

init

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

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

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

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

init

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

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

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

init

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

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

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

doPhase

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

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

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

generateSecret

public final byte[] generateSecret() throws IllegalStateException

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

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

Возвращает:: новый буфер с общим секретом
Вызывает:: 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 — запрашиваемый алгоритм секретного ключа. Он отличается от алгоритма KeyAgreement, переданного методу getInstance. Сведения о стандартных именах алгоритмов секретных ключей см. в разделе «Алгоритмы секретных ключей» спецификации стандартных имен алгоритмов безопасности Java. Укажите "Generic", если результат будет использоваться как исходный ключевой материал для функции выработки ключа (KDF).

Возвращает:

общий секретный ключ. Длина ключевого материала может быть скорректирована для совместимости с указанным алгоритмом независимо от того, допускается ли извлечение ключа. Если в качестве algorithm указано "Generic" и реализация поддерживает это значение, возвращается полный общий секрет.

Вызывает:

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://docs.oracle.com/en/java/javase/25/docs/api/java.base/javax/crypto/KeyAgreement.html