/* * Copyright (c) 1997, 2006, 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.net.InetAddress;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();}