javax.crypto

Class KeyAgreement

java.lang.Object

javax.crypto.KeyAgreement

public class KeyAgreement
extends Object

该类提供了密钥协议（或密钥交换）协议的功能。

涉及建立共享秘密的密钥由密钥发生器（ KeyPairGenerator或KeyGenerator ）之一， KeyFactory或由密钥协商协议的中间阶段的结果创建。

对于密钥交换中的doPhase需要调用doPhase 。 例如，如果这个密钥交换是与另一方进行的， doPhase需要被调用一次，其中lastPhase标志设置为true 。 如果这个密钥交换是与另外两个方， doPhase需要被叫两次，首次将lastPhase标志设置为false ，第二次设置为true 。 密钥交换中可能存在任何数量的参与方。

Java平台的每个实现都需要支持以下标准KeyAgreement算法：

• DiffieHellman

该算法在描述KeyAgreement section Java加密体系结构标准算法名称的文档。 请参阅发行说明文件以了解是否支持其他算法。

从以下版本开始：

1.4

另请参见：

KeyGenerator ， SecretKey

构造方法摘要

构造方法

Modifier	Constructor and Description
protected	KeyAgreement(KeyAgreementSpi keyAgreeSpi, Provider provider, String algorithm) 创建一个KeyAgreement对象。

方法摘要

Modifier and Type	Method and Description
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, Provider provider) 返回实现指定的密钥协商算法的 KeyAgreement对象。
static KeyAgreement	getInstance(String algorithm, String provider) 返回实现指定密钥协商算法的 KeyAgreement对象。
Provider	getProvider() 返回此 KeyAgreement对象的提供者。
void	init(Key key) 使用给定的密钥初始化此密钥协议，该密钥需要包含此密钥协议所需的所有算法参数。
void	init(Key key, AlgorithmParameterSpec params) 使用给定的密钥和算法参数集初始化此密钥协议。
void	init(Key key, AlgorithmParameterSpec params, SecureRandom random) 使用给定的密钥，算法参数集合和随机源初始化此密钥协议。
void	init(Key key, SecureRandom random) 用给定的密钥和随机源初始化这个密钥协商。

Methods inherited from class 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对象的算法名称。

这是在创建此KeyAgreement对象的getInstance呼叫之一中指定的getInstance 。

结果

这个 KeyAgreement对象的算法名称。

getInstance

public static final KeyAgreement getInstance(String algorithm)
                                      throws NoSuchAlgorithmException

返回实现指定的密钥协商算法的KeyAgreement对象。

此方法遍历已注册的安全提供程序列表，从最优选的提供程序开始。 返回从支持指定算法的第一个Provider中封装KeyAgreementSpi实现的新KeyAgreement对象。

请注意，可以通过Security.getProviders()方法检索已注册提供商的列表。

参数

algorithm - 所请求的密钥协商算法的标准名称。 看到该协议密钥部分Java Cryptography Architecture Standard Algorithm Name Documentation有关标准算法名称的信息。

结果

新的 KeyAgreement对象。

异常

NullPointerException - 如果指定的算法为空。

NoSuchAlgorithmException - 如果没有提供者支持指定算法的KeyAgreementSpi实现。

另请参见：

Provider

getInstance

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

返回实现指定的密钥协商算法的KeyAgreement对象。

返回从指定提供程序封装KeyAgreementSpi实现的新KeyAgreement对象。 指定的提供者必须在安全提供程序列表中注册。

请注意，可以通过Security.getProviders()方法检索注册提供商的列表。

参数

algorithm - 请求的密钥协商算法的标准名称。 看到该协议密钥部分Java Cryptography Architecture Standard Algorithm Name Documentation有关标准算法名称的信息。

provider - 提供商的名称。

结果

新的 KeyAgreement对象。

异常

NullPointerException - 如果指定的算法为空。

NoSuchAlgorithmException - 如果指定算法的KeyAgreementSpi实现不能从指定的提供者获得。

NoSuchProviderException - 如果指定的提供程序未在安全提供程序列表中注册。

IllegalArgumentException - 如果 provider为空或为空。

另请参见：

Provider

getInstance

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

返回实现指定的密钥协商算法的KeyAgreement对象。

返回从指定的Provider对象封装KeyAgreementSpi实现的新KeyAgreement对象。 请注意，指定的Provider对象不必在提供者列表中注册。

参数

algorithm - 请求密钥协议算法的标准名称。 看到该协议密钥部分Java Cryptography Architecture Standard Algorithm Name Documentation有关标准算法名称的信息。

provider - 提供商。

结果

新的 KeyAgreement对象。

异常

NullPointerException - 如果指定的算法为空。

NoSuchAlgorithmException - 如果指定的算法的KeyAgreementSpi实现从指定的Provider对象不可用。

IllegalArgumentException - 如果 provider为空。

另请参见：

Provider

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 - random的来源

异常

InvalidKeyException - 如果给定的密钥对于该密钥协议是不合适的，例如，是错误的类型或具有不兼容的算法类型。

init

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

使用给定的密钥和算法参数集初始化此密钥协议。

如果此项协议需要随机字节，它会使用让他们SecureRandom实现的最高优先级安装的提供作为随机源。 （如果没有一个已安装的提供商提供SecureRandom的实现，将会使用系统提供的随机源。）

参数

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 - 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方法重新初始化该密钥协议，否则相同的私有信息和算法参数将用于后续密钥协议。

结果

新的缓冲区与共享的秘密

异常

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 - 如果共享的密钥材料不能用于生成指定算法的密钥（例如，密钥材料太短）