模块 java.base

包 javax.crypto

类 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 安全标准算法名称规范的 密钥协议部分 中进行了描述。请查阅您的实施的发布文档以查看是否支持任何其他算法。

自从：

1.4

参见：

• KeyGenerator
• SecretKey

构造方法总结

构造方法

修饰符	构造方法	描述
protected	KeyAgreement(KeyAgreementSpi keyAgreeSpi, Provider provider, String algorithm)	创建一个 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 对象的算法名称。

这与在创建此 KeyAgreement 对象的 getInstance 调用之一中指定的名称相同。

返回：

此 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 - 请求的密钥协商算法的标准名称。有关标准算法名称的信息，请参阅 Java 安全标准算法名称规范 中的 KeyAgreement 部分。

返回：

新的 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 - 请求的密钥协商算法的标准名称。有关标准算法名称的信息，请参阅 Java 安全标准算法名称规范 中的 KeyAgreement 部分。

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 - 请求的密钥协商算法的标准名称。有关标准算法名称的信息，请参阅 Java 安全标准算法名称规范 中的 KeyAgreement 部分。

provider - 提供商。

返回：

新的 KeyAgreement 对象

抛出：

IllegalArgumentException - 如果 provider 是 null

NoSuchAlgorithmException - 如果无法从指定的 Provider 对象获得指定算法的 KeyAgreementSpi 实现

NullPointerException - 如果 algorithm 是 null

参见：

• 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 - 随机源

抛出：

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 - 随机源

抛出：

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

InvalidAlgorithmParameterException - 如果给定的参数不适合此密钥协议。

doPhase

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

参与此密钥协议的其他方之一收到的给定密钥执行此密钥协议的下一阶段。

参数：

key - 此阶段的关键。例如，在 2 方之间的 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。在这种情况下，应使用更大的输出缓冲区重复此调用。

此方法将此 KeyAgreement 对象重置为它在最近一次调用 init 方法之一后所处的状态。调用 generateSecret 后，可以通过调用 doPhase 提供新密钥，然后调用 generateSecret 生成新密钥，将对象重新用于进一步的密钥协商操作。在这种情况下，提供给init的私有信息和算法参数将用于多个密钥协商操作。在generateSecret之后可以调用init方法来改变后续操作中使用的私有信息。

参数：

sharedSecret - 共享秘密的缓冲区

offset - sharedSecret 中将存储共享秘密的偏移量

返回：

放入 sharedSecret 的字节数

抛出：

IllegalStateException - 如果此密钥协议尚未初始化，或者如果尚未调用 doPhase 为协议中的各方提供密钥

ShortBufferException - 如果给定的输出缓冲区太小而无法保存秘密

generateSecret

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

创建共享机密并将其作为指定算法的 SecretKey 对象返回。

此方法将此 KeyAgreement 对象重置为它在最近一次调用 init 方法之一后所处的状态。调用 generateSecret 后，可以通过调用 doPhase 提供新密钥，然后调用 generateSecret 生成新密钥，将对象重新用于进一步的密钥协商操作。在这种情况下，提供给init的私有信息和算法参数将用于多个密钥协商操作。在generateSecret之后可以调用init方法来改变后续操作中使用的私有信息。

参数：

algorithm - 请求的密钥算法

返回：

共享密钥

抛出：

IllegalStateException - 如果此密钥协议尚未初始化，或者如果尚未调用 doPhase 为协议中的各方提供密钥

NoSuchAlgorithmException - 如果指定的密钥算法不可用

InvalidKeyException - 如果共享密钥材料不能用于生成指定算法的密钥（例如，密钥材料太短）