1 /*
2 * Copyright (c) 1997, 2015, 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}.
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} method is called with a
86 * {@code SSLPermission("getSSLSessionContext")} 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} object into the
152 * session's application layer data
153 * with the given {@code name}.
154 * <P>
155 * Any existing binding using the same {@code name} is
156 * replaced. If the new (or existing) {@code value} implements the
157 * {@code SSLSessionBindingListener} interface, the object
158 * represented by {@code value} 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} 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 * @deprecated The {@link #getPeerCertificates()} method that returns an
276 * array of {@code java.security.cert.Certificate} should
277 * be used instead.
278 */
279 @Deprecated
280 public javax.security.cert.X509Certificate [] getPeerCertificateChain()
281 throws SSLPeerUnverifiedException;
282
283 /**
284 * Returns the identity of the peer which was established as part of
285 * defining the session.
286 *
287 * @return the peer's principal. Returns an X500Principal of the
288 * end-entity certiticate for X509-based cipher suites, and
289 * KerberosPrincipal for Kerberos cipher suites.
290 *
291 * @throws SSLPeerUnverifiedException if the peer's identity has not
292 * been verified
293 *
294 * @see #getPeerCertificates()
295 * @see #getLocalPrincipal()
296 *
297 * @since 1.5
298 */
299 public Principal getPeerPrincipal()
300 throws SSLPeerUnverifiedException;
301
302 /**
303 * Returns the principal that was sent to the peer during handshaking.
304 *
305 * @return the principal sent to the peer. Returns an X500Principal
306 * of the end-entity certificate for X509-based cipher suites, and
307 * KerberosPrincipal for Kerberos cipher suites. If no principal was
308 * sent, then null is returned.
309 *
310 * @see #getLocalCertificates()
311 * @see #getPeerPrincipal()
312 *
313 * @since 1.5
314 */
315 public Principal getLocalPrincipal();
316
317 /**
318 * Returns the name of the SSL cipher suite which is used for all
319 * connections in the session.
320 *
321 * <P> This defines the level of protection
322 * provided to the data sent on the connection, including the kind
323 * of encryption used and most aspects of how authentication is done.
324 *
325 * @return the name of the session's cipher suite
326 */
327 public String getCipherSuite();
328
329 /**
330 * Returns the standard name of the protocol used for all
331 * connections in the session.
332 *
333 * <P> This defines the protocol used in the connection.
334 *
335 * @return the standard name of the protocol used for all
336 * connections in the session.
337 */
338 public String getProtocol();
339
340 /**
341 * Returns the host name of the peer in this session.
342 * <P>
343 * For the server, this is the client's host; and for
344 * the client, it is the server's host. The name may not be
345 * a fully qualified host name or even a host name at all as
346 * it may represent a string encoding of the peer's network address.
347 * If such a name is desired, it might
348 * be resolved through a name service based on the value returned
349 * by this method.
350 * <P>
351 * This value is not authenticated and should not be relied upon.
352 * It is mainly used as a hint for {@code SSLSession} caching
353 * strategies.
354 *
355 * @return the host name of the peer host, or null if no information
356 * is available.
357 */
358 public String getPeerHost();
359
360 /**
361 * Returns the port number of the peer in this session.
362 * <P>
363 * For the server, this is the client's port number; and for
364 * the client, it is the server's port number.
365 * <P>
366 * This value is not authenticated and should not be relied upon.
367 * It is mainly used as a hint for {@code SSLSession} caching
368 * strategies.
369 *
370 * @return the port number of the peer host, or -1 if no information
371 * is available.
372 *
373 * @since 1.5
374 */
375 public int getPeerPort();
376
377 /**
378 * Gets the current size of the largest SSL/TLS/DTLS packet that is
379 * expected when using this session.
380 * <P>
381 * An {@code SSLEngine} using this session may generate SSL/TLS/DTLS
382 * packets of any size up to and including the value returned by this
383 * method. All {@code SSLEngine} network buffers should be sized
384 * at least this large to avoid insufficient space problems when
385 * performing {@code wrap} and {@code unwrap} calls.
386 *
387 * @return the current maximum expected network packet size
388 *
389 * @see SSLEngine#wrap(ByteBuffer, ByteBuffer)
390 * @see SSLEngine#unwrap(ByteBuffer, ByteBuffer)
391 *
392 * @since 1.5
393 */
394 public int getPacketBufferSize();
395
396
397 /**
398 * Gets the current size of the largest application data that is
399 * expected when using this session.
400 * <P>
401 * {@code SSLEngine} application data buffers must be large
402 * enough to hold the application data from any inbound network
403 * application data packet received. Typically, outbound
404 * application data buffers can be of any size.
405 *
406 * @return the current maximum expected application packet size
407 *
408 * @see SSLEngine#wrap(ByteBuffer, ByteBuffer)
409 * @see SSLEngine#unwrap(ByteBuffer, ByteBuffer)
410 *
411 * @since 1.5
412 */
413 public int getApplicationBufferSize();
414 }