模块  java.base
软件包  javax.net.ssl

Class SSLParameters

  • public class SSLParameters
extends Object
    封装SSL / TLS / DTLS连接的参数。 参数是SSL / TLS / DTLS握手中可接受的密码组列表，允许的协议列表，SSL / TLS / DTLS握手期间的端点识别算法，服务器名称指示（SNI），最大网络数据包大小，算法约束以及SSL / TLS / DTLS服务器是否应该请求或要求客户端身份验证等。

    可以通过此类中的构造函数创建SSLParameters。 对象也可以使用所获得的getSSLParameters()的方法SSLSocket和SSLServerSocket和SSLEngine或getDefaultSSLParameters()种getSupportedSSLParameters()的方法SSLContext 。

    SSLParameters可以通过方法SSLSocket.setSSLParameters()和SSLServerSocket.setSSLParameters()以及SSLEngine.setSSLParameters()应用于连接。

    例如： 

         SSLParameters p = sslSocket.getSSLParameters();
     p.setProtocols(new String[] { "TLSv1.2" });
     p.setCipherSuites(
         new String[] { "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256", ... });
     p.setApplicationProtocols(new String[] {"h2", "http/1.1"});
     sslSocket.setSSLParameters(p);
    从以下版本开始：
    1.6
    另请参见：
    SSLSocket ， SSLEngine ， SSLContext

    • 构造方法详细信息

      • SSLParameters

        public SSLParameters()
        构造SSLParameters。

        cipherSuites，协议，加密算法约束，端点标识算法，服务器名称和服务器名称匹配器的值设置为null ; useCipherSuitesOrder，wantClientAuth和needClientAuth都设置为false ; enableRetransmissions设置为true ; 最大网络包大小设置为0 。

      • SSLParameters

        public SSLParameters​(String[] cipherSuites)
        从指定的密码组数组构造SSLParameters。

        调用此构造函数等效于调用no-args构造函数，后跟setCipherSuites(cipherSuites); 。 请注意，密码套件名称的标准列表可以在Java Cryptography体系结构标准算法名称文档的JSSE Cipher Suite Names部分中找到。 提供商可能支持此列表中未找到的密码套件名称。

        参数
        cipherSuites - 密码组数组（或null）

      • SSLParameters

        public SSLParameters​(String[] cipherSuites,
                     String[] protocols)
        从指定的密码套件和协议数组构造SSLParameters。

        调用此构造函数等效于调用no-args构造函数，后跟setCipherSuites(cipherSuites); setProtocols(protocols); 。 请注意，密码套件名称的标准列表可以在Java Cryptography Architecture标准算法名称文档的JSSE Cipher Suite Names部分中找到。 提供商可能支持此列表中未找到的密码套件名称。

        参数
        cipherSuites - 密码组数组（或null）
        protocols - 协议数组（或null）

    • 方法详细信息

      • getCipherSuites

        public String[] getCipherSuites()
        返回密码组数组的副本，如果没有设置，则返回null。

        返回的数组包括Java Cryptography体系结构标准算法名称文档的JSSE Cipher Suite Names部分中的标准密码套件名称列表中的密码套件，还可能包括提供程序支持的其他密码套件。

        结果
        密码组数组的副本，如果没有设置则为null。

      • setCipherSuites

        public void setCipherSuites​(String[] cipherSuites)
        设置密码组数组。
        参数
        cipherSuites - 密码套件数组（或null）。 请注意，密码套件名称的标准列表可以在Java Cryptography Architecture标准算法名称文档的JSSE Cipher Suite Names部分中找到。 提供商可能支持此列表中未找到的密码套件名称，或者可能不使用某个密码套件的建议名称。

      • getProtocols

        public String[] getProtocols()
        返回协议数组的副本，如果没有设置，则返回null。
        结果
        协议数组的副本，如果没有设置则为null。

      • setProtocols

        public void setProtocols​(String[] protocols)
        设置协议数组。
        参数
        protocols - 协议数组（或null）

      • getWantClientAuth

        public boolean getWantClientAuth()
        返回是否应该请求客户端身份验证。
        结果
        是否应该请求客户端身份验证。

      • setWantClientAuth

        public void setWantClientAuth​(boolean wantClientAuth)
        设置是否应该请求客户端身份验证。 调用此方法将清除needClientAuth标志。
        参数
        wantClientAuth - 是否应该请求客户端身份验证

      • getNeedClientAuth

        public boolean getNeedClientAuth()
        返回是否需要客户端身份验证。
        结果
        是否需要客户端身份验证。

      • setNeedClientAuth

        public void setNeedClientAuth​(boolean needClientAuth)
        设置是否需要客户端身份验证。 调用此方法将清除wantClientAuth标志。
        参数
        needClientAuth - 是否需要客户端身份验证

      • setAlgorithmConstraints

        public void setAlgorithmConstraints​(AlgorithmConstraints constraints)
        设置加密算法约束，除运行时环境配置的任何约束外，还将使用这些约束。

        如果constraints参数为非null，则约束必须允许SSL / TLS / DTLS握手中使用的每个加密算法，密钥和算法参数。

        参数
        constraints - 算法约束（或null）
        从以下版本开始：
        1.7

      • setEndpointIdentificationAlgorithm

        public void setEndpointIdentificationAlgorithm​(String algorithm)
        设置端点识别算法。

        如果algorithm参数为非null或非空，则必须在SSL / TLS / DTLS握手期间处理端点标识/验证过程。 这是为了防止中间人攻击。

        参数
        algorithm - 端点标识算法的标准字符串名称（或null）。 有关标准算法名称的信息，请参见Java Security Standard Algorithm Names文档。
        从以下版本开始：
        1.7
        另请参见：
        X509ExtendedTrustManager

      • getServerNames

        public final List<SNIServerName> getServerNames()
        返回List，其中包含服务器名称指示（SNI）参数的所有SNIServerName ，如果未设置，则返回null。

        此方法仅对在客户端模式下运行的SSLSocket或SSLEngine有用。

        对于SSL / TLS / DTLS连接，基础SSL / TLS / DTLS提供程序可以为特定服务器名称类型指定默认值。 在客户端模式下，建议默认情况下，只要服务器可以通过支持的服务器名称类型定位，提供程序就应包括服务器名称指示。

        建议供应商创建初始化时默认的服务器名称主治SSLSocket / SSLEngine秒。 在以下示例中，服务器名称可以由SNIHostName的实例表示，该实例已使用主机名“www.example.com”初始化并键入StandardConstants.SNI_HOST_NAME 。 

          Socket socket =
         sslSocketFactory.createSocket("www.example.com", 443);
        要么 
          SSLEngine engine =
         sslContext.createSSLEngine("www.example.com", 443);
        结果
        null或非null SNIServerName的不可变列表
        从以下版本开始：
        1.8
        另请参见：
        List ， setServerNames(List)

      • getSNIMatchers

        public final Collection<SNIMatcher> getSNIMatchers()
        返回Collection，其中包含服务器名称指示（SNI）参数的所有SNIMatcher ，如果未设置，则返回null。

        此方法仅对在服务器模式下运行的SSLSocket s或SSLEngine有用。

        为了获得更好的互操作性，提供商通常不会定义默认匹配器，因此默认情况下服务器将忽略SNI扩展并继续握手。

        结果
        null或非null SNIMatcher的不可变集合
        从以下版本开始：
        1.8
        另请参见：
        SNIMatcher ， setSNIMatchers(Collection)

      • setUseCipherSuitesOrder

        public final void setUseCipherSuitesOrder​(boolean honorOrder)
        设置是否应该遵守本地密码套件首选项。
        参数
        honorOrder - 在SSL / TLS / DTLS握手期间是否应该遵守 #getCipherSuites本地密码套件订单。
        从以下版本开始：
        1.8
        另请参见：
        getUseCipherSuitesOrder()

      • getUseCipherSuitesOrder

        public final boolean getUseCipherSuitesOrder()
        返回是否应该遵守本地密码套件首选项。
        结果
        在SSL / TLS / DTLS握手期间是否应该遵守 #getCipherSuites本地密码套件订单。
        从以下版本开始：
        1.8
        另请参见：
        setUseCipherSuitesOrder(boolean)

      • setEnableRetransmissions

        public void setEnableRetransmissions​(boolean enableRetransmissions)
        设置是否应启用DTLS握手重新传输。 此方法仅适用于DTLS。
        参数
        enableRetransmissions - true表示应启用DTLS握手重传; false表示应禁用DTLS握手重传
        从以下版本开始：
        9
        另请参见：
        getEnableRetransmissions()

      • getEnableRetransmissions

        public boolean getEnableRetransmissions()
        返回是否应启用DTLS握手重新传输。 此方法仅适用于DTLS。
        结果
        如果应启用DTLS握手重传，则为true
        从以下版本开始：
        9
        另请参见：
        setEnableRetransmissions(boolean)

      • setMaximumPacketSize

        public void setMaximumPacketSize​(int maximumPacketSize)
        设置SSL / TLS / DTLS记录的最大预期网络包大小（以字节为单位）。
        API Note:
        建议在可能的情况下，最大数据包大小不应小于256字节，以便小型握手消息（如HelloVerifyRequests）不会碎片化。
        Implementation Note:
        如果最大数据包大小太小而无法保存最小记录，则实现可能会尝试生成尽可能少的记录。 但是，这可能导致生成的数据包大于最大数据包大小。
        参数
        maximumPacketSize - 以字节为单位的最大预期网络包大小，或 0以使用由底层实现自动指定的隐式大小。
        异常
        IllegalArgumentException - 如果 maximumPacketSize为负数。
        从以下版本开始：
        9
        另请参见：
        getMaximumPacketSize()

      • getMaximumPacketSize

        public int getMaximumPacketSize()
        返回SSL / TLS / DTLS记录的最大预期网络包大小（以字节为单位）。
        API Note:
        隐式大小可能不是固定值，尤其是对于DTLS协议实现。
        Implementation Note:
        对于SSL / TLS / DTLS连接，如果未明确配置，则基础提供程序应计算并指定最大预期网络数据包大小的隐式值。 对于任何连接填充对象，此方法永远不应返回0以便应用程序可以检索底层实现的实际隐式大小。

        实现应尝试遵守最大数据包大小配置。 但是，如果最大数据包大小太小而无法保存最小记录，则实现可能会尝试生成尽可能少的记录。 这可能导致生成的数据包大于最大数据包大小。

        结果
        最大预期网络数据包大小，或 0如果使用由底层实现自动指定的隐式大小，并且此对象尚未由任何连接填充。
        从以下版本开始：
        9
        另请参见：
        setMaximumPacketSize(int)

      • getApplicationProtocols

        public String[] getApplicationProtocols()
        返回可通过SSL / TLS / DTLS协议协商的优先级应用程序层协议名称数组。

        该阵列可以是空的（零长度），在这种情况下，将不使用协议指示。

        每次调用此方法时，此方法都将返回一个新数组。

        结果
        一个非空的，可能是零长度的应用协议数组String s。 该阵列是根据协议首选项排序的，最优选的是protocols[0] 。
        从以下版本开始：
        9
        另请参见：
        setApplicationProtocols(java.lang.String[])

      • setApplicationProtocols

        public void setApplicationProtocols​(String[] protocols)
        设置可通过SSL / TLS / DTLS协议协商的应用程序层协议名称的优先级数组。

        如果底层SSL / TLS实现支持应用层协议，则此方法配置哪些值可以通过协议（如RFC 7301 ，应用层协议协商（ALPN））协商。

        如果预期此连接的末端提供应用程序协议值，则此方法配置的所有协议都将发送给对等方。

        如果希望连接的这一端选择应用程序协议值，则将此方法配置的protocols与对等方发送的值进行比较。 第一个匹配的值成为协商值。 如果对等方实际上没有请求protocols ，则基础协议将确定要采取的操作。 （例如，ALPN将发送"no_application_protocol"警报并终止连接。）

        实现要求：
        此方法将复制 protocols数组。
        参数
        protocols - 有序的应用程序协议数组，最优选的是protocols[0] 。 如果数组为空（零长度），则不使用协议指示。
        异常
        IllegalArgumentException - 如果protocols为null，或者非空数组中的任何元素为null或空（零长度）字符串
        从以下版本开始：
        9
        另请参见：
        getApplicationProtocols()