public interface SSLSession
在 SSL 中,会话用来描述两个实体间正在发生的关系。每个 SSL 连接在某一时刻都会涉及一个会话,但是该会话可以同时地或相继地用在这些实体的多个连接上。还可以用不同的会话代替某一连接上使用的会话。会话是作为 SSL 握手协议的一部分创建或重新加入的。影响安全或资源使用的策略或由应用程序显式调用 invalidate
可能使会话无效。会话管理策略通常用来调优性能。
除了标准会话属性之外,SSL 会话还会公开以下这些只读属性:
可以显式地使会话无效。当遇到某种错误时,也可以隐式地使会话无效。
方法摘要 | |
---|---|
int |
getApplicationBufferSize() 获取使用此会话时期望的最大应用程序数据的当前大小。 |
String |
getCipherSuite() 返回会话中的所有连接所使用的 SSL 密码套件的名称。 |
long |
getCreationTime() 返回创建此会话表示的时间,该时间是自协调世界时 1970 年 1 月 1 日午夜起经过的毫秒数。 |
byte[] |
getId() 返回分配给此会话的标识符。 |
long |
getLastAccessedTime() 返回此会话表示上一次被会话层应用访问的时间,该时间是自协调世界时 1970 年 1 月 1 日午夜起经过的毫秒数。 |
Certificate[] |
getLocalCertificates() 返回握手期间发送给同位体的证书。 |
Principal |
getLocalPrincipal() 返回握手期间发送给同位体的主体。 |
int |
getPacketBufferSize() 获取使用此会话时期望的最大 SSL/TLS 包的当前大小。 |
X509Certificate[] |
getPeerCertificateChain() 返回同级身份,该同级身份被标识作为定义会话的一部分。 |
Certificate[] |
getPeerCertificates() 返回同级身份,该同级身份是作为定义会话的一部分而建立的。 |
String |
getPeerHost() 返回此会话中同位体的主机名称。 |
int |
getPeerPort() 返回此会话中同位体的端口号。 |
Principal |
getPeerPrincipal() 返回同级身份,该同级身份是作为定义会话的一部分而建立的。 |
String |
getProtocol() 返回会话中的所有连接使用的协议的标准名称。 |
SSLSessionContext |
getSessionContext() 返回此会话所在的上下文。 |
Object |
getValue(String name) 返回会话的应用层数据中的绑定到给定名称的对象。 |
String[] |
getValueNames() 返回绑定到会话中的所有应用层数据对象的名称组成的数组。 |
void |
invalidate() 使会话失效。 |
boolean |
isValid() 返回此会话对于恢复和加入是否是有效的和可用的。 |
void |
putValue(String name, Object value) 使用给定的 name 将指定的 value 对象绑定到会话的应用层数据中。 |
void |
removeValue(String name) 移除会话的应用层数据中绑定到给定名称的对象。 |
方法详细信息 |
---|
byte[] getId()
SSLSessionContext getSessionContext()
此上下文在一些环境中可能不可用,在这种情况下,此方法返回 null。
如果存在上下文并且已安装了一个安全管理器,则调用者可能需要相应的权限才能访问上下文,否则可能抛出安全异常。在 Java 环境中,使用 SSLPermission("getSSLSessionContext")
权限调用安全管理器的 checkPermission
方法。
SecurityException
- 如果调用线程没有获取 SSL 会话上下文的权限。
long getCreationTime()
long getLastAccessedTime()
访问将指示使用会话数据建立一个新的连接。访问期间并不反映应用级操作,例如获取或设置与会话相关的值。
此信息在会话管理策略中特别有用。例如,会话管理器线程可以将所有会话放在一个很长时间未被使用的给定上下文中;或者可能根据生存时间对会话进行排序,以优化一些任务。
void invalidate()
将来的连接无法恢复或加入此会话。但是,任何使用此会话的现有连接可以继续使用此会话,直到该连接关闭。
isValid()
boolean isValid()
invalidate()
void putValue(String name, Object value)
name
将指定的
value
对象绑定到会话的应用层数据中。
替换任何使用相同 name
的现有绑定。如果新的(或现有)value
实现了 SSLSessionBindingListener
接口,则会相应地通知 value
表示的对象。
出于安全原因,具有相同名称的值在不同的访问控制上下文之间是不可见的。
name
- 数据对象将要绑定到的名称。此参数不可以为 null。
value
- 将要绑定的数据对象。此参数不可以为 null。
IllegalArgumentException
- 如果任何一个参数为 null。
Object getValue(String name)
出于安全原因,具有相同名称的值在不同的访问控制上下文之间是不可见的。
name
- 要查找的绑定的名称。
IllegalArgumentException
- 如果参数为 null。
void removeValue(String name)
SessionBindingListener
接口,则以适当的方式通知它。
出于安全原因,具有相同名称的值在不同的访问控制上下文之间是不可见的。
name
- 将移除的在不同访问控制上下文之间可见的对象名称
IllegalArgumentException
- 如果参数为 null。
String[] getValueNames()
出于安全原因,具有相同名称的值在不同的访问控制上下文之间是不可见的。
Certificate[] getPeerCertificates() throws SSLPeerUnverifiedException
注:仅当使用基于证书的密码套件时才可以使用此方法;将它与非基于证书的密码套件(如 Kerberos)一起使用将抛出 SSLPeerUnverifiedException。
SSLPeerUnverifiedException
- 如果同级身份未被验证
getPeerPrincipal()
Certificate[] getLocalCertificates()
注:仅当使用基于证书的密码套件时此方法才有用。
当在一次握手中有多个证书可供使用时,具体实现可以选择使用它认为“最好的”证书链,并将该证书链传输给另一端。此方法允许调用者知道实际使用了哪些证书链。
getLocalPrincipal()
X509Certificate[] getPeerCertificateChain() throws SSLPeerUnverifiedException
注:仅当使用基于证书的密码套件时才可以使用此方法;将它与非基于证书的密码套件(如 Kerberos)一起使用将抛出 SSLPeerUnverifiedException。
注:此方法存在是为了与以前的版本兼容。新的应用程序应该使用 getPeerCertificates()
。
X509Certificate
格式。)
SSLPeerUnverifiedException
- 如果同级身份未被验证
getPeerPrincipal()
Principal getPeerPrincipal() throws SSLPeerUnverifiedException
SSLPeerUnverifiedException
- 如果同级身份未被验证
getPeerCertificates()
,
getLocalPrincipal()
Principal getLocalPrincipal()
getLocalCertificates()
,
getPeerPrincipal()
String getCipherSuite()
此密码套件定义了针对连接上发送的数据所提供的保护级别,包括所使用的加密类型和如何进行验证的大多数方面。
String getProtocol()
此方法定义了连接中使用的协议。
String getPeerHost()
对于服务器来说,该主机是客户端的主机;对于客户端来说,它是服务器的主机。此名称可以不是一个完全限定的主机名或根本不是主机名,因为它可以表示同级网络地址的字符串编码。如果需要这样的名称,可以根据此方法返回的值通过名称服务来解析该名称。
此值并没有经过验证,因此不应依赖它。它主要被用作 SSLSession
缓存策略的提示。
int getPeerPort()
对于服务器来说,该端口号是客户端的端口号;对于客户端来说,它是服务器的端口号。
此值并没有经过验证,因此不应依赖它。它主要被用作 SSLSession
缓存策略的提示。
int getPacketBufferSize()
使用此会话的 SSLEngine
可以生成任意大小并包括此方法返回的值的 SSL/TLS 包。所有 SSLEngine
网络缓冲区的大小最少应该是这么大,以防止执行 wrap
和 unwrap
时出现空间不足问题。
SSLEngine.wrap(ByteBuffer, ByteBuffer)
,
SSLEngine.unwrap(ByteBuffer, ByteBuffer)
int getApplicationBufferSize()
SSLEngine
应用数据缓冲区必须足够大以容纳所接收的取自任何入站网络应用数据包的应用数据。通常,出站应用数据缓冲区可以为任意大小。
SSLEngine.wrap(ByteBuffer, ByteBuffer)
,
SSLEngine.unwrap(ByteBuffer, ByteBuffer)