View Javadoc
1   /*
2    * Copyright (c) 1997, 2012, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package javax.net.ssl;
27  
28  import java.security.Principal;
29  
30  /**
31   * In SSL, sessions are used to describe an ongoing relationship between
32   * two entities.  Each SSL connection involves one session at a time, but
33   * that session may be used on many connections between those entities,
34   * simultaneously or sequentially.  The session used on a connection may
35   * also be replaced by a different session.  Sessions are created, or
36   * rejoined, as part of the SSL handshaking protocol. Sessions may be
37   * invalidated due to policies affecting security or resource usage,
38   * or by an application explicitly calling <code>invalidate</code>.
39   * Session management policies are typically used to tune performance.
40   *
41   * <P> In addition to the standard session attributes, SSL sessions expose
42   * these read-only attributes:  <UL>
43   *
44   *      <LI> <em>Peer Identity.</em>  Sessions are between a particular
45   *      client and a particular server.  The identity of the peer may
46   *      have been established as part of session setup.  Peers are
47   *      generally identified by X.509 certificate chains.
48   *
49   *      <LI> <em>Cipher Suite Name.</em>  Cipher suites describe the
50   *      kind of cryptographic protection that's used by connections
51   *      in a particular session.
52   *
53   *      <LI> <em>Peer Host.</em>  All connections in a session are
54   *      between the same two hosts.  The address of the host on the other
55   *      side of the connection is available.
56   *
57   *      </UL>
58   *
59   * <P> Sessions may be explicitly invalidated.  Invalidation may also
60   * be done implicitly, when faced with certain kinds of errors.
61   *
62   * @since 1.4
63   * @author David Brownell
64   */
65  public interface SSLSession {
66  
67      /**
68       * Returns the identifier assigned to this Session.
69       *
70       * @return the Session identifier
71       */
72      public byte[] getId();
73  
74  
75      /**
76       * Returns the context in which this session is bound.
77       * <P>
78       * This context may be unavailable in some environments,
79       * in which case this method returns null.
80       * <P>
81       * If the context is available and there is a
82       * security manager installed, the caller may require
83       * permission to access it or a security exception may be thrown.
84       * In a Java environment, the security manager's
85       * <code>checkPermission</code> method is called with a
86       * <code>SSLPermission("getSSLSessionContext")</code> permission.
87       *
88       * @throws SecurityException if the calling thread does not have
89       *         permission to get SSL session context.
90       * @return the session context used for this session, or null
91       * if the context is unavailable.
92       */
93      public SSLSessionContext getSessionContext();
94  
95  
96      /**
97       * Returns the time at which this Session representation was created,
98       * in milliseconds since midnight, January 1, 1970 UTC.
99       *
100      * @return the time this Session was created
101      */
102     public long getCreationTime();
103 
104 
105     /**
106      * Returns the last time this Session representation was accessed by the
107      * session level infrastructure, in milliseconds since
108      * midnight, January 1, 1970 UTC.
109      * <P>
110      * Access indicates a new connection being established using session data.
111      * Application level operations, such as getting or setting a value
112      * associated with the session, are not reflected in this access time.
113      *
114      * <P> This information is particularly useful in session management
115      * policies.  For example, a session manager thread could leave all
116      * sessions in a given context which haven't been used in a long time;
117      * or, the sessions might be sorted according to age to optimize some task.
118      *
119      * @return the last time this Session was accessed
120      */
121     public long getLastAccessedTime();
122 
123 
124     /**
125      * Invalidates the session.
126      * <P>
127      * Future connections will not be able to
128      * resume or join this session.  However, any existing connection
129      * using this session can continue to use the session until the
130      * connection is closed.
131      *
132      * @see #isValid()
133      */
134     public void invalidate();
135 
136 
137     /**
138      * Returns whether this session is valid and available for resuming or
139      * joining.
140      *
141      * @return true if this session may be rejoined.
142      * @see #invalidate()
143      *
144      * @since 1.5
145      */
146     public boolean isValid();
147 
148 
149     /**
150      *
151      * Binds the specified <code>value</code> object into the
152      * session's application layer data
153      * with the given <code>name</code>.
154      * <P>
155      * Any existing binding using the same <code>name</code> is
156      * replaced.  If the new (or existing) <code>value</code> implements the
157      * <code>SSLSessionBindingListener</code> interface, the object
158      * represented by <code>value</code> is notified appropriately.
159      * <p>
160      * For security reasons, the same named values may not be
161      * visible across different access control contexts.
162      *
163      * @param name the name to which the data object will be bound.
164      *          This may not be null.
165      * @param value the data object to be bound. This may not be null.
166      * @throws IllegalArgumentException if either argument is null.
167      */
168     public void putValue(String name, Object value);
169 
170 
171     /**
172      * Returns the object bound to the given name in the session's
173      * application layer data.  Returns null if there is no such binding.
174      * <p>
175      * For security reasons, the same named values may not be
176      * visible across different access control contexts.
177      *
178      * @param name the name of the binding to find.
179      * @return the value bound to that name, or null if the binding does
180      *          not exist.
181      * @throws IllegalArgumentException if the argument is null.
182      */
183     public Object getValue(String name);
184 
185 
186     /**
187      * Removes the object bound to the given name in the session's
188      * application layer data.  Does nothing if there is no object
189      * bound to the given name.  If the bound existing object
190      * implements the <code>SessionBindingListener</code> interface,
191      * it is notified appropriately.
192      * <p>
193      * For security reasons, the same named values may not be
194      * visible across different access control contexts.
195      *
196      * @param name the name of the object to remove visible
197      *          across different access control contexts
198      * @throws IllegalArgumentException if the argument is null.
199      */
200     public void removeValue(String name);
201 
202 
203     /**
204      * Returns an array of the names of all the application layer
205      * data objects bound into the Session.
206      * <p>
207      * For security reasons, the same named values may not be
208      * visible across different access control contexts.
209      *
210      * @return a non-null (possibly empty) array of names of the objects
211      *  bound to this Session.
212      */
213     public String [] getValueNames();
214 
215     /**
216      * Returns the identity of the peer which was established as part
217      * of defining the session.
218      * <P>
219      * Note: This method can be used only when using certificate-based
220      * cipher suites; using it with non-certificate-based cipher suites,
221      * such as Kerberos, will throw an SSLPeerUnverifiedException.
222      *
223      * @return an ordered array of peer certificates,
224      *          with the peer's own certificate first followed by any
225      *          certificate authorities.
226      * @exception SSLPeerUnverifiedException if the peer's identity has not
227      *          been verified
228      * @see #getPeerPrincipal()
229      */
230     public java.security.cert.Certificate [] getPeerCertificates()
231             throws SSLPeerUnverifiedException;
232 
233     /**
234      * Returns the certificate(s) that were sent to the peer during
235      * handshaking.
236      * <P>
237      * Note: This method is useful only when using certificate-based
238      * cipher suites.
239      * <P>
240      * When multiple certificates are available for use in a
241      * handshake, the implementation chooses what it considers the
242      * "best" certificate chain available, and transmits that to
243      * the other side.  This method allows the caller to know
244      * which certificate chain was actually used.
245      *
246      * @return an ordered array of certificates,
247      * with the local certificate first followed by any
248      * certificate authorities.  If no certificates were sent,
249      * then null is returned.
250      *
251      * @see #getLocalPrincipal()
252      */
253     public java.security.cert.Certificate [] getLocalCertificates();
254 
255     /**
256      * Returns the identity of the peer which was identified as part
257      * of defining the session.
258      * <P>
259      * Note: This method can be used only when using certificate-based
260      * cipher suites; using it with non-certificate-based cipher suites,
261      * such as Kerberos, will throw an SSLPeerUnverifiedException.
262      *
263      * <p><em>Note: this method exists for compatibility with previous
264      * releases. New applications should use
265      * {@link #getPeerCertificates} instead.</em></p>
266      *
267      * @return an ordered array of peer X.509 certificates,
268      *          with the peer's own certificate first followed by any
269      *          certificate authorities.  (The certificates are in
270      *          the original JSSE certificate
271      *          {@link javax.security.cert.X509Certificate} format.)
272      * @exception SSLPeerUnverifiedException if the peer's identity
273      *          has not been verified
274      * @see #getPeerPrincipal()
275      */
276     public javax.security.cert.X509Certificate [] getPeerCertificateChain()
277             throws SSLPeerUnverifiedException;
278 
279     /**
280      * Returns the identity of the peer which was established as part of
281      * defining the session.
282      *
283      * @return the peer's principal. Returns an X500Principal of the
284      * end-entity certiticate for X509-based cipher suites, and
285      * KerberosPrincipal for Kerberos cipher suites.
286      *
287      * @throws SSLPeerUnverifiedException if the peer's identity has not
288      *          been verified
289      *
290      * @see #getPeerCertificates()
291      * @see #getLocalPrincipal()
292      *
293      * @since 1.5
294      */
295     public Principal getPeerPrincipal()
296             throws SSLPeerUnverifiedException;
297 
298     /**
299      * Returns the principal that was sent to the peer during handshaking.
300      *
301      * @return the principal sent to the peer. Returns an X500Principal
302      * of the end-entity certificate for X509-based cipher suites, and
303      * KerberosPrincipal for Kerberos cipher suites. If no principal was
304      * sent, then null is returned.
305      *
306      * @see #getLocalCertificates()
307      * @see #getPeerPrincipal()
308      *
309      * @since 1.5
310      */
311     public Principal getLocalPrincipal();
312 
313     /**
314      * Returns the name of the SSL cipher suite which is used for all
315      * connections in the session.
316      *
317      * <P> This defines the level of protection
318      * provided to the data sent on the connection, including the kind
319      * of encryption used and most aspects of how authentication is done.
320      *
321      * @return the name of the session's cipher suite
322      */
323     public String getCipherSuite();
324 
325     /**
326      * Returns the standard name of the protocol used for all
327      * connections in the session.
328      *
329      * <P> This defines the protocol used in the connection.
330      *
331      * @return the standard name of the protocol used for all
332      * connections in the session.
333      */
334     public String getProtocol();
335 
336     /**
337      * Returns the host name of the peer in this session.
338      * <P>
339      * For the server, this is the client's host;  and for
340      * the client, it is the server's host. The name may not be
341      * a fully qualified host name or even a host name at all as
342      * it may represent a string encoding of the peer's network address.
343      * If such a name is desired, it might
344      * be resolved through a name service based on the value returned
345      * by this method.
346      * <P>
347      * This value is not authenticated and should not be relied upon.
348      * It is mainly used as a hint for <code>SSLSession</code> caching
349      * strategies.
350      *
351      * @return  the host name of the peer host, or null if no information
352      *          is available.
353      */
354     public String getPeerHost();
355 
356     /**
357      * Returns the port number of the peer in this session.
358      * <P>
359      * For the server, this is the client's port number;  and for
360      * the client, it is the server's port number.
361      * <P>
362      * This value is not authenticated and should not be relied upon.
363      * It is mainly used as a hint for <code>SSLSession</code> caching
364      * strategies.
365      *
366      * @return  the port number of the peer host, or -1 if no information
367      *          is available.
368      *
369      * @since 1.5
370      */
371     public int getPeerPort();
372 
373     /**
374      * Gets the current size of the largest SSL/TLS packet that is expected
375      * when using this session.
376      * <P>
377      * A <code>SSLEngine</code> using this session may generate SSL/TLS
378      * packets of any size up to and including the value returned by this
379      * method. All <code>SSLEngine</code> network buffers should be sized
380      * at least this large to avoid insufficient space problems when
381      * performing <code>wrap</code> and <code>unwrap</code> calls.
382      *
383      * @return  the current maximum expected network packet size
384      *
385      * @see SSLEngine#wrap(ByteBuffer, ByteBuffer)
386      * @see SSLEngine#unwrap(ByteBuffer, ByteBuffer)
387      *
388      * @since 1.5
389      */
390     public int getPacketBufferSize();
391 
392 
393     /**
394      * Gets the current size of the largest application data that is
395      * expected when using this session.
396      * <P>
397      * <code>SSLEngine</code> application data buffers must be large
398      * enough to hold the application data from any inbound network
399      * application data packet received.  Typically, outbound
400      * application data buffers can be of any size.
401      *
402      * @return  the current maximum expected application packet size
403      *
404      * @see SSLEngine#wrap(ByteBuffer, ByteBuffer)
405      * @see SSLEngine#unwrap(ByteBuffer, ByteBuffer)
406      *
407      * @since 1.5
408      */
409     public int getApplicationBufferSize();
410 }