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 Summary
ConstructorsConstructorDescription构造SSLParameters。SSLParameters
(String[] cipherSuites) 从指定的密码套件数组构造SSLParameters。SSLParameters
(String[] cipherSuites, String[] protocols) 从指定的密码套件和协议数组构造SSLParameters。 -
Method Summary
Modifier and TypeMethodDescription返回密码算法约束。String[]
返回可以在SSL/TLS/DTLS协议上进行协商的应用层协议名称的优先级数组。String[]
返回密码套件数组的副本,如果未设置,则返回null。boolean
返回是否应启用DTLS握手重传。获取端点识别算法。int
返回SSL/TLS/DTLS记录的最大预期网络数据包大小(以字节为单位)。String[]
返回可以在SSL/TLS/DTLS协议上使用的密钥交换命名组名称的优先级数组。boolean
返回是否应要求客户端身份验证。String[]
返回协议数组的副本,如果未设置,则返回null。final List
<SNIServerName> 返回包含服务器名称指示(SNI)参数的所有SNIServerName
的List
,如果未设置,则返回null。String[]
返回可以在SSL/TLS/DTLS协议上使用的签名方案名称的优先级数组。final Collection
<SNIMatcher> 返回包含服务器名称指示(SNI)参数的所有SNIMatcher
的Collection
,如果未设置,则返回null。final boolean
返回是否应遵守本地密码套件优先级。boolean
返回是否应请求客户端身份验证。void
setAlgorithmConstraints
(AlgorithmConstraints constraints) 设置密码算法约束,这些约束将在运行时环境配置的约束之外使用。void
setApplicationProtocols
(String[] protocols) 设置可以在SSL/TLS/DTLS协议上进行协商的应用层协议名称的优先级数组。void
setCipherSuites
(String[] cipherSuites) 设置密码套件数组。void
setEnableRetransmissions
(boolean enableRetransmissions) 设置是否应启用DTLS握手重传。void
setEndpointIdentificationAlgorithm
(String algorithm) 设置端点识别算法。void
setMaximumPacketSize
(int maximumPacketSize) 设置SSL/TLS/DTLS记录的最大预期网络数据包大小(以字节为单位)。void
setNamedGroups
(String[] namedGroups) 设置可以在SSL/TLS/DTLS协议上使用的密钥交换命名组名称的优先级数组。void
setNeedClientAuth
(boolean needClientAuth) 设置是否应要求客户端身份验证。void
setProtocols
(String[] protocols) 设置协议数组。final void
setServerNames
(List<SNIServerName> serverNames) 设置所需的SNIServerName
的服务器名称指示(SNI)参数。void
setSignatureSchemes
(String[] signatureSchemes) 设置可以在SSL/TLS/DTLS协议上使用的签名方案名称的优先级数组。final void
setSNIMatchers
(Collection<SNIMatcher> matchers) 设置SNIMatcher
的服务器名称指示(SNI)参数。final void
setUseCipherSuitesOrder
(boolean honorOrder) 设置是否应遵守本地密码套件优先级。void
setWantClientAuth
(boolean wantClientAuth) 设置是否应请求客户端身份验证。
-
Constructor Details
-
SSLParameters
public SSLParameters()构造SSLParameters。密码套件、协议、密码算法约束、端点识别算法、签名方案、服务器名称和服务器名称匹配器的值设置为
null
;useCipherSuitesOrder、wantClientAuth和needClientAuth设置为false
;enableRetransmissions设置为true
;最大网络数据包大小设置为0
。 -
SSLParameters
从指定的密码套件数组构造SSLParameters。调用此构造函数等效于调用无参数构造函数,然后调用
setCipherSuites(cipherSuites);
。请注意,标准密码套件名称列表可以在Java安全标准算法名称规范的JSSE Cipher Suite Names部分中找到。提供程序可能支持未在此列表中找到的密码套件名称。- 参数:
-
cipherSuites
- 密码套件数组(或null)
-
SSLParameters
从指定的密码套件和协议数组构造SSLParameters。调用此构造函数等效于调用无参数构造函数,然后调用
setCipherSuites(cipherSuites); setProtocols(protocols);
。请注意,标准密码套件名称列表可以在Java安全标准算法名称规范的JSSE Cipher Suite Names部分中找到。提供程序可能支持未在此列表中找到的密码套件名称。- 参数:
-
cipherSuites
- 密码套件数组(或null) -
protocols
- 协议数组(或null)
-
-
Method Details
-
getCipherSuites
返回密码套件数组的副本,如果未设置,则返回null。返回的数组包括Java安全标准算法名称规范的JSSE Cipher Suite Names部分中的标准密码套件,还可能包括提供程序支持的其他密码套件。
- 返回:
- 密码套件数组的副本,如果未设置,则返回null。
-
setCipherSuites
设置密码套件数组。- 参数:
-
cipherSuites
- 密码套件数组(或null)。请注意,标准密码套件名称列表可以在Java安全标准算法名称规范的JSSE Cipher Suite Names部分中找到。提供程序可能支持未在此列表中找到的密码套件名称,或者可能不使用某个密码套件的推荐名称。
-
getProtocols
返回协议数组的副本,如果未设置,则返回null。- 返回:
- 协议数组的副本,如果未设置,则返回null。
-
setProtocols
设置协议数组。- 参数:
-
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
返回密码算法约束。- 返回:
- 密码算法约束,如果未设置约束,则返回null
- 自版本:
- 1.7
- 参见:
-
setAlgorithmConstraints
获取端点识别算法。- Parameters:
-
constraints
- the algorithm constraints (or null) - Since:
- 1.7
-
getEndpointIdentificationAlgorithm
Gets the endpoint identification algorithm.- 返回值:
- 端点识别算法,如果未设置则返回null。
- 自版本:
- 1.7
- 参见:
-
setEndpointIdentificationAlgorithm
设置端点识别算法。如果
algorithm
参数非null或非空,则在SSL/TLS/DTLS握手期间必须处理端点识别/验证过程。这是为了防止中间人攻击。- 参数:
-
algorithm
- 端点识别算法的标准字符串名称(或null)。有关标准算法名称的信息,请参阅Java安全标准算法名称文档。 - 自版本:
- 1.7
- 参见:
-
setServerNames
设置服务器名称指示(SNI)参数的期望SNIServerName
列表。此方法仅适用于以客户端模式运行的
SSLSocket
或SSLEngine
。请注意,
serverNames
列表会被克隆以防止后续修改。- 参数:
-
serverNames
- 期望的SNIServerName
列表(或null) - 抛出:
-
NullPointerException
- 如果serverNames
包含null
元素 -
IllegalArgumentException
- 如果serverNames
包含相同名称类型的多个名称 - 自版本:
- 1.8
- 参见:
-
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或不可变的非null
SNIServerName
列表 - 自版本:
- 1.8
- 参见:
-
setSNIMatchers
- 参数:
-
matchers
-SNIMatcher
集(或null) - 抛出:
-
NullPointerException
- 如果matchers
包含null
元素 -
IllegalArgumentException
- 如果matchers
包含相同名称类型的多个名称 - 自版本:
- 1.8
- 参见:
-
getSNIMatchers
返回包含服务器名称指示(SNI)参数的所有SNIMatcher
的Collection
,如果未设置则返回null。此方法仅适用于以服务器模式运行的
SSLSocket
或SSLEngine
。为了更好的互操作性,提供程序通常不会定义默认匹配器,以便默认情况下服务器将忽略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。- 返回值:
- 如果应启用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
返回一个可以在SSL/TLS/DTLS协议上进行协商的应用层协议名称的优先级数组。数组可能为空(长度为零),在这种情况下将不使用协议指示。
每次调用此方法时,都将返回一个新数组。
- 返回:
-
一个非空、可能为空(长度为零)的应用程序协议
String
数组。数组根据协议优先级排序,第一个条目是最优先的。 - 自版本:
- 9
- 参见:
-
setApplicationProtocols
设置可以在SSL/TLS/DTLS协议上进行协商的应用层协议名称的优先级数组。如果底层SSL/TLS实现支持应用层协议,则此方法配置协议可以通过诸如RFC 7301的协议进行协商。
如果此连接端期望提供应用程序协议值,则此方法配置的所有协议将发送到对等方。
如果此连接端期望选择应用程序协议值,则此方法配置的
protocols
将与对等方发送的协议进行比较。第一个匹配的值将成为协商的值。如果对等方实际上没有请求任何protocols
,则底层协议将决定采取什么操作。(例如,ALPN将发送一个"no_application_protocol"
警报并终止连接。)必须使用对等方期望的网络字节表示来呈现
String
值。例如,如果应该使用UTF-8
交换ALPNString
,则应将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
返回可以在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
设置可以在SSL/TLS/DTLS协议上使用的签名方案名称的优先级数组。请注意,标准签名方案名称列表在Java安全标准算法名称规范的签名方案部分中定义。提供程序可能支持未在此列表中定义的签名方案,或者可能不使用某些签名方案的推荐名称。
将在SSL/TLS/DTLS连接上使用的签名方案集由输入参数
signatureSchemes
数组和底层提供程序特定的默认签名方案确定。有关在SSL/TLS/DTLS连接中如何使用参数的具体详细信息,请参阅getSignatureSchemes()
。- API注释:
- 请注意,提供程序可能尚未更新以支持此方法,在这种情况下可能会忽略设置的方案。
- 实现注释:
- SunJSSE提供程序支持此方法。
- 参数:
-
signatureSchemes
- 一个有序的签名方案名称数组,第一个条目是最优先的,或null
。此方法将复制此数组。在建立SSL/TLS/DTLS连接时,提供程序应忽略未知的签名方案名称。 - 抛出:
-
IllegalArgumentException
- 如果signatureSchemes
数组中的任何元素为null
或空白。 - 自版本:
- 19
- 参见:
-
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
设置可以在SSL/TLS/DTLS协议上使用的优先级数组的密钥交换命名组名称。请注意,标准的密钥交换命名组列表在Java安全标准算法名称规范的命名组部分中定义。提供程序可能支持未在此列表中定义的命名组,或者可能不使用某个命名组的推荐名称。
将在SSL/TLS/DTLS连接上使用的命名组集由输入参数
namedGroups
数组和基础提供程序特定的默认命名组确定。有关参数在SSL/TLS/DTLS连接中如何使用的具体详细信息,请参阅getNamedGroups()
。- API注释:
- 请注意,提供程序可能尚未更新以支持此方法,在这种情况下可能会忽略设置的命名组。
- 实现注释:
- SunJSSE提供程序支持此方法。
- 参数:
-
namedGroups
- 一个有序的密钥交换命名组名称数组,第一个条目为最首选项,或null
。此方法将复制此数组。提供程序在建立SSL/TLS/DTLS连接时应忽略未知的命名组方案名称。 - 抛出:
-
IllegalArgumentException
- 如果namedGroups
数组中的任何元素是重复的、null
或空白的。 - 自:
- 20
- 参见:
-