mirror of
https://github.com/openjdk/jdk.git
synced 2025-08-27 06:45:07 +02:00
410 lines
15 KiB
Java
410 lines
15 KiB
Java
/*
|
|
* Copyright (c) 1997, 2024, 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;
|
|
import java.nio.ByteBuffer;
|
|
|
|
/**
|
|
* 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
|
|
*/
|
|
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.
|
|
*
|
|
* @return the session context used for this session, or null
|
|
* if the context is unavailable.
|
|
*/
|
|
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
|
|
*/
|
|
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
|
|
*/
|
|
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()
|
|
*/
|
|
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
|
|
*/
|
|
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.
|
|
*
|
|
* @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.
|
|
*/
|
|
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.
|
|
*
|
|
* @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.
|
|
*/
|
|
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.
|
|
*
|
|
* @param name the name of the object to remove
|
|
* @throws IllegalArgumentException if the argument is null.
|
|
*/
|
|
void removeValue(String name);
|
|
|
|
|
|
/**
|
|
* Returns an array of the names of all the application layer
|
|
* data objects bound into the Session.
|
|
*
|
|
* @return a non-null (possibly empty) array of names of the objects
|
|
* bound to this Session.
|
|
*/
|
|
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()
|
|
*/
|
|
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()
|
|
*/
|
|
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>
|
|
*
|
|
* @implSpec
|
|
* This default implementation throws UnsupportedOperationException.
|
|
*
|
|
* @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.)
|
|
* @throws SSLPeerUnverifiedException if the peer's identity
|
|
* has not been verified.
|
|
* @throws UnsupportedOperationException if the underlying provider
|
|
* does not implement the operation.
|
|
*
|
|
* @see #getPeerPrincipal()
|
|
* @deprecated The {@link #getPeerCertificates()} method that returns an
|
|
* array of {@code java.security.cert.Certificate} should
|
|
* be used instead.
|
|
*/
|
|
@SuppressWarnings("removal")
|
|
@Deprecated(since="9", forRemoval=true)
|
|
default javax.security.cert.X509Certificate[]
|
|
getPeerCertificateChain() throws SSLPeerUnverifiedException {
|
|
throw new UnsupportedOperationException(
|
|
"This method is deprecated and marked for removal. Use the " +
|
|
"getPeerCertificates() method instead.");
|
|
}
|
|
|
|
/**
|
|
* 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 certificate 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
|
|
*/
|
|
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
|
|
*/
|
|
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
|
|
*/
|
|
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.
|
|
*/
|
|
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.
|
|
*/
|
|
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
|
|
*/
|
|
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
|
|
*/
|
|
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
|
|
*/
|
|
int getApplicationBufferSize();
|
|
}
|