001 /*
002 * Copyright 1997-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.net.ssl;
027
028 import java.net.InetAddress;
029 import java.security.Principal;
030
031 /**
032 * In SSL, sessions are used to describe an ongoing relationship between
033 * two entities. Each SSL connection involves one session at a time, but
034 * that session may be used on many connections between those entities,
035 * simultaneously or sequentially. The session used on a connection may
036 * also be replaced by a different session. Sessions are created, or
037 * rejoined, as part of the SSL handshaking protocol. Sessions may be
038 * invalidated due to policies affecting security or resource usage,
039 * or by an application explicitly calling <code>invalidate</code>.
040 * Session management policies are typically used to tune performance.
041 *
042 * <P> In addition to the standard session attributes, SSL sessions expose
043 * these read-only attributes: <UL>
044 *
045 * <LI> <em>Peer Identity.</em> Sessions are between a particular
046 * client and a particular server. The identity of the peer may
047 * have been established as part of session setup. Peers are
048 * generally identified by X.509 certificate chains.
049 *
050 * <LI> <em>Cipher Suite Name.</em> Cipher suites describe the
051 * kind of cryptographic protection that's used by connections
052 * in a particular session.
053 *
054 * <LI> <em>Peer Host.</em> All connections in a session are
055 * between the same two hosts. The address of the host on the other
056 * side of the connection is available.
057 *
058 * </UL>
059 *
060 * <P> Sessions may be explicitly invalidated. Invalidation may also
061 * be done implicitly, when faced with certain kinds of errors.
062 *
063 * @since 1.4
064 * @version 1.41
065 * @author David Brownell
066 */
067 public interface SSLSession {
068
069 /**
070 * Returns the identifier assigned to this Session.
071 *
072 * @return the Session identifier
073 */
074 public byte[] getId();
075
076 /**
077 * Returns the context in which this session is bound.
078 * <P>
079 * This context may be unavailable in some environments,
080 * in which case this method returns null.
081 * <P>
082 * If the context is available and there is a
083 * security manager installed, the caller may require
084 * permission to access it or a security exception may be thrown.
085 * In a Java environment, the security manager's
086 * <code>checkPermission</code> method is called with a
087 * <code>SSLPermission("getSSLSessionContext")</code> permission.
088 *
089 * @throws SecurityException if the calling thread does not have
090 * permission to get SSL session context.
091 * @return the session context used for this session, or null
092 * if the context is unavailable.
093 */
094 public SSLSessionContext getSessionContext();
095
096 /**
097 * Returns the time at which this Session representation was created,
098 * in milliseconds since midnight, January 1, 1970 UTC.
099 *
100 * @return the time this Session was created
101 */
102 public long getCreationTime();
103
104 /**
105 * Returns the last time this Session representation was accessed by the
106 * session level infrastructure, in milliseconds since
107 * midnight, January 1, 1970 UTC.
108 * <P>
109 * Access indicates a new connection being established using session data.
110 * Application level operations, such as getting or setting a value
111 * associated with the session, are not reflected in this access time.
112 *
113 * <P> This information is particularly useful in session management
114 * policies. For example, a session manager thread could leave all
115 * sessions in a given context which haven't been used in a long time;
116 * or, the sessions might be sorted according to age to optimize some task.
117 *
118 * @return the last time this Session was accessed
119 */
120 public long getLastAccessedTime();
121
122 /**
123 * Invalidates the session.
124 * <P>
125 * Future connections will not be able to
126 * resume or join this session. However, any existing connection
127 * using this session can continue to use the session until the
128 * connection is closed.
129 *
130 * @see #isValid()
131 */
132 public void invalidate();
133
134 /**
135 * Returns whether this session is valid and available for resuming or
136 * joining.
137 *
138 * @return true if this session may be rejoined.
139 * @see #invalidate()
140 *
141 * @since 1.5
142 */
143 public boolean isValid();
144
145 /**
146 *
147 * Binds the specified <code>value</code> object into the
148 * session's application layer data
149 * with the given <code>name</code>.
150 * <P>
151 * Any existing binding using the same <code>name</code> is
152 * replaced. If the new (or existing) <code>value</code> implements the
153 * <code>SSLSessionBindingListener</code> interface, the object
154 * represented by <code>value</code> is notified appropriately.
155 * <p>
156 * For security reasons, the same named values may not be
157 * visible across different access control contexts.
158 *
159 * @param name the name to which the data object will be bound.
160 * This may not be null.
161 * @param value the data object to be bound. This may not be null.
162 * @throws IllegalArgumentException if either argument is null.
163 */
164 public void putValue(String name, Object value);
165
166 /**
167 * Returns the object bound to the given name in the session's
168 * application layer data. Returns null if there is no such binding.
169 * <p>
170 * For security reasons, the same named values may not be
171 * visible across different access control contexts.
172 *
173 * @param name the name of the binding to find.
174 * @return the value bound to that name, or null if the binding does
175 * not exist.
176 * @throws IllegalArgumentException if the argument is null.
177 */
178 public Object getValue(String name);
179
180 /**
181 * Removes the object bound to the given name in the session's
182 * application layer data. Does nothing if there is no object
183 * bound to the given name. If the bound existing object
184 * implements the <code>SessionBindingListener</code> interface,
185 * it is notified appropriately.
186 * <p>
187 * For security reasons, the same named values may not be
188 * visible across different access control contexts.
189 *
190 * @param name the name of the object to remove visible
191 * across different access control contexts
192 * @throws IllegalArgumentException if the argument is null.
193 */
194 public void removeValue(String name);
195
196 /**
197 * Returns an array of the names of all the application layer
198 * data objects bound into the Session.
199 * <p>
200 * For security reasons, the same named values may not be
201 * visible across different access control contexts.
202 *
203 * @return a non-null (possibly empty) array of names of the objects
204 * bound to this Session.
205 */
206 public String[] getValueNames();
207
208 /**
209 * Returns the identity of the peer which was established as part
210 * of defining the session.
211 * <P>
212 * Note: This method can be used only when using certificate-based
213 * cipher suites; using it with non-certificate-based cipher suites,
214 * such as Kerberos, will throw an SSLPeerUnverifiedException.
215 *
216 * @return an ordered array of peer certificates,
217 * with the peer's own certificate first followed by any
218 * certificate authorities.
219 * @exception SSLPeerUnverifiedException if the peer's identity has not
220 * been verified
221 * @see #getPeerPrincipal()
222 */
223 public java.security.cert.Certificate[] getPeerCertificates()
224 throws SSLPeerUnverifiedException;
225
226 /**
227 * Returns the certificate(s) that were sent to the peer during
228 * handshaking.
229 * <P>
230 * Note: This method is useful only when using certificate-based
231 * cipher suites.
232 * <P>
233 * When multiple certificates are available for use in a
234 * handshake, the implementation chooses what it considers the
235 * "best" certificate chain available, and transmits that to
236 * the other side. This method allows the caller to know
237 * which certificate chain was actually used.
238 *
239 * @return an ordered array of certificates,
240 * with the local certificate first followed by any
241 * certificate authorities. If no certificates were sent,
242 * then null is returned.
243 *
244 * @see #getLocalPrincipal()
245 */
246 public java.security.cert.Certificate[] getLocalCertificates();
247
248 /**
249 * Returns the identity of the peer which was identified as part
250 * of defining the session.
251 * <P>
252 * Note: This method can be used only when using certificate-based
253 * cipher suites; using it with non-certificate-based cipher suites,
254 * such as Kerberos, will throw an SSLPeerUnverifiedException.
255 *
256 * <p><em>Note: this method exists for compatibility with previous
257 * releases. New applications should use
258 * {@link #getPeerCertificates} instead.</em></p>
259 *
260 * @return an ordered array of peer X.509 certificates,
261 * with the peer's own certificate first followed by any
262 * certificate authorities. (The certificates are in
263 * the original JSSE certificate
264 * {@link javax.security.cert.X509Certificate} format.)
265 * @exception SSLPeerUnverifiedException if the peer's identity
266 * has not been verified
267 * @see #getPeerPrincipal()
268 */
269 public javax.security.cert.X509Certificate[] getPeerCertificateChain()
270 throws SSLPeerUnverifiedException;
271
272 /**
273 * Returns the identity of the peer which was established as part of
274 * defining the session.
275 *
276 * @return the peer's principal. Returns an X500Principal of the
277 * end-entity certiticate for X509-based cipher suites, and
278 * KerberosPrincipal for Kerberos cipher suites.
279 *
280 * @throws SSLPeerUnverifiedException if the peer's identity has not
281 * been verified
282 *
283 * @see #getPeerCertificates()
284 * @see #getLocalPrincipal()
285 *
286 * @since 1.5
287 */
288 public Principal getPeerPrincipal()
289 throws SSLPeerUnverifiedException;
290
291 /**
292 * Returns the principal that was sent to the peer during handshaking.
293 *
294 * @return the principal sent to the peer. Returns an X500Principal
295 * of the end-entity certificate for X509-based cipher suites, and
296 * KerberosPrincipal for Kerberos cipher suites. If no principal was
297 * sent, then null is returned.
298 *
299 * @see #getLocalCertificates()
300 * @see #getPeerPrincipal()
301 *
302 * @since 1.5
303 */
304 public Principal getLocalPrincipal();
305
306 /**
307 * Returns the name of the SSL cipher suite which is used for all
308 * connections in the session.
309 *
310 * <P> This defines the level of protection
311 * provided to the data sent on the connection, including the kind
312 * of encryption used and most aspects of how authentication is done.
313 *
314 * @return the name of the session's cipher suite
315 */
316 public String getCipherSuite();
317
318 /**
319 * Returns the standard name of the protocol used for all
320 * connections in the session.
321 *
322 * <P> This defines the protocol used in the connection.
323 *
324 * @return the standard name of the protocol used for all
325 * connections in the session.
326 */
327 public String getProtocol();
328
329 /**
330 * Returns the host name of the peer in this session.
331 * <P>
332 * For the server, this is the client's host; and for
333 * the client, it is the server's host. The name may not be
334 * a fully qualified host name or even a host name at all as
335 * it may represent a string encoding of the peer's network address.
336 * If such a name is desired, it might
337 * be resolved through a name service based on the value returned
338 * by this method.
339 * <P>
340 * This value is not authenticated and should not be relied upon.
341 * It is mainly used as a hint for <code>SSLSession</code> caching
342 * strategies.
343 *
344 * @return the host name of the peer host, or null if no information
345 * is available.
346 */
347 public String getPeerHost();
348
349 /**
350 * Returns the port number of the peer in this session.
351 * <P>
352 * For the server, this is the client's port number; and for
353 * the client, it is the server's port number.
354 * <P>
355 * This value is not authenticated and should not be relied upon.
356 * It is mainly used as a hint for <code>SSLSession</code> caching
357 * strategies.
358 *
359 * @return the port number of the peer host, or -1 if no information
360 * is available.
361 *
362 * @since 1.5
363 */
364 public int getPeerPort();
365
366 /**
367 * Gets the current size of the largest SSL/TLS packet that is expected
368 * when using this session.
369 * <P>
370 * A <code>SSLEngine</code> using this session may generate SSL/TLS
371 * packets of any size up to and including the value returned by this
372 * method. All <code>SSLEngine</code> network buffers should be sized
373 * at least this large to avoid insufficient space problems when
374 * performing <code>wrap</code> and <code>unwrap</code> calls.
375 *
376 * @return the current maximum expected network packet size
377 *
378 * @see SSLEngine#wrap(ByteBuffer, ByteBuffer)
379 * @see SSLEngine#unwrap(ByteBuffer, ByteBuffer)
380 *
381 * @since 1.5
382 */
383 public int getPacketBufferSize();
384
385 /**
386 * Gets the current size of the largest application data that is
387 * expected when using this session.
388 * <P>
389 * <code>SSLEngine</code> application data buffers must be large
390 * enough to hold the application data from any inbound network
391 * application data packet received. Typically, outbound
392 * application data buffers can be of any size.
393 *
394 * @return the current maximum expected application packet size
395 *
396 * @see SSLEngine#wrap(ByteBuffer, ByteBuffer)
397 * @see SSLEngine#unwrap(ByteBuffer, ByteBuffer)
398 *
399 * @since 1.5
400 */
401 public int getApplicationBufferSize();
402 }
|