1 /* 2 * Copyright (c) 1997, 2019, 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 */ 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} 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 */ 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} 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 */ 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 SSLSessionBindingListener} 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 * <P> 223 * Note: The returned value may not be a valid certificate chain 224 * and should not be relied on for trust decisions. 225 * 226 * @return an ordered array of peer certificates, 227 * with the peer's own certificate first followed by any 228 * certificate authorities. 229 * @exception SSLPeerUnverifiedException if the peer's identity has not 230 * been verified 231 * @see #getPeerPrincipal() 232 */ getPeerCertificates()233 public java.security.cert.Certificate [] getPeerCertificates() 234 throws SSLPeerUnverifiedException; 235 236 /** 237 * Returns the certificate(s) that were sent to the peer during 238 * handshaking. 239 * <P> 240 * Note: This method is useful only when using certificate-based 241 * cipher suites. 242 * <P> 243 * When multiple certificates are available for use in a 244 * handshake, the implementation chooses what it considers the 245 * "best" certificate chain available, and transmits that to 246 * the other side. This method allows the caller to know 247 * which certificate chain was actually used. 248 * 249 * @return an ordered array of certificates, 250 * with the local certificate first followed by any 251 * certificate authorities. If no certificates were sent, 252 * then null is returned. 253 * 254 * @see #getLocalPrincipal() 255 */ getLocalCertificates()256 public java.security.cert.Certificate [] getLocalCertificates(); 257 258 /** 259 * Returns the identity of the peer which was identified as part 260 * of defining the session. 261 * <P> 262 * Note: This method can be used only when using certificate-based 263 * cipher suites; using it with non-certificate-based cipher suites, 264 * such as Kerberos, will throw an SSLPeerUnverifiedException. 265 * <P> 266 * Note: The returned value may not be a valid certificate chain 267 * and should not be relied on for trust decisions. 268 * 269 * <p><em>Note: this method exists for compatibility with previous 270 * releases. New applications should use 271 * {@link #getPeerCertificates} instead.</em></p> 272 * 273 * @return an ordered array of peer X.509 certificates, 274 * with the peer's own certificate first followed by any 275 * certificate authorities. (The certificates are in 276 * the original JSSE certificate 277 * {@link javax.security.cert.X509Certificate} format.) 278 * @exception SSLPeerUnverifiedException if the peer's identity 279 * has not been verified 280 * @see #getPeerPrincipal() 281 * @deprecated The {@link #getPeerCertificates()} method that returns an 282 * array of {@code java.security.cert.Certificate} should 283 * be used instead. 284 */ 285 @SuppressWarnings("removal") 286 @Deprecated(since="9", forRemoval=true) getPeerCertificateChain()287 public javax.security.cert.X509Certificate [] getPeerCertificateChain() 288 throws SSLPeerUnverifiedException; 289 290 /** 291 * Returns the identity of the peer which was established as part of 292 * defining the session. 293 * 294 * @return the peer's principal. Returns an X500Principal of the 295 * end-entity certiticate for X509-based cipher suites, and 296 * KerberosPrincipal for Kerberos cipher suites. 297 * 298 * @throws SSLPeerUnverifiedException if the peer's identity has not 299 * been verified 300 * 301 * @see #getPeerCertificates() 302 * @see #getLocalPrincipal() 303 * 304 * @since 1.5 305 */ getPeerPrincipal()306 public Principal getPeerPrincipal() 307 throws SSLPeerUnverifiedException; 308 309 /** 310 * Returns the principal that was sent to the peer during handshaking. 311 * 312 * @return the principal sent to the peer. Returns an X500Principal 313 * of the end-entity certificate for X509-based cipher suites, and 314 * KerberosPrincipal for Kerberos cipher suites. If no principal was 315 * sent, then null is returned. 316 * 317 * @see #getLocalCertificates() 318 * @see #getPeerPrincipal() 319 * 320 * @since 1.5 321 */ getLocalPrincipal()322 public Principal getLocalPrincipal(); 323 324 /** 325 * Returns the name of the SSL cipher suite which is used for all 326 * connections in the session. 327 * 328 * <P> This defines the level of protection 329 * provided to the data sent on the connection, including the kind 330 * of encryption used and most aspects of how authentication is done. 331 * 332 * @return the name of the session's cipher suite 333 */ getCipherSuite()334 public String getCipherSuite(); 335 336 /** 337 * Returns the standard name of the protocol used for all 338 * connections in the session. 339 * 340 * <P> This defines the protocol used in the connection. 341 * 342 * @return the standard name of the protocol used for all 343 * connections in the session. 344 */ getProtocol()345 public String getProtocol(); 346 347 /** 348 * Returns the host name of the peer in this session. 349 * <P> 350 * For the server, this is the client's host; and for 351 * the client, it is the server's host. The name may not be 352 * a fully qualified host name or even a host name at all as 353 * it may represent a string encoding of the peer's network address. 354 * If such a name is desired, it might 355 * be resolved through a name service based on the value returned 356 * by this method. 357 * <P> 358 * This value is not authenticated and should not be relied upon. 359 * It is mainly used as a hint for {@code SSLSession} caching 360 * strategies. 361 * 362 * @return the host name of the peer host, or null if no information 363 * is available. 364 */ getPeerHost()365 public String getPeerHost(); 366 367 /** 368 * Returns the port number of the peer in this session. 369 * <P> 370 * For the server, this is the client's port number; and for 371 * the client, it is the server's port number. 372 * <P> 373 * This value is not authenticated and should not be relied upon. 374 * It is mainly used as a hint for {@code SSLSession} caching 375 * strategies. 376 * 377 * @return the port number of the peer host, or -1 if no information 378 * is available. 379 * 380 * @since 1.5 381 */ getPeerPort()382 public int getPeerPort(); 383 384 /** 385 * Gets the current size of the largest SSL/TLS/DTLS packet that is 386 * expected when using this session. 387 * <P> 388 * An {@code SSLEngine} using this session may generate SSL/TLS/DTLS 389 * packets of any size up to and including the value returned by this 390 * method. All {@code SSLEngine} network buffers should be sized 391 * at least this large to avoid insufficient space problems when 392 * performing {@code wrap} and {@code unwrap} calls. 393 * 394 * @return the current maximum expected network packet size 395 * 396 * @see SSLEngine#wrap(ByteBuffer, ByteBuffer) 397 * @see SSLEngine#unwrap(ByteBuffer, ByteBuffer) 398 * 399 * @since 1.5 400 */ getPacketBufferSize()401 public int getPacketBufferSize(); 402 403 404 /** 405 * Gets the current size of the largest application data that is 406 * expected when using this session. 407 * <P> 408 * {@code SSLEngine} application data buffers must be large 409 * enough to hold the application data from any inbound network 410 * application data packet received. Typically, outbound 411 * application data buffers can be of any size. 412 * 413 * @return the current maximum expected application packet size 414 * 415 * @see SSLEngine#wrap(ByteBuffer, ByteBuffer) 416 * @see SSLEngine#unwrap(ByteBuffer, ByteBuffer) 417 * 418 * @since 1.5 419 */ getApplicationBufferSize()420 public int getApplicationBufferSize(); 421 } 422