invalidate.
* Session management policies are typically used to tune performance.
*
* In addition to the standard session attributes, SSL sessions expose * these read-only attributes:
Sessions may be explicitly invalidated. Invalidation may also * be done implicitly, when faced with certain kinds of errors. * * @since 1.4 * @author David Brownell */ public interface SSLSession { /** * Returns the identifier assigned to this Session. * * @return the Session identifier */ public byte[] getId(); /** * Returns the context in which this session is bound. *
* This context may be unavailable in some environments, * in which case this method returns null. *
* If the context is available and there is a
* security manager installed, the caller may require
* permission to access it or a security exception may be thrown.
* In a Java environment, the security manager's
* checkPermission method is called with a
* SSLPermission("getSSLSessionContext") permission.
*
* @throws SecurityException if the calling thread does not have
* permission to get SSL session context.
* @return the session context used for this session, or null
* if the context is unavailable.
*/
public SSLSessionContext getSessionContext();
/**
* Returns the time at which this Session representation was created,
* in milliseconds since midnight, January 1, 1970 UTC.
*
* @return the time this Session was created
*/
public long getCreationTime();
/**
* Returns the last time this Session representation was accessed by the
* session level infrastructure, in milliseconds since
* midnight, January 1, 1970 UTC.
*
* Access indicates a new connection being established using session data. * Application level operations, such as getting or setting a value * associated with the session, are not reflected in this access time. * *
This information is particularly useful in session management * policies. For example, a session manager thread could leave all * sessions in a given context which haven't been used in a long time; * or, the sessions might be sorted according to age to optimize some task. * * @return the last time this Session was accessed */ public long getLastAccessedTime(); /** * Invalidates the session. *
* Future connections will not be able to
* resume or join this session. However, any existing connection
* using this session can continue to use the session until the
* connection is closed.
*
* @see #isValid()
*/
public void invalidate();
/**
* Returns whether this session is valid and available for resuming or
* joining.
*
* @return true if this session may be rejoined.
* @see #invalidate()
*
* @since 1.5
*/
public boolean isValid();
/**
*
* Binds the specified value object into the
* session's application layer data
* with the given name.
*
* Any existing binding using the same name is
* replaced. If the new (or existing) value implements the
* SSLSessionBindingListener interface, the object
* represented by value is notified appropriately.
*
* For security reasons, the same named values may not be * visible across different access control contexts. * * @param name the name to which the data object will be bound. * This may not be null. * @param value the data object to be bound. This may not be null. * @throws IllegalArgumentException if either argument is null. */ public void putValue(String name, Object value); /** * Returns the object bound to the given name in the session's * application layer data. Returns null if there is no such binding. *
* For security reasons, the same named values may not be
* visible across different access control contexts.
*
* @param name the name of the binding to find.
* @return the value bound to that name, or null if the binding does
* not exist.
* @throws IllegalArgumentException if the argument is null.
*/
public Object getValue(String name);
/**
* Removes the object bound to the given name in the session's
* application layer data. Does nothing if there is no object
* bound to the given name. If the bound existing object
* implements the SessionBindingListener interface,
* it is notified appropriately.
*
* For security reasons, the same named values may not be * visible across different access control contexts. * * @param name the name of the object to remove visible * across different access control contexts * @throws IllegalArgumentException if the argument is null. */ public void removeValue(String name); /** * Returns an array of the names of all the application layer * data objects bound into the Session. *
* For security reasons, the same named values may not be * visible across different access control contexts. * * @return a non-null (possibly empty) array of names of the objects * bound to this Session. */ public String [] getValueNames(); /** * Returns the identity of the peer which was established as part * of defining the session. *
* Note: This method can be used only when using certificate-based * cipher suites; using it with non-certificate-based cipher suites, * such as Kerberos, will throw an SSLPeerUnverifiedException. * * @return an ordered array of peer certificates, * with the peer's own certificate first followed by any * certificate authorities. * @exception SSLPeerUnverifiedException if the peer's identity has not * been verified * @see #getPeerPrincipal() */ public java.security.cert.Certificate [] getPeerCertificates() throws SSLPeerUnverifiedException; /** * Returns the certificate(s) that were sent to the peer during * handshaking. *
* Note: This method is useful only when using certificate-based * cipher suites. *
* When multiple certificates are available for use in a * handshake, the implementation chooses what it considers the * "best" certificate chain available, and transmits that to * the other side. This method allows the caller to know * which certificate chain was actually used. * * @return an ordered array of certificates, * with the local certificate first followed by any * certificate authorities. If no certificates were sent, * then null is returned. * * @see #getLocalPrincipal() */ public java.security.cert.Certificate [] getLocalCertificates(); /** * Returns the identity of the peer which was identified as part * of defining the session. *
* Note: This method can be used only when using certificate-based * cipher suites; using it with non-certificate-based cipher suites, * such as Kerberos, will throw an SSLPeerUnverifiedException. * *
Note: this method exists for compatibility with previous * releases. New applications should use * {@link #getPeerCertificates} instead.
* * @return an ordered array of peer X.509 certificates, * with the peer's own certificate first followed by any * certificate authorities. (The certificates are in * the original JSSE certificate * {@link javax.security.cert.X509Certificate} format.) * @exception SSLPeerUnverifiedException if the peer's identity * has not been verified * @see #getPeerPrincipal() */ public javax.security.cert.X509Certificate [] getPeerCertificateChain() throws SSLPeerUnverifiedException; /** * Returns the identity of the peer which was established as part of * defining the session. * * @return the peer's principal. Returns an X500Principal of the * end-entity certiticate for X509-based cipher suites, and * KerberosPrincipal for Kerberos cipher suites. * * @throws SSLPeerUnverifiedException if the peer's identity has not * been verified * * @see #getPeerCertificates() * @see #getLocalPrincipal() * * @since 1.5 */ public Principal getPeerPrincipal() throws SSLPeerUnverifiedException; /** * Returns the principal that was sent to the peer during handshaking. * * @return the principal sent to the peer. Returns an X500Principal * of the end-entity certificate for X509-based cipher suites, and * KerberosPrincipal for Kerberos cipher suites. If no principal was * sent, then null is returned. * * @see #getLocalCertificates() * @see #getPeerPrincipal() * * @since 1.5 */ public Principal getLocalPrincipal(); /** * Returns the name of the SSL cipher suite which is used for all * connections in the session. * *This defines the level of protection * provided to the data sent on the connection, including the kind * of encryption used and most aspects of how authentication is done. * * @return the name of the session's cipher suite */ public String getCipherSuite(); /** * Returns the standard name of the protocol used for all * connections in the session. * *
This defines the protocol used in the connection. * * @return the standard name of the protocol used for all * connections in the session. */ public String getProtocol(); /** * Returns the host name of the peer in this session. *
* For the server, this is the client's host; and for * the client, it is the server's host. The name may not be * a fully qualified host name or even a host name at all as * it may represent a string encoding of the peer's network address. * If such a name is desired, it might * be resolved through a name service based on the value returned * by this method. *
* This value is not authenticated and should not be relied upon.
* It is mainly used as a hint for SSLSession caching
* strategies.
*
* @return the host name of the peer host, or null if no information
* is available.
*/
public String getPeerHost();
/**
* Returns the port number of the peer in this session.
*
* For the server, this is the client's port number; and for * the client, it is the server's port number. *
* This value is not authenticated and should not be relied upon.
* It is mainly used as a hint for SSLSession caching
* strategies.
*
* @return the port number of the peer host, or -1 if no information
* is available.
*
* @since 1.5
*/
public int getPeerPort();
/**
* Gets the current size of the largest SSL/TLS packet that is expected
* when using this session.
*
* A SSLEngine using this session may generate SSL/TLS
* packets of any size up to and including the value returned by this
* method. All SSLEngine network buffers should be sized
* at least this large to avoid insufficient space problems when
* performing wrap and unwrap calls.
*
* @return the current maximum expected network packet size
*
* @see SSLEngine#wrap(ByteBuffer, ByteBuffer)
* @see SSLEngine#unwrap(ByteBuffer, ByteBuffer)
*
* @since 1.5
*/
public int getPacketBufferSize();
/**
* Gets the current size of the largest application data that is
* expected when using this session.
*
* SSLEngine application data buffers must be large
* enough to hold the application data from any inbound network
* application data packet received. Typically, outbound
* application data buffers can be of any size.
*
* @return the current maximum expected application packet size
*
* @see SSLEngine#wrap(ByteBuffer, ByteBuffer)
* @see SSLEngine#unwrap(ByteBuffer, ByteBuffer)
*
* @since 1.5
*/
public int getApplicationBufferSize();
}