javax.net.ssl
接口 SSLSession

public interface SSLSession

在 SSL 中，会话用来描述两个实体间正在发生的关系。每个 SSL 连接在某一时刻都会涉及一个会话，但是该会话可以同时地或相继地用在这些实体的多个连接上。还可以用不同的会话代替某一连接上使用的会话。会话是作为 SSL 握手协议的一部分创建或重新加入的。影响安全或资源使用的策略或由应用程序显式调用 invalidate 可能使会话无效。会话管理策略通常用来调优性能。

除了标准会话属性之外，SSL 会话还会公开以下这些只读属性：

• 同级身份。 会话是在特定客户端和特定服务器之间进行的。同级身份可能已作为会话设置的一部分建立。同位体通常是用 X.509 证书链标识。
• 密码套件的名称。密码套件描述在特定会话中的连接使用的加密保护的种类。
• 同级主机。一次会话的所有连接都是在相同的两个主机之间进行的。连接的另一端的主机的地址是可用的。

可以显式地使会话无效。当遇到某种错误时，也可以隐式地使会话无效。

从以下版本开始：

1.4

方法摘要

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) 移除会话的应用层数据中绑定到给定名称的对象。

方法详细信息

getId

byte[] getId()

返回分配给此会话的标识符。

返回：

会话的标识符

getSessionContext

SSLSessionContext getSessionContext()

返回此会话所在的上下文。

此上下文在一些环境中可能不可用，在这种情况下，此方法返回 null。

如果存在上下文并且已安装了一个安全管理器，则调用者可能需要相应的权限才能访问上下文，否则可能抛出安全异常。在 Java 环境中，使用 SSLPermission("getSSLSessionContext") 权限调用安全管理器的 checkPermission 方法。

返回：

用于此会话的会话上下文；如果上下文不可用，则返回 null。

抛出：

SecurityException - 如果调用线程没有获取 SSL 会话上下文的权限。

getCreationTime

long getCreationTime()

返回创建此会话表示的时间，该时间是自协调世界时 1970 年 1 月 1 日午夜起经过的毫秒数。

返回：

创建此会话的时间

getLastAccessedTime

long getLastAccessedTime()

返回此会话表示上一次被会话层应用访问的时间，该时间是自协调世界时 1970 年 1 月 1 日午夜起经过的毫秒数。

访问将指示使用会话数据建立一个新的连接。访问期间并不反映应用级操作，例如获取或设置与会话相关的值。

此信息在会话管理策略中特别有用。例如，会话管理器线程可以将所有会话放在一个很长时间未被使用的给定上下文中；或者可能根据生存时间对会话进行排序，以优化一些任务。

返回：

上一次访问此会话的时间

invalidate

void invalidate()

使会话失效。

将来的连接无法恢复或加入此会话。但是，任何使用此会话的现有连接可以继续使用此会话，直到该连接关闭。

另请参见：

isValid()

isValid

boolean isValid()

返回此会话对于恢复和加入是否是有效的和可用的。

返回：

如果可以重新加入此会话，则返回 true。

从以下版本开始：

1.5

另请参见：

invalidate()

putValue

void putValue(String name,
              Object value)

使用给定的 name 将指定的 value 对象绑定到会话的应用层数据中。

替换任何使用相同 name 的现有绑定。如果新的（或现有）value 实现了 SSLSessionBindingListener 接口，则会相应地通知 value 表示的对象。

出于安全原因，具有相同名称的值在不同的访问控制上下文之间是不可见的。

参数：

name - 数据对象将要绑定到的名称。此参数不可以为 null。

value - 将要绑定的数据对象。此参数不可以为 null。

抛出：

IllegalArgumentException - 如果任何一个参数为 null。

getValue

Object getValue(String name)

返回会话的应用层数据中的绑定到给定名称的对象。如果不存在这种绑定，则返回 null。

出于安全原因，具有相同名称的值在不同的访问控制上下文之间是不可见的。

参数：

name - 要查找的绑定的名称。

返回：

绑定到该名称的值；如果不存在绑定，则返回 null。

抛出：

IllegalArgumentException - 如果参数为 null。

removeValue

void removeValue(String name)

移除会话的应用层数据中绑定到给定名称的对象。如果没有对象绑定到给定名称，则什么都不做。如果绑定的现有对象实现了 SessionBindingListener 接口，则以适当的方式通知它。

出于安全原因，具有相同名称的值在不同的访问控制上下文之间是不可见的。

参数：

name - 将移除的在不同访问控制上下文之间可见的对象名称

抛出：

IllegalArgumentException - 如果参数为 null。

getValueNames

String[] getValueNames()

返回绑定到会话中的所有应用层数据对象的名称组成的数组。

出于安全原因，具有相同名称的值在不同的访问控制上下文之间是不可见的。

返回：

绑定到此会话的对象的名称组成的非 null（可能为空）数组。

getPeerCertificates

Certificate[] getPeerCertificates()
                                  throws SSLPeerUnverifiedException

返回同级身份，该同级身份是作为定义会话的一部分而建立的。

