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

Модификатор и тип	Метод	Описание
`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)`	Переводит текущий поток в состояние ожидания до его пробуждения, обычно в результате вызова уведомления или прерывания, либо до истечения заданного промежутка реального времени.

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

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

doPhase

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

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

Параметры:: key — ключ для этого этапа. Например, при согласовании ключей Диффи — Хеллмана между двумя участниками это будет открытый ключ Диффи — Хеллмана другого участника.; 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. Сведения о стандартных именах алгоритмов секретных ключей см. в разделе SecretKey Algorithms спецификации стандартных имён алгоритмов безопасности 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.