Module  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加密体系结构标准算法名称文档的JSSE Cipher Suite Names部分找到。 提供商可能会支持此列表中找不到密码套件名称。

        参数
        cipherSuites - 密码队列（或null）

      • SSLParameters

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

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

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

    • 方法详细信息

      • getCipherSuites

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

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

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

      • setCipherSuites

        public void setCipherSuites​(String[] cipherSuites)
        设置密码组数组。
        参数
        cipherSuites - 密码队列（或null）。 请注意，密码套件名称的标准列表可以在Java加密体系结构标准算法名称文档的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参数为非空值，那么在SSL / TLS / DTLS握手中使用的每个加密算法，密钥和算法参数都必须被约束所允许。

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

      • setEndpointIdentificationAlgorithm

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

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

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

      • getServerNames

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

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

        对于SSL / TLS / DTLS连接，底层SSL / TLS / DTLS提供程序可以为某个服务器名称类型指定默认值。 在客户端模式下，建议默认情况下，每当服务器可以通过受支持的服务器名称类型定位时，提供程序应包括服务器名称指示。

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

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

      • getSNIMatchers

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

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

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

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

      • setUseCipherSuitesOrder

        public final void setUseCipherSuitesOrder​(boolean honorOrder)
        设置本地密码套件的优先级是否应该被兑现。
        参数
        honorOrder - 在SSL / TLS / DTLS握手期间是否应该履行 #getCipherSuites本地密码 #getCipherSuites订单。
        从以下版本开始：
        1.8
        另请参见：
        getUseCipherSuitesOrder()

      • getUseCipherSuitesOrder

        public final boolean getUseCipherSuitesOrder​()
        返回是否应该遵守本地密码套件的偏好。
        结果
        在SSL / TLS / DTLS握手期间， #getCipherSuites应该在 #getCipherSuites订购本地密码 #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 。 阵列根据协议偏好进行protocols[0] ，最优选protocols[0] 。
        从以下版本开始：
        9
        另请参见：
        setApplicationProtocols(java.lang.String[])

      • setApplicationProtocols

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

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

        如果连接的这个结束期望提供应用协议值，则通过此方法配置的所有协议将被发送到对等体。

        如果连接的这个结束是期望选择应用程序协议值， protocols通过此方法配置的protocols与对等体发送的protocols进行比较。 第一个匹配值成为协商值。 如果对等体实际上没有请求protocols ，底层协议将决定采取什么行动。 （例如，ALPN将发送一个"no_application_protocol"警报并终止连接。）

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