Module java.base
Package javax.crypto

Class 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
参见:

  • Constructor Details

    • KeyAgreement

      protected KeyAgreement(KeyAgreementSpi keyAgreeSpi, Provider provider, String algorithm)
      创建一个KeyAgreement对象。
      参数:
      keyAgreeSpi - 代理
      provider - 提供者
      algorithm - 算法

  • Method Details

    • 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对象
      抛出:
      NoSuchAlgorithmException - 如果没有Provider支持指定算法的KeyAgreementSpi实现
      NullPointerException - 如果algorithm为null
      参见:

    • getInstance

      public static final KeyAgreement getInstance(String algorithm, String provider) throws NoSuchAlgorithmException, NoSuchProviderException
      返回实现指定密钥协商算法的KeyAgreement对象。

      返回一个新的KeyAgreement对象，该对象封装了指定提供者的KeyAgreementSpi实现。指定的提供者必须在安全提供者列表中注册。

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

      参数:
      algorithm - 请求的密钥协商算法的标准名称。有关标准算法名称的信息，请参阅Java安全标准算法名称规范中的密钥协商部分。
      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实现。请注意，指定的提供者不必在提供者列表中注册。

      参数:
      algorithm - 请求的密钥协商算法的标准名称。有关标准算法名称的信息，请参阅Java安全标准算法名称规范中的密钥协商部分。
      provider - 提供者。
      返回:
      新的KeyAgreement对象
      抛出:
      IllegalArgumentException - 如果provider为null
      NoSuchAlgorithmException - 如果指定提供者对象中没有可用于指定算法的KeyAgreementSpi实现
      NullPointerException - 如果algorithm为null
      参见:

    • 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 - 如果共享的秘密密钥材料无法用于生成指定算法的秘密密钥(例如，密钥材料太短)