模块  java.base
软件包  javax.crypto

Class KeyAgreement

  • public class KeyAgreement
extends Object
    此类提供密钥协议（或密钥交换）协议的功能。

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

    对于密钥交换中的每个通讯员，需要调用doPhase 。 例如，如果此密钥交换与另一方进行， doPhase需要调用lastPhase一次，并将lastPhase标志设置为true 。 如果此密钥交换与另外两方进行， doPhase需要调用doPhase两次，第一次将lastPhase标志设置为false ，第二次将其设置为true 。 密钥交换可能涉及任意数量的各方。

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

    • DiffieHellman
    该算法在Java安全标准算法名称规范的KeyAgreement section中描述。 请参阅实现的发行文档，以了解是否支持任何其他算法。
    从以下版本开始：
    1.4
    另请参见：
    KeyGenerator ， SecretKey

    • 构造方法详细信息

      • 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对象，该对象封装了第一个支持指定算法的Provider的KeyAgreementSpi实现。

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

        Implementation Note:
        JDK Reference Implementation另外使用jdk.security.provider.preferred Security属性来确定指定算法的首选提供程序顺序。 这可能与Security.getProviders()返回的提供程序顺序不同。
        参数
        algorithm - 请求的密钥协商算法的标准名称。 看到该协议密钥部分Java Security Standard Algorithm Names Specification有关标准算法名称的信息。
        结果
        新的 KeyAgreement对象
        异常
        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 - 如果给定的参数不适合此密钥协议。

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