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