模块 java.base
包 javax.net.ssl

接口 SSLSession

所有已知的实现类：
ExtendedSSLSession
public interface SSLSession
在 SSL 中，会话用于描述两个实体之间的持续关系。每个 SSL 连接一次涉及一个会话，但该会话可以同时或依次用于这些实体之间的许多连接。连接上使用的会话也可以由不同的会话替换。会话是作为 SSL 握手协议的一部分创建或重新加入的。会话可能由于影响安全或资源使用的策略而失效，或者由于应用程序显式调用 invalidate 而失效。会话管理策略通常用于调整性能。

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

  • Peer Identity. 会话在特定客户端和特定服务之间。对等方的身份可能已作为会话设置的一部分建立。对等点通常由 X.509 证书链标识。
  • Cipher Suite Name. 密码套件描述了特定会话中的连接所使用的加密保护类型。
  • Peer Host. 会话中的所有连接都在相同的两个主机之间。连接另一端的主机地址可用。

会话可能会被显式无效。当遇到某些类型的错误时，也可以隐式地进行无效化。

自从：
1.4

  • 方法详情

    • getId

      byte[] getId()
      返回分配给此会话的标识符。
      返回：
      会话标识符

    • getSessionContext

      SSLSessionContext  getSessionContext()
      返回绑定此会话的上下文。

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

      如果上下文可用并且安装了安全管理器，调用者可能需要访问它的权限或者可能抛出安全异常。在 Java 环境中，安全管理器的 checkPermission 方法以 SSLPermission("getSSLSessionContext") 权限调用。

      返回：
      用于此会话的会话上下文，如果上下文不可用，则为 null。
      抛出：
      SecurityException - 如果调用线程没有获取 SSL 会话上下文的权限。

    • getCreationTime

      long getCreationTime()
      返回创建此会话表示的时间，自 1970 年 1 月 1 日午夜 UTC 以来的毫秒数。
      返回：
      创建此会话的时间

    • getLastAccessedTime

      long getLastAccessedTime()
      返回会话级基础结构最后一次访问此会话表示的时间，自 1970 年 1 月 1 日午夜 UTC 以来的毫秒数。

      访问表示正在使用会话数据建立新连接。应用程序级操作，例如获取或设置与会话关联的值，不会反映在该访问时间中。

      此信息在会话管理策略中特别有用。例如，会话管理器线程可以将所有会话保留在给定的上下文中，这些会话很长时间没有被使用；或者，可以根据年龄对会话进行排序以优化某些任务。

      返回：
      上次访问此会话的时间

    • invalidate

      void invalidate()
      使会话无效。

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

      参见：

    • isValid

      boolean isValid()
      返回此会话是否有效并可用于恢复或加入。
      返回：
      如果可以重新加入此会话，则为真。
      自从：
      1.5
      参见：

    • putValue

      void putValue(String  name, Object  value)
      使用给定的 name 将指定的 value 对象绑定到会话的应用层数据中。

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

      出于安全原因，相同的命名值可能在不同的访问控制上下文中不可见。

      参数：
      name - 数据对象将绑定到的名称。这可能不为空。
      value - 要绑定的数据对象。这可能不为空。
      抛出：
      IllegalArgumentException - 如果任一参数为空。

    • getValue

      Object  getValue(String  name)
      返回绑定到会话应用层数据中给定名称的对象。如果没有这样的绑定，则返回 null。

      出于安全原因，相同的命名值可能在不同的访问控制上下文中不可见。

      参数：
      name - 要查找的绑定的名称。
      返回：
      绑定到该名称的值，如果绑定不存在则为 null。
      抛出：
      IllegalArgumentException - 如果参数为空。

    • removeValue

      void removeValue(String  name)
      在会话的应用层数据中删除绑定到给定名称的对象。如果没有对象绑定到给定名称，则不执行任何操作。如果绑定的现有对象实现了 SSLSessionBindingListener 接口，则会适当地通知它。

      出于安全原因，相同的命名值可能在不同的访问控制上下文中不可见。

      参数：
      name - 要删除的对象的名称在不同的访问控制上下文中可见
      抛出：
      IllegalArgumentException - 如果参数为空。

    • getValueNames

      String [] getValueNames()
      返回绑定到会话中的所有应用层数据对象的名称数组。

      出于安全原因，相同的命名值可能在不同的访问控制上下文中不可见。

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

    • getPeerCertificates

      Certificate [] getPeerCertificates() throws SSLPeerUnverifiedException
      返回作为定义会话的一部分而建立的对等方的身份。

      注意：此方法只能在使用基于证书的密码套件时使用；将它与非基于证书的密码套件（例如 Kerberos）一起使用将抛出 SSLPeerUnverifiedException。

      注意：返回的值可能不是有效的证书链，不应依赖于信任决策。

      返回：
      对等证书的有序数组，首先是对等方自己的证书，然后是任何证书颁发机构。
      抛出：
      SSLPeerUnverifiedException - 如果对等方的身份尚未验证
      参见：

    • getLocalCertificates

      Certificate [] getLocalCertificates()
      返回在握手期间发送给对等方的证书。

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

      当多个证书可用于握手时，实现选择它认为可用的“最佳”证书链，并将其传输到另一端。此方法允许调用者知道实际使用了哪个证书链。

      返回：
      有序的证书数组，首先是本地证书，然后是任何证书颁发机构。如果未发送任何证书，则返回 null。
      参见：

    • getPeerCertificateChain

      @Deprecated (since ="9", forRemoval =true) default X509Certificate [] getPeerCertificateChain() throws SSLPeerUnverifiedException
      已弃用，将被删除：此 API 元素可能会在未来版本中删除。
      应改用返回 java.security.cert.Certificate 数组的 getPeerCertificates() 方法。
      返回被识别为定义会话一部分的对等方的身份。

      注意：此方法只能在使用基于证书的密码套件时使用；将它与非基于证书的密码套件（例如 Kerberos）一起使用将抛出 SSLPeerUnverifiedException。

      注意：返回的值可能不是有效的证书链，不应依赖于信任决策。

      Note: this method exists for compatibility with previous releases. New applications should use getPeerCertificates() instead.

      实现要求：
      此默认实现抛出 UnsupportedOperationException。
      返回：
      对等 X.509 证书的有序数组，首先是对等方自己的证书，然后是任何证书颁发机构。 （证书采用原始 JSSE 证书 X509Certificate 格式。）
      抛出：
      SSLPeerUnverifiedException - 如果对等方的身份尚未验证。
      UnsupportedOperationException - 如果底层提供者没有实现该操作。
      参见：

    • getPeerPrincipal

      Principal  getPeerPrincipal() throws SSLPeerUnverifiedException
      返回作为定义会话的一部分而建立的对等方的身份。
      返回：
      同行的主体。返回基于 X509 的密码套件的终端实体证书的 X500Principal，以及 Kerberos 密码套件的 KerberosPrincipal。
      抛出：
      SSLPeerUnverifiedException - 如果对等方的身份尚未验证
      自从：
      1.5
      参见：

    • getLocalPrincipal

      Principal  getLocalPrincipal()
      返回握手期间发送给对等方的委托人。
      返回：
      委托人发送给对等方。返回基于 X509 的密码套件的终端实体证书的 X500Principal，以及 Kerberos 密码套件的 KerberosPrincipal。如果没有发送委托人，则返回 null。
      自从：
      1.5
      参见：

    • getCipherSuite

      String  getCipherSuite()
      返回用于会话中所有连接的 SSL 密码套件的名称。

      这定义了为连接上发送的数据提供的保护级别，包括使用的加密类型和身份验证的大多数方面。

      返回：
      会话密码套件的名称

    • getProtocol

      String  getProtocol()
      返回用于会话中所有连接的协议的标准名称。

      这定义了连接中使用的协议。

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

    • getPeerHost

      String  getPeerHost()
      返回此会话中对等方的主机名。

      对于服务，这是客户端的主机；对于客户端，它是服务的主机。该名称可能不是完全限定的主机名，甚至根本不是主机名，因为它可能表示对等方网络地址的字符串编码。如果需要这样的名称，可以根据此方法返回的值通过名称服务对其进行解析。

      此值未经过身份验证，不应依赖。它主要用作SSLSession 缓存策略的提示。

      返回：
      对等主机的主机名，如果没有可用信息，则为 null。

    • getPeerPort

      int getPeerPort()
      返回此会话中对等方的端口号。

      对于服务，这是客户端的端口号；对于客户端，它是服务的端口号。

      此值未经过身份验证，不应依赖。它主要用作SSLSession 缓存策略的提示。

      返回：
      对等主机的端口号，如果没有可用信息，则为 -1。
      自从：
      1.5

    • getPacketBufferSize

      int getPacketBufferSize()
      获取使用此会话时预期的最大 SSL/TLS/DTLS 数据包的当前大小。

      使用此会话的 SSLEngine 可以生成任何大小的 SSL/TLS/DTLS 数据包，最大可达并包括此方法返回的值。所有 SSLEngine 网络缓冲区的大小应至少如此大，以避免在执行 wrap 和 unwrap 调用时出现空间不足问题。

      返回：
      当前最大预期网络数据包大小
      自从：
      1.5
      参见：

    • getApplicationBufferSize

      int getApplicationBufferSize()
      获取使用此会话时预期的最大应用程序数据的当前大小。

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

      返回：
      当前最大预期应用程序数据包大小
      自从：
      1.5
      参见：