In addition to connections having a context associated with them, the JSSE also makes it possible to get access to and manage session information that is related to the connection taking place. This is done via objects that implement the SSLSession interface.
The SSLSession Interface
Objects implementing the javax.net.ssl.SSLSession interface are not created directly, but are returned by the getSession() method on SSLSocket. As you can see from the method descriptions that follow, an object implementing SSLSession acts not only as a carrier of connection information but also allows for the session to be invalidated and for other objects to be associated with the session if need be.
SSLSession.get CipherSuite()
The getCipherSuite() method returns a String representing the name of the SSL cipher suite, which is in use with all connections in the session.
SSLSession.get CreationTime()
The getCreationTime() method returns a long representing the time at when this SSLSession object was created. The time value is in milliseconds since midnight, January 1, 1970 UTC.
SSLSession.getId()
The getId() method returns a byte array representing the identifier that has been assigned to the session this SSLSession object represents.
SSLSession.get LastAccessedTime()
The getLastAccessedTime() method returns a long representing the last time this SSLSession object was accessed by the session-level infrastructure. As with getCreationTime(), the value is in milliseconds since midnight, January 1, 1970 UTC.
SSLSession.get LocalCertificates()
The getLocalCertificates() method returns an array of Certificate objects representing the certificate chain sent to the peer during handshaking. If no certificate chain was sent the method returns null.
SSLSession.get LocalPrincipal()
The getLocalPrincipal() method returns a Principal representing the principal that was used to identify this end of the connection to the peer. If no principal was provided, this method returns null. If the cipher suite in use is X.509-certificate based, the return value can be cast to X500Principal.
SSLSession.get PeerCertificates()
The getPeerCertificates() method returns an array of Certificate objects representing the certificate chain that you received from the peer during handshaking.
The method will throw an SSLPeerUnverifiedException if the peer did not authenticate itself during handshaking or if the cipher suite being used is not based on X.509 certificates but is instead based on another mechanism, such as that used by Kerberos.
SSLSession.get PeerHost()
The getPeerHost() method returns a String representing the hostname or the Internet address of the peer. The method will return null if the information is not available.
The return value of this method is not authenticated, so it should be considered to be a hint as to the identity of the peer’s host.
SSLSession.get PeerPort()
The getPeerPort() method returns the port number being used on the peer. The method will return ?1 if the information is not available. The method is only available in JDK 1.5 or later.
Like getPeerHost(), the return value of this method is not authenticated, so it should be considered to be a hint.
SSLSession.get PeerPrincipal()
The getPeerPrincipal() method returns a Principal object representing the principal that was used to identify the peer during handshaking. If the cipher suite used is based on the use of X.509 certificates, the object returned can be cast to X500Principal. The method is only available in JDK 1.5 and later.
The method will throw an SSLPeerUnverifiedException if the peer did not authenticate itself during handshaking.
SSLSession.get Protocol()
The getProtocol() method returns a String representing the standard name of the protocol that will be used for all connections associated with this SSLSession object.
SSLSession.get SessionContext()
The getSessionContext() method returns a javax.net.ssl.SSLSessionContext object that provides additional context information specific to this session. In the case where the environment does not have the session context available, the method will return null.
If an SSLSessionContext object is returned, you can use it for finding out and setting the session timeout, finding out and setting the number of sessions that can be cached in the context, and finding out the IDs of all the sessions associated with the context.
SSLSession.invalidate()
The invalidate() method invalidates the session. In this case that means that future connections will not be able to resume or join the session; however, any existing connection using the session will be able to continue until the connection is closed.
SSLSession.isValid()
The isValid() method returns a boolean value that will be true if it is possible to resume or join a connection to the session, false otherwise. The method is only available in JDK 1.5 or later.
SSLSession.putValue()
The putValue() method takes two parameters, a String and an Object, with the String representing a name that the Object parameter is to be stored under. The object that has been stored can be retrieved later using the getValue() method. The getValue() method takes a single String as a parameter representing an object name previously stored by putValue() and returns an Object that is associated with that name, or null if there isn’t one. Objects can be removed using the removeValue() method.
A String array representing the names of all the objects that have been stored in the session can be retrieved from the SSLSession object using the getValueNames() method. If no Objects are stored in the session, the method will return a zero length array.
The putValue(), getValue(), and removeValue() methods will all throw an IllegalArgumentException if any of the parameters passed to them are null.
As you can see, an object implementing SSLSession can carry any information that you want to associate with a session, as well as the basic information about the parties involved in the SSL connection the session object represents. The next example shows how a session object can be used to further check the identity of a client that has connected to a server