Класс KeyAgreement

public class KeyAgreement
extends Object

Этот класс предоставляет функциональность протокола согласования ключей (или обмена ключами).

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

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

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

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

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

Модификатор Конструктор Описание
protected KeyAgreement​(KeyAgreementSpi keyAgreeSpi, Provider provider, String algorithm)

Создаёт объект KeyAgreement.

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

Модификатор и тип Метод Описание
Key doPhase​(Key key, boolean lastPhase)

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

Генерирует общий секрет и возвращает его в новом буфере.
int generateSecret​(byte[] sharedSecret, int offset)

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

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

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

static KeyAgreement getInstance​(String algorithm)

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

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

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

Возвращает поставщика этого объекта KeyAgreement.
void init​(Key key)

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

Инициализирует это согласование ключей заданным ключом и источником случайных чисел.
void init​(Key key, AlgorithmParameterSpec params)

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

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

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

generateSecret

public final byte[] generateSecret()
                            throws IllegalStateException

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

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

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

generateSecret

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

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

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

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

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

generateSecret

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

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

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

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

© 1993, 2020, 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/11/docs/api/java.base/javax/crypto/KeyAgreement.html

Spec-Zone .ru
спецификации, руководства, описания, API