Module java.base
Package javax.net.ssl

Interface SSLSession

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

除了标准会话属性外，SSL会话还公开这些只读属性:

  • 对等身份。 会话是在特定客户端和特定服务器之间的。对等方的身份可能已经在会话设置的过程中建立。通常通过X.509证书链来识别对等方。
  • 密码套件名称。 密码套件描述了在特定会话中连接所使用的加密保护类型。
  • 对等主机。 会话中的所有连接都是在相同的两个主机之间的。可以获取连接另一侧主机的地址。

会话可以被显式地使无效。当面临某些类型的错误时，也可以隐式地进行使无效。

自版本:
1.4

  • Method Details

    • 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()
      返回此会话是否有效且可用于恢复或加入。
      返回:
      如果此会话可以重新加入，则为true。
      自版本:
      1.5
      参见:

    • putValue

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

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

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

      参数:
      name - 将绑定数据对象的名称。此名称不能为空。
      value - 要绑定的数据对象。此值不能为空。
      抛出:
      IllegalArgumentException - 如果任一参数为null。

    • getValue

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

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

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

    • removeValue

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

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

      参数:
      name - 要删除的对象的名称，可见于不同的访问控制上下文。
      抛出:
      IllegalArgumentException - 如果参数为null。

    • 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
      Deprecated, for removal: This API element is subject to removal in a future version.
      The getPeerCertificates() method that returns an array of java.security.cert.Certificate should be used instead.
      返回作为定义会话一部分而被识别的对等体的标识。

      注意：仅在使用基于证书的密码套件时才能使用此方法；如果在非基于证书的密码套件（如Kerberos）中使用它，将抛出SSLPeerUnverifiedException异常。

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

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

      实现要求：
      此默认实现会抛出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
      参见：