| /* |
| * Copyright (c) 1997, 2017, 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 SessionBindingListener} 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. |
| */ |
| @Deprecated(since="9") |
| 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(); |
| } |