1 /* 2 * Copyright (c) 1997, 2006, 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.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 */ getId()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 */ getSessionContext()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 */ getCreationTime()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 */ getLastAccessedTime()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 */ invalidate()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 */ isValid()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 */ putValue(String name, Object value)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 */ getValue(String name)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 */ removeValue(String name)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 */ getValueNames()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 */ getPeerCertificates()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 */ getLocalCertificates()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 */ getPeerCertificateChain()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 */ getPeerPrincipal()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 */ getLocalPrincipal()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 */ getCipherSuite()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 */ getProtocol()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 */ getPeerHost()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 */ getPeerPort()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 */ getPacketBufferSize()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 */ getApplicationBufferSize()410 public int getApplicationBufferSize(); 411 } 412