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