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