SSLSession and ExtendedSSLSession Interfaces

A javax.net.ssl.SSLSession represents a security context negotiated between the two peers of an SSLSocket/SSLEngine connection. Once a session has been arranged, it can be shared by future SSLSocket/Engines connected between the same two peers.

In some cases, parameters that are negotiated during the handshake are needed later in the handshake to make decisions about trust. For example, the list of valid signature algorithms might restrict the certificate types that can be used for authentication. You can retrieve the SSLSession object during the handshake by calling the getHandshakeSession() method on an SSLSocket or SSLEngine object. Implementations of the TrustManager or KeyManager interfaces can use the getHandshakeSession() method to get information about session parameters, to help them make decisions.

A fully initialized SSLSession object contains the cipher suite that will be used for communications over a secure socket, as well as a non-authoritative hint as to the network address of the remote peer, and management information such as the time of creation and last use. A session also contains a shared master secret, negotiated between the peers, that is used to create cryptographic keys for encrypting and guaranteeing the integrity of the communications over an SSLSocket or SSLEngine connection. The value of this master secret is known only to the underlying secure socket implementation, and is not exposed through the SSLSession API.

A TLS 1.2 session is represented by the ExtendedSSLSession class, an implementation of the SSLSession interface. The ExtendedSSLSession class adds methods which describe the signature algorithms that are supported by the local implementation and the peer. The getRequestedServerNames() method called on an ExtendedSSLSession instance is used to obtain a list of SNIServerName objects in the requested Server Name Indication (SNI) Extension. The server should use the requested server names to guide the selection of an appropriate authentication certificate, and/or other aspects of the security policy. The client should use the requested server names to guide the endpoint identification of the peer's identity, and/or other aspects of the security policy.

Calls to SSLSession.getPacketBufferSize() and SSLSession.getApplicationBufferSize() also are used to determine the appropriate buffer sizes used by SSLEngine.