Класс 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 Reference дополнительно использует свойство jdk.security.provider.preferred Security для определения предпочтительного порядка поставщиков для указанного алгоритма. Это может отличаться от порядка поставщиков, возвращаемых методом Security.getProviders().

Параметры:

algorithm - стандартное имя запрашиваемого алгоритма согласования ключей. Справочная информация о стандартных именах алгоритмов содержится в разделе KeyAgreement спецификации Java Security Standard Algorithm Names Specification.

Возвращает:

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

Исключения:

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

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

См. также:

Provider

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

См. также:

Provider

getInstance

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

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

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

Параметры:

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

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

Параметры:: 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 - ключ для этой фазы. Например, в случае Диффи-Хеллмана между 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, 2021, 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/17/docs/api/java.base/javax/crypto/KeyAgreement.html