Back to index...

	/*
	* Copyright (c) 1997, 2012, Oracle and/or its affiliates. All rights reserved.
	* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
	*
	* This code is free software; you can redistribute it and/or modify it
	* under the terms of the GNU General Public License version 2 only, as
	* published by the Free Software Foundation. Oracle designates this
	* particular file as subject to the "Classpath" exception as provided
	* by Oracle in the LICENSE file that accompanied this code.
	*
	* This code is distributed in the hope that it will be useful, but WITHOUT
	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
	* version 2 for more details (a copy is included in the LICENSE file that
	* accompanied this code).
	*
	* You should have received a copy of the GNU General Public License version
	* 2 along with this work; if not, write to the Free Software Foundation,
	* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
	*
	* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
	* or visit www.oracle.com if you need additional information or have any
	* questions.
	*/

	package javax.net.ssl;

	import java.security.Principal;

	/**
	* In SSL, sessions are used to describe an ongoing relationship between
	* two entities. Each SSL connection involves one session at a time, but
	* that session may be used on many connections between those entities,
	* simultaneously or sequentially. The session used on a connection may
	* also be replaced by a different session. Sessions are created, or
	* rejoined, as part of the SSL handshaking protocol. Sessions may be
	* invalidated due to policies affecting security or resource usage,
	* or by an application explicitly calling <code>invalidate</code>.
	* Session management policies are typically used to tune performance.
	*
	* <P> In addition to the standard session attributes, SSL sessions expose
	* these read-only attributes: <UL>
	*
	* <LI> <em>Peer Identity.</em> Sessions are between a particular
	* client and a particular server. The identity of the peer may
	* have been established as part of session setup. Peers are
	* generally identified by X.509 certificate chains.
	*
	* <LI> <em>Cipher Suite Name.</em> Cipher suites describe the
	* kind of cryptographic protection that's used by connections
	* in a particular session.
	*
	* <LI> <em>Peer Host.</em> All connections in a session are
	* between the same two hosts. The address of the host on the other
	* side of the connection is available.
	*
	* </UL>
	*
	* <P> 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.
	* <P>
	* This context may be unavailable in some environments,
	* in which case this method returns null.
	* <P>
	* 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
	* <code>checkPermission</code> method is called with a
	* <code>SSLPermission("getSSLSessionContext")</code> 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.
	* <P>
	* 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.
	*
	* <P> 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.
	* <P>
	* 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 <code>value</code> object into the
	* session's application layer data
	* with the given <code>name</code>.
	* <P>
	* Any existing binding using the same <code>name</code> is
	* replaced. If the new (or existing) <code>value</code> implements the
	* <code>SSLSessionBindingListener</code> interface, the object
	* represented by <code>value</code> is notified appropriately.
	* <p>
	* 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.
	* <p>
	* 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 <code>SessionBindingListener</code> interface,
	* it is notified appropriately.
	* <p>
	* 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.
	* <p>
	* 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.
	* <P>
	* 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.
	* <P>
	* Note: This method is useful only when using certificate-based
	* cipher suites.
	* <P>
	* 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.
	* <P>
	* 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.
	*
	* <p><em>Note: this method exists for compatibility with previous
	* releases. New applications should use
	* {@link #getPeerCertificates} instead.</em></p>
	*
	* @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.
	*
	* <P> 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.
	*
	* <P> 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.
	* <P>
	* 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.
	* <P>
	* This value is not authenticated and should not be relied upon.
	* It is mainly used as a hint for <code>SSLSession</code> 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.
	* <P>
	* For the server, this is the client's port number; and for
	* the client, it is the server's port number.
	* <P>
	* This value is not authenticated and should not be relied upon.
	* It is mainly used as a hint for <code>SSLSession</code> 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.
	* <P>
	* A <code>SSLEngine</code> using this session may generate SSL/TLS
	* packets of any size up to and including the value returned by this
	* method. All <code>SSLEngine</code> network buffers should be sized
	* at least this large to avoid insufficient space problems when
	* performing <code>wrap</code> and <code>unwrap</code> 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.
	* <P>
	* <code>SSLEngine</code> 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();
	}

Back to index...