Module  java.base
软件包  javax.net.ssl

Interface SSLSession

  • 所有已知实现类:
    ExtendedSSLSession


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

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

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

    会话可能会被明确无效。 当面临某些种类的错误时,也可以隐式地完成无效。

    从以下版本开始:
    1.4
    • 方法详细信息

      • getId

        byte[] getId​()
        返回分配给此会话的标识符。
        结果
        会话标识符
      • getSessionContext

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

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

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

        结果
        用于此会话的会话上下文,如果上下文不可用,则为null。
        异常
        SecurityException - 如果调用线程没有获取SSL会话上下文的权限。
      • getCreationTime

        long getCreationTime​()
        返回此会话表示形式创建的时间,以1970年1月1日UTC为午夜的毫秒计。
        结果
        此会话创建的时间
      • getLastAccessedTime

        long getLastAccessedTime​()
        返回会话级基础架构访问该会话表示的最后一次,以毫秒为单位,自1970年1月1日UTC之后。

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

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

        结果
        上次访问此会话
      • 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 - 如果任一参数为空。
      • getValue

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

        出于安全考虑,在不同的访问控制上下文中可能看不到相同的命名值。

        参数
        name - 要查找的绑定的名称。
        结果
        绑定到该名称的值,如果绑定不存在则为null。
        异常
        IllegalArgumentException - 如果参数为null。
      • removeValue

        void removeValue​(String name)
        删除在会话的应用层数据中绑定到给定名称的对象。 如果没有绑定到给定名称的对象,则不执行任何操作。 如果绑定的现有对象实现了SessionBindingListener接口,则会被正确通知。

        出于安全考虑,在不同的访问控制上下文中可能看不到相同的命名值。

        参数
        name - 要删除的对象的名称,可跨越不同的访问控制上下文
        异常
        IllegalArgumentException - 如果参数为空。
      • getValueNames

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

        出于安全考虑,在不同的访问控制上下文中可能看不到相同的命名值。

        结果
        绑定到此会话的对象的非空(可能为空)数组。
      • getPeerCertificates

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

        注意:此方法只能在使用基于证书的密码套件时使用; 与非基于证书的密码套件(如Kerberos)一起使用,将抛出SSLPeerUnverifiedException异常。

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

        结果
        一个有序的对等证书阵列,首先是对等体自己的证书,然后是任何证书颁发机构。
        异常
        SSLPeerUnverifiedException - 如果对等体的身份未被验证
        另请参见:
        getPeerPrincipal()
      • getLocalCertificates

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

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

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

        结果
        有序的证书阵列,本地证书首先跟随任何证书颁发机构。 如果没有发送证书,则返回null。
        另请参见:
        getLocalPrincipal()
      • getPeerCertificateChain

        @Deprecated(since="9")
        X509Certificate[] getPeerCertificateChain​()
                                           throws SSLPeerUnverifiedException
        已过时。 应该使用返回java.security.cert.Certificate数组的getPeerCertificates()方法。
        返回被确定为定义会话一部分的对等体的身份。

        注意:此方法只能在使用基于证书的密码套件时使用; 与非基于证书的密码套件(如Kerberos)一起使用,将抛出SSLPeerUnverifiedException异常。

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

        注意:此方法与以前的版本兼容。 新的应用程序应该使用getPeerCertificates()

        结果
        一个对等X.509证书的有序阵列,其中首先使用对等体自己的证书,然后是任何证书颁发机构。 (证书是原始的JSSE证书X509Certificate格式。)
        异常
        SSLPeerUnverifiedException - 如果对等体的身份未被验证
        另请参见:
        getPeerPrincipal()
      • 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 / DTLS数据包的当前大小。

        使用此会话的SSLEngine可以生成任何大小的SSL / TLS / DTLS数据包,包括此方法返回的值。 所有SSLEngine网络缓冲区的大小应至少大于此大小,以避免在执行wrapunwrap呼叫时出现空间不足问题。

        结果
        当前最大预期网络包大小
        从以下版本开始:
        1.5
        另请参见:
        SSLEngine.wrap(ByteBuffer, ByteBuffer)SSLEngine.unwrap(ByteBuffer, ByteBuffer)
      • getApplicationBufferSize

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

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

        结果
        当前最大预期应用包大小
        从以下版本开始:
        1.5
        另请参见:
        SSLEngine.wrap(ByteBuffer, ByteBuffer), SSLEngine.unwrap(ByteBuffer, ByteBuffer)