模块 java.base
包 javax.net.ssl

类 SSLParameters

java.lang.Object
javax.net.ssl.SSLParameters
public class SSLParameters extends Object
封装 SSL/TLS/DTLS 连接的参数。参数是在 SSL/TLS/DTLS 握手中接受的密码套件列表、允许的协议列表、SSL/TLS/DTLS 握手期间的端点识别算法、服务名称指示 (SNI)、最大网络数据包大小、算法约束、签名方案、密钥交换命名组以及 SSL/TLS/DTLS 服务是否应该请求或要求客户端身份验证等。

SSLParameter 对象可以通过此类中的构造函数创建，并且可以描述为预填充对象。 SSLParameter 对象也可以使用 SSLSocket 和 SSLServerSocket 和 SSLEngine 中的 getSSLParameters() 方法或 SSLContext 中的 getDefaultSSLParameters() 和 getSupportedSSLParameters() 方法获得，并且可以描述为连接填充对象。

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
参见：

  • 构造方法详细信息

    • SSLParameters

      public SSLParameters()
      构造 SSLParameters。

      cipherSuites、协议、密码算法约束、端点识别算法、签名方案、服务名称和服务名称匹配器的值设置为 null ； useCipherSuitesOrder、wantClientAuth 和 needClientAuth 设置为 false ； enableRetransmissions 设置为 true ；最大网络数据包大小设置为 0 。

    • SSLParameters

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

      调用此构造函数等同于调用后跟 setCipherSuites(cipherSuites); 的无参数构造函数。请注意，密码套件名称的标准列表可以在 Java 安全标准算法名称规范的 JSSE 密码套件名称 部分找到。提供商可能支持此list中未找到的密码套件名称。

      参数：
      cipherSuites - 密码套件数组（或 null）

    • SSLParameters

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

      调用此构造函数等同于调用后跟 setCipherSuites(cipherSuites); setProtocols(protocols); 的无参数构造函数。请注意，密码套件名称的标准列表可以在 Java 安全标准算法名称规范的 JSSE 密码套件名称 部分找到。提供商可能支持此list中未找到的密码套件名称。

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

  • 方法详情

    • getCipherSuites

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

      返回的数组包括来自 Java 安全标准算法名称规范的 JSSE 密码套件名称 部分中的标准密码套件名称列表的密码套件，并且还可能包括提供程序支持的其他密码套件。

      返回：
      密码套件数组的副本；如果未设置，则为 null。

    • setCipherSuites

      public void setCipherSuites(String [] cipherSuites)
      设置密码组数组。
      参数：
      cipherSuites - 密码套件数组（或 null）。请注意，密码套件名称的标准列表可以在 Java 安全标准算法名称规范的 JSSE 密码套件名称 部分找到。提供商可能支持未在此list中找到的密码套件名称，或者可能不使用某个密码套件的推荐名称。

    • 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 - 是否需要客户端身份验证

    • getAlgorithmConstraints

      public AlgorithmConstraints  getAlgorithmConstraints()
      返回密码算法约束。
      返回：
      加密算法约束，如果未设置约束，则为 null
      自从：
      1.7
      参见：

    • setAlgorithmConstraints

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

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

      参数：
      constraints - 算法约束（或 null）
      自从：
      1.7

    • getEndpointIdentificationAlgorithm

      public String  getEndpointIdentificationAlgorithm()
      获取终结点标识算法。
      返回：
      端点识别算法，如果未设置则为 null。
      自从：
      1.7
      参见：

    • setEndpointIdentificationAlgorithm

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

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

      参数：
      algorithm - 端点识别算法的标准字符串名称（或 null）。有关标准算法名称的信息，请参阅 Java 安全标准算法名称 文档。
      自从：
      1.7
      参见：

    • setServerNames

      public final void setServerNames(List <SNIServerName > serverNames)
      设置服务名称指示 (SNI) 参数所需的 SNIServerName s。

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

      请注意，克隆 serverNames 列表以防止后续修改。

      参数：
      serverNames - 所需的 SNIServerName 列表（或空）
      抛出：
      NullPointerException - 如果 serverNames 包含 null 元素
      IllegalArgumentException - 如果 serverNames 包含多个相同名称类型的名称
      自从：
      1.8
      参见：

    • getServerNames

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

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

      对于 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
      参见：

    • setSNIMatchers

      public final void setSNIMatchers(Collection <SNIMatcher > matchers)
      设置服务名称指示 (SNI) 参数的 SNIMatcher s。

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

      请注意，克隆 matchers 集合以防止后续修改。

      参数：
      matchers - SNIMatcher 的集合（或 null）
      抛出：
      NullPointerException - 如果 matchers 包含 null 元素
      IllegalArgumentException - 如果 matchers 包含多个相同名称类型的名称
      自从：
      1.8
      参见：

    • getSNIMatchers

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

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

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

      返回：
      null 或非 null SNIMatcher 的不可变集合
      自从：
      1.8
      参见：

    • setUseCipherSuitesOrder

      public final void setUseCipherSuitesOrder(boolean honorOrder)
      设置是否应遵守本地密码套件首选项。
      参数：
      honorOrder - 在 SSL/TLS/DTLS 握手期间，是否应遵守 #getCipherSuites 中的本地密码套件顺序。
      自从：
      1.8
      参见：

    • getUseCipherSuitesOrder

      public final boolean getUseCipherSuitesOrder()
      返回是否应遵守本地密码套件首选项。
      返回：
      在 SSL/TLS/DTLS 握手期间，是否应遵守 #getCipherSuites 中的本地密码套件顺序。
      自从：
      1.8
      参见：

    • setEnableRetransmissions

      public void setEnableRetransmissions(boolean enableRetransmissions)
      设置是否应启用 DTLS 握手重传。此方法仅适用于 DTLS。
      参数：
      enableRetransmissions - true 表示应该启用 DTLS 握手重传； false 表示应该禁用 DTLS 握手重传
      自从：
      9
      参见：

    • getEnableRetransmissions

      public boolean getEnableRetransmissions()
      返回是否应启用 DTLS 握手重传。此方法仅适用于 DTLS。
      返回：
      true，如果应该启用 DTLS 握手重传
      自从：
      9
      参见：

    • setMaximumPacketSize

      public void setMaximumPacketSize(int maximumPacketSize)
      为 SSL/TLS/DTLS 记录设置最大预期网络数据包大小（以字节为单位）。
      API 注意：
      建议如果可能，最大数据包大小不应小于 256 字节，这样小的握手消息（例如 HelloVerifyRequests）就不会碎片化。
      实现注意事项：
      如果最大数据包大小太小而无法保存最少的记录，则实现可能会尝试生成尽可能少的记录。但是，这可能会导致生成的数据包大于最大数据包大小。
      参数：
      maximumPacketSize - 以字节为单位的最大预期网络数据包大小，或 0 使用由底层实现自动指定的隐式大小。
      抛出：
      IllegalArgumentException - 如果 maximumPacketSize 为负。
      自从：
      9
      参见：

    • getMaximumPacketSize

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

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

      返回：
      最大预期网络数据包大小，或者 0 如果使用由底层实现自动指定的隐式大小并且该对象尚未被任何连接填充。
      自从：
      9
      参见：

    • getApplicationProtocols

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

      该数组可以为空（零长度），在这种情况下将不使用协议指示。

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

      返回：
      应用程序协议 String 的非空、长度可能为零的数组。该数组根据协议首选项排序，第一个条目是最首选的。
      自从：
      9
      参见：

    • setApplicationProtocols

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

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

      如果希望连接的这一端提供应用程序协议值，则此方法配置的所有协议都将发送到对等方。

      如果希望连接的这一端选择应用程序协议值，则将此方法配置的protocols与对端发送的那些进行比较。第一个匹配的值成为协商值。如果 protocols 中的任何一个都没有被对等方实际请求，底层协议将决定采取什么行动。 （例如，ALPN 将发送 "no_application_protocol" 警报并终止连接。）

      String 值必须使用对等方期望的网络字节表示来呈现。例如，如果应使用 UTF-8 交换 ALPN String，则应在调用此方法之前将 String 转换为其 byte[] 表示并存储为面向字节的 String。

         // MEETEI MAYEK LETTERS HUK UN I (Unicode 0xabcd->0xabcf): 2 bytes
   byte[] bytes = "\uabcd\uabce\uabcf"
       .getBytes(StandardCharsets.UTF_8);
   String HUK_UN_I = new String(bytes, StandardCharsets.ISO_8859_1);

   // 0x00-0xFF: 1 byte
   String rfc7301Grease8A = "\u008A\u008A";

   SSLParameters p = sslSocket.getSSLParameters();
   p.setApplicationProtocols(new String[] {
       "h2", "http/1.1", rfc7301Grease8A, HUK_UN_I});
   sslSocket.setSSLParameters(p);
      实现要求：
      此方法将复制 protocols 数组。
      参数：
      protocols - 一个有序的应用程序协议数组，protocols[0] 是首选。如果数组为空（零长度），则不会使用协议指示。
      抛出：
      IllegalArgumentException - 如果协议为空，或者非空数组中的任何元素为空或空（零长度）字符串
      自从：
      9
      参见：

    • getSignatureSchemes

      public String [] getSignatureSchemes()
      返回可在 SSL/TLS/DTLS 协议上使用的签名方案名称的优先数组。

      请注意，签名方案名称的标准列表在 Java 安全标准算法名称规范的 签名方案 部分中定义。提供者可能支持未在此list中定义的签名方案，或者可能不使用某个签名方案的推荐名称。

      将在 SSL/TLS/DTLS 连接上使用的签名方案集由此方法返回的数组和底层提供程序特定的默认签名方案决定。

      如果返回的数组是 null ，则将在 SSL/TLS/DTLS 连接上使用底层提供者特定的默认签名方案。

      如果返回的数组为空（零长度），则表示SSL/TLS/DTLS协议的签名方案协商机制关闭，如果某个SSL/ TLS/DTLS 协议。此参数将覆盖底层提供者特定的默认签名方案。

      如果返回的数组不是 null 或为空（零长度），则返回数组中的签名方案将用于 SSL/TLS/DTLS 连接。此参数将覆盖底层提供者特定的默认签名方案。

      如果已调用该方法，则此方法返回传递给 setSignatureSchemes(java.lang.String[]) 的最新值，否则返回连接填充对象的默认签名方案，或 null 预填充对象。

      API 注意：
      请注意，提供程序可能尚未更新以支持此方法，在这种情况下，可能会返回 null 而不是连接填充对象的默认签名方案。
      实现注意事项：
      SunJSSE 提供者支持此方法。请注意，应用程序可以将 jdk.tls.client.SignatureSchemes 和/或 jdk.tls.server.SignatureSchemes 系统属性与 SunJSSE 提供者一起使用，以覆盖提供者特定的默认签名方案。
      返回：
      一组签名方案 Strings 或 null（如果未设置）。对于非空返回，每次调用此方法都会返回一个新数组。该数组根据签名方案偏好排序，第一个条目是最优选的。提供商在建立 SSL/TLS/DTLS 连接时应忽略未知的签名方案名称。
      自从：
      19
      参见：

    • setSignatureSchemes

      public void setSignatureSchemes(String [] signatureSchemes)
      设置可在 SSL/TLS/DTLS 协议上使用的签名方案名称的优先数组。

      请注意，签名方案名称的标准列表在 Java 安全标准算法名称规范的 签名方案 部分中定义。提供者可能支持未在此list中定义的签名方案，或者可能不使用某个签名方案的推荐名称。

      将在 SSL/TLS/DTLS 连接上使用的签名方案集由输入参数 signatureSchemes 数组和底层提供商特定的默认签名方案决定。有关如何在 SSL/TLS/DTLS 连接中使用参数的具体详细信息，请参阅 getSignatureSchemes() 。

      API 注意：
      请注意，提供程序可能尚未更新以支持此方法，在这种情况下可能会忽略已设置的方案。
      实现注意事项：
      SunJSSE 提供者支持这种方法。
      参数：
      signatureSchemes - 签名方案名称的有序数组，第一个条目是最优选的，或 null 。此方法将复制此数组。提供商在建立 SSL/TLS/DTLS 连接时应忽略未知的签名方案名称。
      抛出：
      IllegalArgumentException - 如果 signatureSchemes 数组中的任何元素是 null 或 空白的 。
      自从：
      19
      参见：

    • getNamedGroups

      public String [] getNamedGroups()
      返回可在 SSL/TLS/DTLS 协议上使用的密钥交换命名组名称的优先级数组。

      请注意，密钥交换命名组的标准列表在 Java 安全标准算法名称规范的 命名组 部分中定义。提供商可能支持未在此list中定义的命名组，或者可能不使用某个命名组的推荐名称。

      将在 SSL/TLS/DTLS 连接上使用的命名组集由此方法返回的数组和底层提供程序特定的默认命名组决定。

      如果返回的数组是 null ，那么底层提供者特定的默认命名组将用于 SSL/TLS/DTLS 连接。

      如果返回的数组为空（零长度），则表示关闭了SSL/TLS/DTLS协议的命名组协商机制，如果某个SSL/协议需要协商机制，则可能无法建立连接TLS/DTLS 协议。此参数将覆盖底层提供程序特定的默认名称组。

      如果返回的数组不是 null 或为空（零长度），则返回数组中的命名组将用于 SSL/TLS/DTLS 连接。此参数将覆盖底层提供程序特定的默认命名组。

      如果已调用该方法，则此方法返回传递给 setNamedGroups(java.lang.String[]) 的最新值，否则返回连接填充对象的默认命名组，或 null 预填充对象。

      API 注意：
      请注意，提供程序可能尚未更新以支持此方法，在这种情况下，可能会返回 null 而不是连接填充对象的默认命名组。
      实现注意事项：
      SunJSSE 提供者支持此方法。请注意，应用程序可以将 jdk.tls.namedGroups 系统属性与 SunJSSE 提供者一起使用，以覆盖特定于提供者的默认命名组。
      返回：
      一个名为组名 Strings 或 null 的密钥交换数组（如果未设置）。对于非空返回，每次调用此方法都会返回一个新数组。该数组根据命名的组偏好排序，第一个条目是最优选的。提供者在建立 SSL/TLS/DTLS 连接时应忽略未知的命名组名称。
      自从：
      20
      参见：

    • setNamedGroups

      public void setNamedGroups(String [] namedGroups)
      设置可用于 SSL/TLS/DTLS 协议的密钥交换命名组名称的优先级数组。

      请注意，密钥交换命名组的标准列表在 Java 安全标准算法名称规范的 命名组 部分中定义。提供商可能支持未在此list中定义的命名组，或者可能不使用某个命名组的推荐名称。

      将在 SSL/TLS/DTLS 连接上使用的命名组集由输入参数 namedGroups 数组和底层提供程序特定的默认命名组确定。有关如何在 SSL/TLS/DTLS 连接中使用参数的具体详细信息，请参阅 getNamedGroups() 。

      API 注意：
      请注意，提供程序可能尚未更新以支持此方法，在这种情况下可能会忽略已设置的命名组。
      实现注意事项：
      SunJSSE 提供者支持这种方法。
      参数：
      namedGroups - 名为组名称的密钥交换的有序数组，第一个条目是最优选的，或 null 。此方法将复制此数组。提供者在建立 SSL/TLS/DTLS 连接时应忽略未知的命名组方案名称。
      抛出：
      IllegalArgumentException - 如果 namedGroups 数组中的任何元素重复，则 null 或 空白的 。
      自从：
      20
      参见：