Module java.base
Package javax.net.ssl

Class 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对象可以通过此类中的构造函数创建，并可以描述为预填充对象。也可以使用SSLContext中的getSSLParameters()方法以及SSLSocket和SSLServerSocket中的getSSLParameters()方法，SSLEngine中的getSSLParameters()方法，getDefaultSSLParameters()和getSupportedSSLParameters()方法获取SSLParameter对象，并可以描述为连接填充对象。

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

例如：

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

  • Constructor Details

    • SSLParameters

      public SSLParameters()
      构造SSLParameters。

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

    • SSLParameters

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

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

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

    • SSLParameters

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

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

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

  • Method Details

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

    • getAlgorithmConstraints

      public AlgorithmConstraints getAlgorithmConstraints()
      返回密码算法约束。
      返回:
      密码算法约束，如果未设置约束，则返回null
      自版本:
      1.7
      参见:

    • setAlgorithmConstraints

      public void setAlgorithmConstraints(AlgorithmConstraints constraints)
      获取端点识别算法。
      Parameters:
      constraints - the algorithm constraints (or null)
      Since:
      1.7

    • getEndpointIdentificationAlgorithm

      public String getEndpointIdentificationAlgorithm()
      Gets the endpoint identification algorithm.
      返回值:
      端点识别算法，如果未设置则返回null。
      自版本:
      1.7
      参见:

    • setEndpointIdentificationAlgorithm

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

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

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

    • setServerNames

      public final void setServerNames(List<SNIServerName> serverNames)
      设置服务器名称指示（SNI）参数的期望SNIServerName列表。

      此方法仅适用于以客户端模式运行的SSLSocket或SSLEngine。

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

      参数:
      serverNames - 期望的SNIServerName列表（或null）
      抛出:
      NullPointerException - 如果serverNames包含null元素
      IllegalArgumentException - 如果serverNames包含相同名称类型的多个名称
      自版本:
      1.8
      参见:

    • getServerNames

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

      此方法仅适用于以客户端模式运行的SSLSocket或SSLEngine。

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

      建议提供程序在创建SSLSocket/SSLEngine时初始化默认的服务器名称指示。在以下示例中，服务器名称可以由已初始化为主机名"www.example.com"和类型StandardConstants.SNI_HOST_NAME的SNIHostName实例表示。

           Socket socket =
         sslSocketFactory.createSocket("www.example.com", 443);
      或 
           SSLEngine engine =
         sslContext.createSSLEngine("www.example.com", 443);
      返回值:
      null或不可变的非nullSNIServerName列表
      自版本:
      1.8
      参见:

    • setSNIMatchers

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

      此方法仅适用于以服务器模式运行的SSLSocket或SSLEngine。

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

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

    • getSNIMatchers

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

      此方法仅适用于以服务器模式运行的SSLSocket或SSLEngine。

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

      返回值:
      null或不可变的非nullSNIMatcher集
      自版本:
      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。
      返回值:
      如果应启用DTLS握手重传，则为true
      自版本:
      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的协议进行协商。

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

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

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

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

     // 0x00-0xFF：1字节
     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 - 如果协议为null，或者非空数组中的任何元素为null或空（长度为零）字符串
      自版本:
      9
      参见:

    • getSignatureSchemes

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

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

      将在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提供程序支持此方法。请注意，应用程序可以使用SunJSSE提供程序的jdk.tls.client.SignatureSchemes和/或jdk.tls.server.SignatureSchemes系统属性来覆盖提供程序特定的默认签名方案。
      返回:
      一个签名方案Strings数组或null（如果未设置任何签名方案）。对于非空返回，每次调用此方法时都将返回一个新数组。数组根据签名方案优先级排序，第一个条目是最优先的。提供程序在建立SSL/TLS/DTLS连接时应忽略未知的签名方案名称。
      自版本:
      19
      参见:

    • setSignatureSchemes

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

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

      将在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安全标准算法名称规范的命名组部分中定义。提供程序可能支持未在此列表中定义的命名组，或者可能不使用某个命名组的推荐名称。

      将在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提供程序支持此方法。请注意，应用程序可以使用SunJSSE提供程序的jdk.tls.namedGroups系统属性来覆盖提供程序特定的默认命名组。
      返回：
      一个密钥交换命名组名称Strings的数组，如果未设置任何值则返回null。对于非null返回值，每次调用此方法时都将返回一个新数组。数组根据命名组偏好排序，第一个条目为最首选项。提供程序在建立SSL/TLS/DTLS连接时应忽略未知的命名组名称。
      自：
      20
      参见：

    • setNamedGroups

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

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

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

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