/*

 * Copyright (c) 1997, 2019, 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}.

 * 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} method is called with a

     * {@code 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.

     * <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} object into the

     * session's application layer data

     * with the given {@code name}.

     * <P>

     * Any existing binding using the same {@code name} is

     * replaced.  If the new (or existing) {@code value} implements the

     * {@code SSLSessionBindingListener} interface, the object

     * represented by {@code value} 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 SSLSessionBindingListener} 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.

     * <P>

     * Note: The returned value may not be a valid certificate chain

     * and should not be relied on for trust decisions.

     *

     * @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>

     * Note: The returned value may not be a valid certificate chain

     * and should not be relied on for trust decisions.

     *

     * <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()

     * @deprecated The {@link #getPeerCertificates()} method that returns an

     *               array of {@code java.security.cert.Certificate} should

     *               be used instead.

     */

    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} 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} 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/DTLS packet that is

     * expected when using this session.

     * <P>

     * An {@code SSLEngine} using this session may generate SSL/TLS/DTLS

     * packets of any size up to and including the value returned by this

     * method. All {@code SSLEngine} network buffers should be sized

     * at least this large to avoid insufficient space problems when

     * performing {@code wrap} and {@code 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.

     * <P>

     * {@code 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();

}