注：仅当使用基于证书的密码套件时才可以使用此方法；将它与非基于证书的密码套件（如 Kerberos）一起使用将抛出 SSLPeerUnverifiedException。

返回：

同级证书的有序数组，同位体自己的证书紧跟在任何证书授权之后。

抛出：

SSLPeerUnverifiedException - 如果同级身份未被验证

另请参见：

getPeerPrincipal()

getLocalCertificates

Certificate[] getLocalCertificates()

返回握手期间发送给同位体的证书。

注：仅当使用基于证书的密码套件时此方法才有用。

当在一次握手中有多个证书可供使用时，具体实现可以选择使用它认为“最好的”证书链，并将该证书链传输给另一端。此方法允许调用者知道实际使用了哪些证书链。

返回：

证书的有序数组，本地证书紧跟在任何证书授权之后。如果没有发送任何证书，则返回 null。

另请参见：

getLocalPrincipal()

getPeerCertificateChain

X509Certificate[] getPeerCertificateChain()
                                          throws SSLPeerUnverifiedException

返回同级身份，该同级身份被标识作为定义会话的一部分。

注：仅当使用基于证书的密码套件时才可以使用此方法；将它与非基于证书的密码套件（如 Kerberos）一起使用将抛出 SSLPeerUnverifiedException。

注：此方法存在是为了与以前的版本兼容。新的应用程序应该使用 getPeerCertificates()。

返回：

同级 X.509 证书的有序数组，同位体自己的证书紧跟在任何证书授权之后。（证书格式采用原来的 JSSE 证书 X509Certificate 格式。）

抛出：

SSLPeerUnverifiedException - 如果同级身份未被验证

另请参见：

getPeerPrincipal()

getPeerPrincipal

Principal getPeerPrincipal()
                           throws SSLPeerUnverifiedException

返回同级身份，该同级身份是作为定义会话的一部分而建立的。

返回：

同位体的主体。对于基于 X509 的密码套件，返回最终实体证书的 X500Principal；对于 Kerberos 密码套件，返回 KerberosPrincipal。

抛出：

SSLPeerUnverifiedException - 如果同级身份未被验证

从以下版本开始：

1.5

另请参见：

getPeerCertificates(), getLocalPrincipal()

getLocalPrincipal

Principal getLocalPrincipal()

返回握手期间发送给同位体的主体。

返回：

发送给同位体的主体。返回基于 X509 的密码套件的最终实体证书的 X500Principal，以及 Kerberos 的密码套件的 KerberosPrincipal。如果没有发送任何主体，则返回 null。

从以下版本开始：

1.5

另请参见：

getLocalCertificates(), getPeerPrincipal()

getCipherSuite

String getCipherSuite()

返回会话中的所有连接所使用的 SSL 密码套件的名称。

此密码套件定义了针对连接上发送的数据所提供的保护级别，包括所使用的加密类型和如何进行验证的大多数方面。

返回：

会话的密码套件的名称。

getProtocol

String getProtocol()

返回会话中的所有连接使用的协议的标准名称。

此方法定义了连接中使用的协议。

返回：

会话中的所有连接使用的协议的标准名称。

getPeerHost

String getPeerHost()

返回此会话中同位体的主机名称。

对于服务器来说，该主机是客户端的主机；对于客户端来说，它是服务器的主机。此名称可以不是一个完全限定的主机名或根本不是主机名，因为它可以表示同级网络地址的字符串编码。如果需要这样的名称，可以根据此方法返回的值通过名称服务来解析该名称。

此值并没有经过验证，因此不应依赖它。它主要被用作 SSLSession 缓存策略的提示。

返回：

同级主机的主机名称；如果没有信息可用，则返回 null。

getPeerPort

int getPeerPort()

返回此会话中同位体的端口号。

对于服务器来说，该端口号是客户端的端口号；对于客户端来说，它是服务器的端口号。

此值并没有经过验证，因此不应依赖它。它主要被用作 SSLSession 缓存策略的提示。

返回：

同位体的端口号；如果没有信息可用，则返回 -1。

从以下版本开始：

1.5

getPacketBufferSize

int getPacketBufferSize()

获取使用此会话时期望的最大 SSL/TLS 包的当前大小。

使用此会话的 SSLEngine 可以生成任意大小并包括此方法返回的值的 SSL/TLS 包。所有 SSLEngine 网络缓冲区的大小最少应该是这么大，以防止执行 wrap 和 unwrap 时出现空间不足问题。

返回：

期望网络包大小的当前最大值

从以下版本开始：

1.5

另请参见：

SSLEngine.wrap(ByteBuffer, ByteBuffer), SSLEngine.unwrap(ByteBuffer, ByteBuffer)

getApplicationBufferSize

int getApplicationBufferSize()

获取使用此会话时期望的最大应用程序数据的当前大小。

SSLEngine 应用数据缓冲区必须足够大以容纳所接收的取自任何入站网络应用数据包的应用数据。通常，出站应用数据缓冲区可以为任意大小。

返回：

期望应用程序包大小的当前最大值

从以下版本开始：

1.5

另请参见：

SSLEngine.wrap(ByteBuffer, ByteBuffer), SSLEngine.unwrap(ByteBuffer, ByteBuffer)