1 /* 2 * Copyright (c) 2003, 2013, 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.nio.ByteBuffer; 29 import java.nio.ReadOnlyBufferException; 30 31 32 /** 33 * A class which enables secure communications using protocols such as 34 * the Secure Sockets Layer (SSL) or 35 * <A HREF="http://www.ietf.org/rfc/rfc2246.txt"> IETF RFC 2246 "Transport 36 * Layer Security" (TLS) </A> protocols, but is transport independent. 37 * <P> 38 * The secure communications modes include: <UL> 39 * 40 * <LI> <em>Integrity Protection</em>. SSL/TLS protects against 41 * modification of messages by an active wiretapper. 42 * 43 * <LI> <em>Authentication</em>. In most modes, SSL/TLS provides 44 * peer authentication. Servers are usually authenticated, and 45 * clients may be authenticated as requested by servers. 46 * 47 * <LI> <em>Confidentiality (Privacy Protection)</em>. In most 48 * modes, SSL/TLS encrypts data being sent between client and 49 * server. This protects the confidentiality of data, so that 50 * passive wiretappers won't see sensitive data such as financial 51 * information or personal information of many kinds. 52 * 53 * </UL> 54 * 55 * These kinds of protection are specified by a "cipher suite", which 56 * is a combination of cryptographic algorithms used by a given SSL 57 * connection. During the negotiation process, the two endpoints must 58 * agree on a cipher suite that is available in both environments. If 59 * there is no such suite in common, no SSL connection can be 60 * established, and no data can be exchanged. 61 * <P> 62 * The cipher suite used is established by a negotiation process called 63 * "handshaking". The goal of this process is to create or rejoin a 64 * "session", which may protect many connections over time. After 65 * handshaking has completed, you can access session attributes by 66 * using the {@link #getSession()} method. 67 * <P> 68 * The <code>SSLSocket</code> class provides much of the same security 69 * functionality, but all of the inbound and outbound data is 70 * automatically transported using the underlying {@link 71 * java.net.Socket Socket}, which by design uses a blocking model. 72 * While this is appropriate for many applications, this model does not 73 * provide the scalability required by large servers. 74 * <P> 75 * The primary distinction of an <code>SSLEngine</code> is that it 76 * operates on inbound and outbound byte streams, independent of the 77 * transport mechanism. It is the responsibility of the 78 * <code>SSLEngine</code> user to arrange for reliable I/O transport to 79 * the peer. By separating the SSL/TLS abstraction from the I/O 80 * transport mechanism, the <code>SSLEngine</code> can be used for a 81 * wide variety of I/O types, such as {@link 82 * java.nio.channels.spi.AbstractSelectableChannel#configureBlocking(boolean) 83 * non-blocking I/O (polling)}, {@link java.nio.channels.Selector 84 * selectable non-blocking I/O}, {@link java.net.Socket Socket} and the 85 * traditional Input/OutputStreams, local {@link java.nio.ByteBuffer 86 * ByteBuffers} or byte arrays, <A 87 * HREF="http://www.jcp.org/en/jsr/detail?id=203"> future asynchronous 88 * I/O models </A>, and so on. 89 * <P> 90 * At a high level, the <code>SSLEngine</code> appears thus: 91 * 92 * <pre> 93 * app data 94 * 95 * | ^ 96 * | | | 97 * v | | 98 * +----+-----|-----+----+ 99 * | | | 100 * | SSL|Engine | 101 * wrap() | | | unwrap() 102 * | OUTBOUND | INBOUND | 103 * | | | 104 * +----+-----|-----+----+ 105 * | | ^ 106 * | | | 107 * v | 108 * 109 * net data 110 * </pre> 111 * Application data (also known as plaintext or cleartext) is data which 112 * is produced or consumed by an application. Its counterpart is 113 * network data, which consists of either handshaking and/or ciphertext 114 * (encrypted) data, and destined to be transported via an I/O 115 * mechanism. Inbound data is data which has been received from the 116 * peer, and outbound data is destined for the peer. 117 * <P> 118 * (In the context of an <code>SSLEngine</code>, the term "handshake 119 * data" is taken to mean any data exchanged to establish and control a 120 * secure connection. Handshake data includes the SSL/TLS messages 121 * "alert", "change_cipher_spec," and "handshake.") 122 * <P> 123 * There are five distinct phases to an <code>SSLEngine</code>. 124 * 125 * <OL> 126 * <li> Creation - The <code>SSLEngine</code> has been created and 127 * initialized, but has not yet been used. During this phase, an 128 * application may set any <code>SSLEngine</code>-specific settings 129 * (enabled cipher suites, whether the <code>SSLEngine</code> should 130 * handshake in client or server mode, and so on). Once 131 * handshaking has begun, though, any new settings (except 132 * client/server mode, see below) will be used for 133 * the next handshake. 134 * 135 * <li> Initial Handshake - The initial handshake is a procedure by 136 * which the two peers exchange communication parameters until an 137 * SSLSession is established. Application data can not be sent during 138 * this phase. 139 * 140 * <li> Application Data - Once the communication parameters have 141 * been established and the handshake is complete, application data 142 * may flow through the <code>SSLEngine</code>. Outbound 143 * application messages are encrypted and integrity protected, 144 * and inbound messages reverse the process. 145 * 146 * <li> Rehandshaking - Either side may request a renegotiation of 147 * the session at any time during the Application Data phase. New 148 * handshaking data can be intermixed among the application data. 149 * Before starting the rehandshake phase, the application may 150 * reset the SSL/TLS communication parameters such as the list of 151 * enabled ciphersuites and whether to use client authentication, 152 * but can not change between client/server modes. As before, once 153 * handshaking has begun, any new <code>SSLEngine</code> 154 * configuration settings will not be used until the next 155 * handshake. 156 * 157 * <li> Closure - When the connection is no longer needed, the 158 * application should close the <code>SSLEngine</code> and should 159 * send/receive any remaining messages to the peer before 160 * closing the underlying transport mechanism. Once an engine is 161 * closed, it is not reusable: a new <code>SSLEngine</code> must 162 * be created. 163 * </OL> 164 * An <code>SSLEngine</code> is created by calling {@link 165 * SSLContext#createSSLEngine()} from an initialized 166 * <code>SSLContext</code>. Any configuration 167 * parameters should be set before making the first call to 168 * <code>wrap()</code>, <code>unwrap()</code>, or 169 * <code>beginHandshake()</code>. These methods all trigger the 170 * initial handshake. 171 * <P> 172 * Data moves through the engine by calling {@link #wrap(ByteBuffer, 173 * ByteBuffer) wrap()} or {@link #unwrap(ByteBuffer, ByteBuffer) 174 * unwrap()} on outbound or inbound data, respectively. Depending on 175 * the state of the <code>SSLEngine</code>, a <code>wrap()</code> call 176 * may consume application data from the source buffer and may produce 177 * network data in the destination buffer. The outbound data 178 * may contain application and/or handshake data. A call to 179 * <code>unwrap()</code> will examine the source buffer and may 180 * advance the handshake if the data is handshaking information, or 181 * may place application data in the destination buffer if the data 182 * is application. The state of the underlying SSL/TLS algorithm 183 * will determine when data is consumed and produced. 184 * <P> 185 * Calls to <code>wrap()</code> and <code>unwrap()</code> return an 186 * <code>SSLEngineResult</code> which indicates the status of the 187 * operation, and (optionally) how to interact with the engine to make 188 * progress. 189 * <P> 190 * The <code>SSLEngine</code> produces/consumes complete SSL/TLS 191 * packets only, and does not store application data internally between 192 * calls to <code>wrap()/unwrap()</code>. Thus input and output 193 * <code>ByteBuffer</code>s must be sized appropriately to hold the 194 * maximum record that can be produced. Calls to {@link 195 * SSLSession#getPacketBufferSize()} and {@link 196 * SSLSession#getApplicationBufferSize()} should be used to determine 197 * the appropriate buffer sizes. The size of the outbound application 198 * data buffer generally does not matter. If buffer conditions do not 199 * allow for the proper consumption/production of data, the application 200 * must determine (via {@link SSLEngineResult}) and correct the 201 * problem, and then try the call again. 202 * <P> 203 * For example, <code>unwrap()</code> will return a {@link 204 * SSLEngineResult.Status#BUFFER_OVERFLOW} result if the engine 205 * determines that there is not enough destination buffer space available. 206 * Applications should call {@link SSLSession#getApplicationBufferSize()} 207 * and compare that value with the space available in the destination buffer, 208 * enlarging the buffer if necessary. Similarly, if <code>unwrap()</code> 209 * were to return a {@link SSLEngineResult.Status#BUFFER_UNDERFLOW}, the 210 * application should call {@link SSLSession#getPacketBufferSize()} to ensure 211 * that the source buffer has enough room to hold a record (enlarging if 212 * necessary), and then obtain more inbound data. 213 * 214 * <pre>{@code 215 * SSLEngineResult r = engine.unwrap(src, dst); 216 * switch (r.getStatus()) { 217 * BUFFER_OVERFLOW: 218 * // Could attempt to drain the dst buffer of any already obtained 219 * // data, but we'll just increase it to the size needed. 220 * int appSize = engine.getSession().getApplicationBufferSize(); 221 * ByteBuffer b = ByteBuffer.allocate(appSize + dst.position()); 222 * dst.flip(); 223 * b.put(dst); 224 * dst = b; 225 * // retry the operation. 226 * break; 227 * BUFFER_UNDERFLOW: 228 * int netSize = engine.getSession().getPacketBufferSize(); 229 * // Resize buffer if needed. 230 * if (netSize > dst.capacity()) { 231 * ByteBuffer b = ByteBuffer.allocate(netSize); 232 * src.flip(); 233 * b.put(src); 234 * src = b; 235 * } 236 * // Obtain more inbound network data for src, 237 * // then retry the operation. 238 * break; 239 * // other cases: CLOSED, OK. 240 * } 241 * }</pre> 242 * 243 * <P> 244 * Unlike <code>SSLSocket</code>, all methods of SSLEngine are 245 * non-blocking. <code>SSLEngine</code> implementations may 246 * require the results of tasks that may take an extended period of 247 * time to complete, or may even block. For example, a TrustManager 248 * may need to connect to a remote certificate validation service, 249 * or a KeyManager might need to prompt a user to determine which 250 * certificate to use as part of client authentication. Additionally, 251 * creating cryptographic signatures and verifying them can be slow, 252 * seemingly blocking. 253 * <P> 254 * For any operation which may potentially block, the 255 * <code>SSLEngine</code> will create a {@link java.lang.Runnable} 256 * delegated task. When <code>SSLEngineResult</code> indicates that a 257 * delegated task result is needed, the application must call {@link 258 * #getDelegatedTask()} to obtain an outstanding delegated task and 259 * call its {@link java.lang.Runnable#run() run()} method (possibly using 260 * a different thread depending on the compute strategy). The 261 * application should continue obtaining delegated tasks until no more 262 * exist, and try the original operation again. 263 * <P> 264 * At the end of a communication session, applications should properly 265 * close the SSL/TLS link. The SSL/TLS protocols have closure handshake 266 * messages, and these messages should be communicated to the peer 267 * before releasing the <code>SSLEngine</code> and closing the 268 * underlying transport mechanism. A close can be initiated by one of: 269 * an SSLException, an inbound closure handshake message, or one of the 270 * close methods. In all cases, closure handshake messages are 271 * generated by the engine, and <code>wrap()</code> should be repeatedly 272 * called until the resulting <code>SSLEngineResult</code>'s status 273 * returns "CLOSED", or {@link #isOutboundDone()} returns true. All 274 * data obtained from the <code>wrap()</code> method should be sent to the 275 * peer. 276 * <P> 277 * {@link #closeOutbound()} is used to signal the engine that the 278 * application will not be sending any more data. 279 * <P> 280 * A peer will signal its intent to close by sending its own closure 281 * handshake message. After this message has been received and 282 * processed by the local <code>SSLEngine</code>'s <code>unwrap()</code> 283 * call, the application can detect the close by calling 284 * <code>unwrap()</code> and looking for a <code>SSLEngineResult</code> 285 * with status "CLOSED", or if {@link #isInboundDone()} returns true. 286 * If for some reason the peer closes the communication link without 287 * sending the proper SSL/TLS closure message, the application can 288 * detect the end-of-stream and can signal the engine via {@link 289 * #closeInbound()} that there will no more inbound messages to 290 * process. Some applications might choose to require orderly shutdown 291 * messages from a peer, in which case they can check that the closure 292 * was generated by a handshake message and not by an end-of-stream 293 * condition. 294 * <P> 295 * There are two groups of cipher suites which you will need to know 296 * about when managing cipher suites: 297 * 298 * <UL> 299 * <LI> <em>Supported</em> cipher suites: all the suites which are 300 * supported by the SSL implementation. This list is reported 301 * using {@link #getSupportedCipherSuites()}. 302 * 303 * <LI> <em>Enabled</em> cipher suites, which may be fewer than 304 * the full set of supported suites. This group is set using the 305 * {@link #setEnabledCipherSuites(String [])} method, and 306 * queried using the {@link #getEnabledCipherSuites()} method. 307 * Initially, a default set of cipher suites will be enabled on a 308 * new engine that represents the minimum suggested 309 * configuration. 310 * </UL> 311 * 312 * Implementation defaults require that only cipher suites which 313 * authenticate servers and provide confidentiality be enabled by 314 * default. Only if both sides explicitly agree to unauthenticated 315 * and/or non-private (unencrypted) communications will such a 316 * cipher suite be selected. 317 * <P> 318 * Each SSL/TLS connection must have one client and one server, thus 319 * each endpoint must decide which role to assume. This choice determines 320 * who begins the handshaking process as well as which type of messages 321 * should be sent by each party. The method {@link 322 * #setUseClientMode(boolean)} configures the mode. Once the initial 323 * handshaking has started, an <code>SSLEngine</code> can not switch 324 * between client and server modes, even when performing renegotiations. 325 * <P> 326 * Applications might choose to process delegated tasks in different 327 * threads. When an <code>SSLEngine</code> 328 * is created, the current {@link java.security.AccessControlContext} 329 * is saved. All future delegated tasks will be processed using this 330 * context: that is, all access control decisions will be made using the 331 * context captured at engine creation. 332 * <HR> 333 * 334 * <B>Concurrency Notes</B>: 335 * There are two concurrency issues to be aware of: 336 * 337 * <OL> 338 * <li>The <code>wrap()</code> and <code>unwrap()</code> methods 339 * may execute concurrently of each other. 340 * 341 * <li> The SSL/TLS protocols employ ordered packets. 342 * Applications must take care to ensure that generated packets 343 * are delivered in sequence. If packets arrive 344 * out-of-order, unexpected or fatal results may occur. 345 * <P> 346 * For example: 347 * 348 * <pre> 349 * synchronized (outboundLock) { 350 * sslEngine.wrap(src, dst); 351 * outboundQueue.put(dst); 352 * } 353 * </pre> 354 * 355 * As a corollary, two threads must not attempt to call the same method 356 * (either <code>wrap()</code> or <code>unwrap()</code>) concurrently, 357 * because there is no way to guarantee the eventual packet ordering. 358 * </OL> 359 * 360 * <h3>Default configuration for different Android versions</h3> 361 * <p>{@code SSLEngine} instances obtained from default {@link SSLContext} are configured as 362 * follows: 363 * 364 * <style type="text/css"> 365 * tr.deprecated { 366 * background-color: #ccc; 367 * color: #999; 368 * font-style: italic; 369 * } 370 * </style> 371 * 372 * <h4>Protocols</h4> 373 * <table> 374 * <thead> 375 * <tr> 376 * <th>Protocol</th> 377 * <th>Supported (API Levels)</th> 378 * <th>Enabled by default (API Levels)</th> 379 * </tr> 380 * </thead> 381 * <tbody> 382 * <tr class="deprecated"> 383 * <td>SSLv3</td> 384 * <td>1–25</td> 385 * <td>1–22</td> 386 * </tr> 387 * <tr> 388 * <td>TLSv1</td> 389 * <td>1+</td> 390 * <td>1+</td> 391 * </tr> 392 * <tr> 393 * <td>TLSv1.1</td> 394 * <td>20+</td> 395 * <td>20+</td> 396 * </tr> 397 * <tr> 398 * <td>TLSv1.2</td> 399 * <td>20+</td> 400 * <td>20+</td> 401 * </tr> 402 * </tbody> 403 * </table> 404 * 405 * <h4>Cipher suites</h4> 406 * <table> 407 * <thead> 408 * <tr> 409 * <th>Cipher suite</th> 410 * <th>Supported (API Levels)</th> 411 * <th>Enabled by default (API Levels)</th> 412 * </tr> 413 * </thead> 414 * <tbody> 415 * <tr class="deprecated"> 416 * <td>SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA</td> 417 * <td>9-22</td> 418 * <td>9-19</td> 419 * </tr> 420 * <tr class="deprecated"> 421 * <td>SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA</td> 422 * <td>9-22</td> 423 * <td>9-19</td> 424 * </tr> 425 * <tr class="deprecated"> 426 * <td>SSL_DHE_DSS_WITH_DES_CBC_SHA</td> 427 * <td>9-22</td> 428 * <td>9-19</td> 429 * </tr> 430 * <tr class="deprecated"> 431 * <td>SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA</td> 432 * <td>9-22</td> 433 * <td>9-19</td> 434 * </tr> 435 * <tr class="deprecated"> 436 * <td>SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA</td> 437 * <td>9-22</td> 438 * <td>9-19</td> 439 * </tr> 440 * <tr class="deprecated"> 441 * <td>SSL_DHE_RSA_WITH_DES_CBC_SHA</td> 442 * <td>9-22</td> 443 * <td>9-19</td> 444 * </tr> 445 * <tr class="deprecated"> 446 * <td>SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA</td> 447 * <td>9-22</td> 448 * <td></td> 449 * </tr> 450 * <tr class="deprecated"> 451 * <td>SSL_DH_anon_EXPORT_WITH_RC4_40_MD5</td> 452 * <td>9-22</td> 453 * <td></td> 454 * </tr> 455 * <tr class="deprecated"> 456 * <td>SSL_DH_anon_WITH_3DES_EDE_CBC_SHA</td> 457 * <td>9-22</td> 458 * <td></td> 459 * </tr> 460 * <tr class="deprecated"> 461 * <td>SSL_DH_anon_WITH_DES_CBC_SHA</td> 462 * <td>9-22</td> 463 * <td></td> 464 * </tr> 465 * <tr class="deprecated"> 466 * <td>SSL_DH_anon_WITH_RC4_128_MD5</td> 467 * <td>9-22</td> 468 * <td></td> 469 * </tr> 470 * <tr class="deprecated"> 471 * <td>SSL_RSA_EXPORT_WITH_DES40_CBC_SHA</td> 472 * <td>9-22</td> 473 * <td>9-19</td> 474 * </tr> 475 * <tr class="deprecated"> 476 * <td>SSL_RSA_EXPORT_WITH_RC4_40_MD5</td> 477 * <td>9-22</td> 478 * <td>9-19</td> 479 * </tr> 480 * <tr> 481 * <td>SSL_RSA_WITH_3DES_EDE_CBC_SHA</td> 482 * <td>9+</td> 483 * <td>9-19</td> 484 * </tr> 485 * <tr class="deprecated"> 486 * <td>SSL_RSA_WITH_DES_CBC_SHA</td> 487 * <td>9-22</td> 488 * <td>9-19</td> 489 * </tr> 490 * <tr class="deprecated"> 491 * <td>SSL_RSA_WITH_NULL_MD5</td> 492 * <td>9-22</td> 493 * <td></td> 494 * </tr> 495 * <tr class="deprecated"> 496 * <td>SSL_RSA_WITH_NULL_SHA</td> 497 * <td>9-22</td> 498 * <td></td> 499 * </tr> 500 * <tr class="deprecated"> 501 * <td>SSL_RSA_WITH_RC4_128_MD5</td> 502 * <td>9-25</td> 503 * <td>9-19</td> 504 * </tr> 505 * <tr class="deprecated"> 506 * <td>SSL_RSA_WITH_RC4_128_SHA</td> 507 * <td>9-25</td> 508 * <td>9-23</td> 509 * </tr> 510 * <tr class="deprecated"> 511 * <td>TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA</td> 512 * <td>1-8</td> 513 * <td>1-8</td> 514 * </tr> 515 * <tr class="deprecated"> 516 * <td>TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA</td> 517 * <td>1-8</td> 518 * <td>1-8</td> 519 * </tr> 520 * <tr class="deprecated"> 521 * <td>TLS_DHE_DSS_WITH_AES_128_CBC_SHA</td> 522 * <td>9-22</td> 523 * <td>9-22</td> 524 * </tr> 525 * <tr class="deprecated"> 526 * <td>TLS_DHE_DSS_WITH_AES_128_CBC_SHA256</td> 527 * <td>20-22</td> 528 * <td></td> 529 * </tr> 530 * <tr class="deprecated"> 531 * <td>TLS_DHE_DSS_WITH_AES_128_GCM_SHA256</td> 532 * <td>20-22</td> 533 * <td></td> 534 * </tr> 535 * <tr class="deprecated"> 536 * <td>TLS_DHE_DSS_WITH_AES_256_CBC_SHA</td> 537 * <td>9-22</td> 538 * <td>20-22</td> 539 * </tr> 540 * <tr class="deprecated"> 541 * <td>TLS_DHE_DSS_WITH_AES_256_CBC_SHA256</td> 542 * <td>20-22</td> 543 * <td></td> 544 * </tr> 545 * <tr class="deprecated"> 546 * <td>TLS_DHE_DSS_WITH_AES_256_GCM_SHA384</td> 547 * <td>20-22</td> 548 * <td></td> 549 * </tr> 550 * <tr class="deprecated"> 551 * <td>TLS_DHE_DSS_WITH_DES_CBC_SHA</td> 552 * <td>1-8</td> 553 * <td>1-8</td> 554 * </tr> 555 * <tr class="deprecated"> 556 * <td>TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA</td> 557 * <td>1-8</td> 558 * <td>1-8</td> 559 * </tr> 560 * <tr class="deprecated"> 561 * <td>TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA</td> 562 * <td>1-8</td> 563 * <td>1-8</td> 564 * </tr> 565 * <tr class="deprecated"> 566 * <td>TLS_DHE_RSA_WITH_AES_128_CBC_SHA</td> 567 * <td>9-25</td> 568 * <td>9-25</td> 569 * </tr> 570 * <tr class="deprecated"> 571 * <td>TLS_DHE_RSA_WITH_AES_128_CBC_SHA256</td> 572 * <td>20-25</td> 573 * <td></td> 574 * </tr> 575 * <tr class="deprecated"> 576 * <td>TLS_DHE_RSA_WITH_AES_128_GCM_SHA256</td> 577 * <td>20-25</td> 578 * <td>20-25</td> 579 * </tr> 580 * <tr class="deprecated"> 581 * <td>TLS_DHE_RSA_WITH_AES_256_CBC_SHA</td> 582 * <td>9-25</td> 583 * <td>20-25</td> 584 * </tr> 585 * <tr class="deprecated"> 586 * <td>TLS_DHE_RSA_WITH_AES_256_CBC_SHA256</td> 587 * <td>20-25</td> 588 * <td></td> 589 * </tr> 590 * <tr class="deprecated"> 591 * <td>TLS_DHE_RSA_WITH_AES_256_GCM_SHA384</td> 592 * <td>20-25</td> 593 * <td>20-25</td> 594 * </tr> 595 * <tr class="deprecated"> 596 * <td>TLS_DHE_RSA_WITH_DES_CBC_SHA</td> 597 * <td>1-8</td> 598 * <td>1-8</td> 599 * </tr> 600 * <tr class="deprecated"> 601 * <td>TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA</td> 602 * <td>1-8</td> 603 * <td></td> 604 * </tr> 605 * <tr class="deprecated"> 606 * <td>TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA</td> 607 * <td>1-8</td> 608 * <td></td> 609 * </tr> 610 * <tr class="deprecated"> 611 * <td>TLS_DH_DSS_WITH_DES_CBC_SHA</td> 612 * <td>1-8</td> 613 * <td></td> 614 * </tr> 615 * <tr class="deprecated"> 616 * <td>TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA</td> 617 * <td>1-8</td> 618 * <td></td> 619 * </tr> 620 * <tr class="deprecated"> 621 * <td>TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA</td> 622 * <td>1-8</td> 623 * <td></td> 624 * </tr> 625 * <tr class="deprecated"> 626 * <td>TLS_DH_RSA_WITH_DES_CBC_SHA</td> 627 * <td>1-8</td> 628 * <td></td> 629 * </tr> 630 * <tr class="deprecated"> 631 * <td>TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA</td> 632 * <td>1-8</td> 633 * <td></td> 634 * </tr> 635 * <tr class="deprecated"> 636 * <td>TLS_DH_anon_WITH_3DES_EDE_CBC_SHA</td> 637 * <td>1-8</td> 638 * <td></td> 639 * </tr> 640 * <tr class="deprecated"> 641 * <td>TLS_DH_anon_WITH_AES_128_CBC_SHA</td> 642 * <td>9-22</td> 643 * <td></td> 644 * </tr> 645 * <tr class="deprecated"> 646 * <td>TLS_DH_anon_WITH_AES_128_CBC_SHA256</td> 647 * <td>20-22</td> 648 * <td></td> 649 * </tr> 650 * <tr class="deprecated"> 651 * <td>TLS_DH_anon_WITH_AES_128_GCM_SHA256</td> 652 * <td>20-22</td> 653 * <td></td> 654 * </tr> 655 * <tr class="deprecated"> 656 * <td>TLS_DH_anon_WITH_AES_256_CBC_SHA</td> 657 * <td>9-22</td> 658 * <td></td> 659 * </tr> 660 * <tr class="deprecated"> 661 * <td>TLS_DH_anon_WITH_AES_256_CBC_SHA256</td> 662 * <td>20-22</td> 663 * <td></td> 664 * </tr> 665 * <tr class="deprecated"> 666 * <td>TLS_DH_anon_WITH_AES_256_GCM_SHA384</td> 667 * <td>20-22</td> 668 * <td></td> 669 * </tr> 670 * <tr class="deprecated"> 671 * <td>TLS_DH_anon_WITH_DES_CBC_SHA</td> 672 * <td>1-8</td> 673 * <td></td> 674 * </tr> 675 * <tr class="deprecated"> 676 * <td>TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA</td> 677 * <td>20-22</td> 678 * <td></td> 679 * </tr> 680 * <tr> 681 * <td>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</td> 682 * <td>20+</td> 683 * <td>20+</td> 684 * </tr> 685 * <tr> 686 * <td>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256</td> 687 * <td>20+</td> 688 * <td></td> 689 * </tr> 690 * <tr> 691 * <td>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</td> 692 * <td>20+</td> 693 * <td>20+</td> 694 * </tr> 695 * <tr> 696 * <td>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</td> 697 * <td>20+</td> 698 * <td>20+</td> 699 * </tr> 700 * <tr> 701 * <td>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384</td> 702 * <td>20+</td> 703 * <td></td> 704 * </tr> 705 * <tr> 706 * <td>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</td> 707 * <td>20+</td> 708 * <td>20+</td> 709 * </tr> 710 * <tr> 711 * <td>TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256</td> 712 * <td>24+</td> 713 * <td>24+</td> 714 * </tr> 715 * <tr class="deprecated"> 716 * <td>TLS_ECDHE_ECDSA_WITH_NULL_SHA</td> 717 * <td>20-22</td> 718 * <td></td> 719 * </tr> 720 * <tr class="deprecated"> 721 * <td>TLS_ECDHE_ECDSA_WITH_RC4_128_SHA</td> 722 * <td>20-25</td> 723 * <td>20-23</td> 724 * </tr> 725 * <tr> 726 * <td>TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA</td> 727 * <td>21+</td> 728 * <td>21+</td> 729 * </tr> 730 * <tr> 731 * <td>TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA</td> 732 * <td>21+</td> 733 * <td>21+</td> 734 * </tr> 735 * <tr> 736 * <td>TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256</td> 737 * <td>24+</td> 738 * <td>24+</td> 739 * </tr> 740 * <tr class="deprecated"> 741 * <td>TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA</td> 742 * <td>20-22</td> 743 * <td></td> 744 * </tr> 745 * <tr> 746 * <td>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</td> 747 * <td>20+</td> 748 * <td>20+</td> 749 * </tr> 750 * <tr> 751 * <td>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</td> 752 * <td>20+</td> 753 * <td></td> 754 * </tr> 755 * <tr> 756 * <td>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</td> 757 * <td>20+</td> 758 * <td>20+</td> 759 * </tr> 760 * <tr> 761 * <td>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</td> 762 * <td>20+</td> 763 * <td>20+</td> 764 * </tr> 765 * <tr> 766 * <td>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384</td> 767 * <td>20+</td> 768 * <td></td> 769 * </tr> 770 * <tr> 771 * <td>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</td> 772 * <td>20+</td> 773 * <td>20+</td> 774 * </tr> 775 * <tr> 776 * <td>TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256</td> 777 * <td>24+</td> 778 * <td>24+</td> 779 * </tr> 780 * <tr class="deprecated"> 781 * <td>TLS_ECDHE_RSA_WITH_NULL_SHA</td> 782 * <td>20-22</td> 783 * <td></td> 784 * </tr> 785 * <tr class="deprecated"> 786 * <td>TLS_ECDHE_RSA_WITH_RC4_128_SHA</td> 787 * <td>20-25</td> 788 * <td>20-23</td> 789 * </tr> 790 * <tr class="deprecated"> 791 * <td>TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA</td> 792 * <td>20-22</td> 793 * <td></td> 794 * </tr> 795 * <tr class="deprecated"> 796 * <td>TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA</td> 797 * <td>20-22</td> 798 * <td></td> 799 * </tr> 800 * <tr class="deprecated"> 801 * <td>TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256</td> 802 * <td>20-22</td> 803 * <td></td> 804 * </tr> 805 * <tr class="deprecated"> 806 * <td>TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256</td> 807 * <td>20-22</td> 808 * <td></td> 809 * </tr> 810 * <tr class="deprecated"> 811 * <td>TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA</td> 812 * <td>20-22</td> 813 * <td></td> 814 * </tr> 815 * <tr class="deprecated"> 816 * <td>TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384</td> 817 * <td>20-22</td> 818 * <td></td> 819 * </tr> 820 * <tr class="deprecated"> 821 * <td>TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384</td> 822 * <td>20-22</td> 823 * <td></td> 824 * </tr> 825 * <tr class="deprecated"> 826 * <td>TLS_ECDH_ECDSA_WITH_NULL_SHA</td> 827 * <td>20-22</td> 828 * <td></td> 829 * </tr> 830 * <tr class="deprecated"> 831 * <td>TLS_ECDH_ECDSA_WITH_RC4_128_SHA</td> 832 * <td>20-22</td> 833 * <td></td> 834 * </tr> 835 * <tr class="deprecated"> 836 * <td>TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA</td> 837 * <td>20-22</td> 838 * <td></td> 839 * </tr> 840 * <tr class="deprecated"> 841 * <td>TLS_ECDH_RSA_WITH_AES_128_CBC_SHA</td> 842 * <td>20-22</td> 843 * <td></td> 844 * </tr> 845 * <tr class="deprecated"> 846 * <td>TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256</td> 847 * <td>20-22</td> 848 * <td></td> 849 * </tr> 850 * <tr class="deprecated"> 851 * <td>TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256</td> 852 * <td>20-22</td> 853 * <td></td> 854 * </tr> 855 * <tr class="deprecated"> 856 * <td>TLS_ECDH_RSA_WITH_AES_256_CBC_SHA</td> 857 * <td>20-22</td> 858 * <td></td> 859 * </tr> 860 * <tr class="deprecated"> 861 * <td>TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384</td> 862 * <td>20-22</td> 863 * <td></td> 864 * </tr> 865 * <tr class="deprecated"> 866 * <td>TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384</td> 867 * <td>20-22</td> 868 * <td></td> 869 * </tr> 870 * <tr class="deprecated"> 871 * <td>TLS_ECDH_RSA_WITH_NULL_SHA</td> 872 * <td>20-22</td> 873 * <td></td> 874 * </tr> 875 * <tr class="deprecated"> 876 * <td>TLS_ECDH_RSA_WITH_RC4_128_SHA</td> 877 * <td>20-22</td> 878 * <td></td> 879 * </tr> 880 * <tr class="deprecated"> 881 * <td>TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA</td> 882 * <td>20-22</td> 883 * <td></td> 884 * </tr> 885 * <tr class="deprecated"> 886 * <td>TLS_ECDH_anon_WITH_AES_128_CBC_SHA</td> 887 * <td>20-22</td> 888 * <td></td> 889 * </tr> 890 * <tr class="deprecated"> 891 * <td>TLS_ECDH_anon_WITH_AES_256_CBC_SHA</td> 892 * <td>20-22</td> 893 * <td></td> 894 * </tr> 895 * <tr class="deprecated"> 896 * <td>TLS_ECDH_anon_WITH_NULL_SHA</td> 897 * <td>20-22</td> 898 * <td></td> 899 * </tr> 900 * <tr class="deprecated"> 901 * <td>TLS_ECDH_anon_WITH_RC4_128_SHA</td> 902 * <td>20-22</td> 903 * <td></td> 904 * </tr> 905 * <tr> 906 * <td>TLS_EMPTY_RENEGOTIATION_INFO_SCSV</td> 907 * <td>20+</td> 908 * <td>20+</td> 909 * </tr> 910 * <tr> 911 * <td>TLS_FALLBACK_SCSV</td> 912 * <td>21+</td> 913 * <td></td> 914 * </tr> 915 * <tr class="deprecated"> 916 * <td>TLS_NULL_WITH_NULL_NULL</td> 917 * <td>1-8</td> 918 * <td></td> 919 * </tr> 920 * <tr class="deprecated"> 921 * <td>TLS_PSK_WITH_3DES_EDE_CBC_SHA</td> 922 * <td>21-22</td> 923 * <td></td> 924 * </tr> 925 * <tr> 926 * <td>TLS_PSK_WITH_AES_128_CBC_SHA</td> 927 * <td>21+</td> 928 * <td>21+</td> 929 * </tr> 930 * <tr> 931 * <td>TLS_PSK_WITH_AES_256_CBC_SHA</td> 932 * <td>21+</td> 933 * <td>21+</td> 934 * </tr> 935 * <tr class="deprecated"> 936 * <td>TLS_PSK_WITH_RC4_128_SHA</td> 937 * <td>21-25</td> 938 * <td></td> 939 * </tr> 940 * <tr class="deprecated"> 941 * <td>TLS_RSA_EXPORT_WITH_DES40_CBC_SHA</td> 942 * <td>1-8</td> 943 * <td>1-8</td> 944 * </tr> 945 * <tr class="deprecated"> 946 * <td>TLS_RSA_WITH_3DES_EDE_CBC_SHA</td> 947 * <td>1-8</td> 948 * <td>1-8</td> 949 * </tr> 950 * <tr> 951 * <td>TLS_RSA_WITH_AES_128_CBC_SHA</td> 952 * <td>9+</td> 953 * <td>9+</td> 954 * </tr> 955 * <tr> 956 * <td>TLS_RSA_WITH_AES_128_CBC_SHA256</td> 957 * <td>20+</td> 958 * <td></td> 959 * </tr> 960 * <tr> 961 * <td>TLS_RSA_WITH_AES_128_GCM_SHA256</td> 962 * <td>20+</td> 963 * <td>20+</td> 964 * </tr> 965 * <tr> 966 * <td>TLS_RSA_WITH_AES_256_CBC_SHA</td> 967 * <td>9+</td> 968 * <td>20+</td> 969 * </tr> 970 * <tr> 971 * <td>TLS_RSA_WITH_AES_256_CBC_SHA256</td> 972 * <td>20+</td> 973 * <td></td> 974 * </tr> 975 * <tr> 976 * <td>TLS_RSA_WITH_AES_256_GCM_SHA384</td> 977 * <td>20+</td> 978 * <td>20+</td> 979 * </tr> 980 * <tr class="deprecated"> 981 * <td>TLS_RSA_WITH_DES_CBC_SHA</td> 982 * <td>1-8</td> 983 * <td>1-8</td> 984 * </tr> 985 * <tr class="deprecated"> 986 * <td>TLS_RSA_WITH_NULL_MD5</td> 987 * <td>1-8</td> 988 * <td></td> 989 * </tr> 990 * <tr class="deprecated"> 991 * <td>TLS_RSA_WITH_NULL_SHA</td> 992 * <td>1-8</td> 993 * <td></td> 994 * </tr> 995 * <tr class="deprecated"> 996 * <td>TLS_RSA_WITH_NULL_SHA256</td> 997 * <td>20-22</td> 998 * <td></td> 999 * </tr> 1000 * </tbody> 1001 * </table> 1002 * 1003 * <p><em>NOTE</em>: PSK cipher suites are enabled by default only if the {@code SSLContext} through 1004 * which the engine was created has been initialized with a {@code PSKKeyManager}. 1005 * 1006 * @see SSLContext 1007 * @see SSLSocket 1008 * @see SSLServerSocket 1009 * @see SSLSession 1010 * @see java.net.Socket 1011 * 1012 * @since 1.5 1013 * @author Brad R. Wetmore 1014 */ 1015 1016 public abstract class SSLEngine { 1017 1018 private String peerHost = null; 1019 private int peerPort = -1; 1020 1021 /** 1022 * Constructor for an <code>SSLEngine</code> providing no hints 1023 * for an internal session reuse strategy. 1024 * 1025 * @see SSLContext#createSSLEngine() 1026 * @see SSLSessionContext 1027 */ SSLEngine()1028 protected SSLEngine() { 1029 } 1030 1031 /** 1032 * Constructor for an <code>SSLEngine</code>. 1033 * <P> 1034 * <code>SSLEngine</code> implementations may use the 1035 * <code>peerHost</code> and <code>peerPort</code> parameters as hints 1036 * for their internal session reuse strategy. 1037 * <P> 1038 * Some cipher suites (such as Kerberos) require remote hostname 1039 * information. Implementations of this class should use this 1040 * constructor to use Kerberos. 1041 * <P> 1042 * The parameters are not authenticated by the 1043 * <code>SSLEngine</code>. 1044 * 1045 * @param peerHost the name of the peer host 1046 * @param peerPort the port number of the peer 1047 * @see SSLContext#createSSLEngine(String, int) 1048 * @see SSLSessionContext 1049 */ SSLEngine(String peerHost, int peerPort)1050 protected SSLEngine(String peerHost, int peerPort) { 1051 this.peerHost = peerHost; 1052 this.peerPort = peerPort; 1053 } 1054 1055 /** 1056 * Returns the host name of the peer. 1057 * <P> 1058 * Note that the value is not authenticated, and should not be 1059 * relied upon. 1060 * 1061 * @return the host name of the peer, or null if nothing is 1062 * available. 1063 */ getPeerHost()1064 public String getPeerHost() { 1065 return peerHost; 1066 } 1067 1068 /** 1069 * Returns the port number of the peer. 1070 * <P> 1071 * Note that the value is not authenticated, and should not be 1072 * relied upon. 1073 * 1074 * @return the port number of the peer, or -1 if nothing is 1075 * available. 1076 */ getPeerPort()1077 public int getPeerPort() { 1078 return peerPort; 1079 } 1080 1081 /** 1082 * Attempts to encode a buffer of plaintext application data into 1083 * SSL/TLS network data. 1084 * <P> 1085 * An invocation of this method behaves in exactly the same manner 1086 * as the invocation: 1087 * <blockquote><pre> 1088 * {@link #wrap(ByteBuffer [], int, int, ByteBuffer) 1089 * engine.wrap(new ByteBuffer [] { src }, 0, 1, dst);} 1090 * </pre></blockquote> 1091 * 1092 * @param src 1093 * a <code>ByteBuffer</code> containing outbound application data 1094 * @param dst 1095 * a <code>ByteBuffer</code> to hold outbound network data 1096 * @return an <code>SSLEngineResult</code> describing the result 1097 * of this operation. 1098 * @throws SSLException 1099 * A problem was encountered while processing the 1100 * data that caused the <code>SSLEngine</code> to abort. 1101 * See the class description for more information on 1102 * engine closure. 1103 * @throws ReadOnlyBufferException 1104 * if the <code>dst</code> buffer is read-only. 1105 * @throws IllegalArgumentException 1106 * if either <code>src</code> or <code>dst</code> 1107 * is null. 1108 * @throws IllegalStateException if the client/server mode 1109 * has not yet been set. 1110 * @see #wrap(ByteBuffer [], int, int, ByteBuffer) 1111 */ wrap(ByteBuffer src, ByteBuffer dst)1112 public SSLEngineResult wrap(ByteBuffer src, 1113 ByteBuffer dst) throws SSLException { 1114 return wrap(new ByteBuffer [] { src }, 0, 1, dst); 1115 } 1116 1117 /** 1118 * Attempts to encode plaintext bytes from a sequence of data 1119 * buffers into SSL/TLS network data. 1120 * <P> 1121 * An invocation of this method behaves in exactly the same manner 1122 * as the invocation: 1123 * <blockquote><pre> 1124 * {@link #wrap(ByteBuffer [], int, int, ByteBuffer) 1125 * engine.wrap(srcs, 0, srcs.length, dst);} 1126 * </pre></blockquote> 1127 * 1128 * @param srcs 1129 * an array of <code>ByteBuffers</code> containing the 1130 * outbound application data 1131 * @param dst 1132 * a <code>ByteBuffer</code> to hold outbound network data 1133 * @return an <code>SSLEngineResult</code> describing the result 1134 * of this operation. 1135 * @throws SSLException 1136 * A problem was encountered while processing the 1137 * data that caused the <code>SSLEngine</code> to abort. 1138 * See the class description for more information on 1139 * engine closure. 1140 * @throws ReadOnlyBufferException 1141 * if the <code>dst</code> buffer is read-only. 1142 * @throws IllegalArgumentException 1143 * if either <code>srcs</code> or <code>dst</code> 1144 * is null, or if any element in <code>srcs</code> is null. 1145 * @throws IllegalStateException if the client/server mode 1146 * has not yet been set. 1147 * @see #wrap(ByteBuffer [], int, int, ByteBuffer) 1148 */ wrap(ByteBuffer [] srcs, ByteBuffer dst)1149 public SSLEngineResult wrap(ByteBuffer [] srcs, 1150 ByteBuffer dst) throws SSLException { 1151 if (srcs == null) { 1152 throw new IllegalArgumentException("src == null"); 1153 } 1154 return wrap(srcs, 0, srcs.length, dst); 1155 } 1156 1157 1158 /** 1159 * Attempts to encode plaintext bytes from a subsequence of data 1160 * buffers into SSL/TLS network data. This <i>"gathering"</i> 1161 * operation encodes, in a single invocation, a sequence of bytes 1162 * from one or more of a given sequence of buffers. Gathering 1163 * wraps are often useful when implementing network protocols or 1164 * file formats that, for example, group data into segments 1165 * consisting of one or more fixed-length headers followed by a 1166 * variable-length body. See 1167 * {@link java.nio.channels.GatheringByteChannel} for more 1168 * information on gathering, and {@link 1169 * java.nio.channels.GatheringByteChannel#write(ByteBuffer[], 1170 * int, int)} for more information on the subsequence 1171 * behavior. 1172 * <P> 1173 * Depending on the state of the SSLEngine, this method may produce 1174 * network data without consuming any application data (for example, 1175 * it may generate handshake data.) 1176 * <P> 1177 * The application is responsible for reliably transporting the 1178 * network data to the peer, and for ensuring that data created by 1179 * multiple calls to wrap() is transported in the same order in which 1180 * it was generated. The application must properly synchronize 1181 * multiple calls to this method. 1182 * <P> 1183 * If this <code>SSLEngine</code> has not yet started its initial 1184 * handshake, this method will automatically start the handshake. 1185 * <P> 1186 * This method will attempt to produce one SSL/TLS packet, and will 1187 * consume as much source data as possible, but will never consume 1188 * more than the sum of the bytes remaining in each buffer. Each 1189 * <code>ByteBuffer</code>'s position is updated to reflect the 1190 * amount of data consumed or produced. The limits remain the 1191 * same. 1192 * <P> 1193 * The underlying memory used by the <code>srcs</code> and 1194 * <code>dst ByteBuffer</code>s must not be the same. 1195 * <P> 1196 * See the class description for more information on engine closure. 1197 * 1198 * @param srcs 1199 * an array of <code>ByteBuffers</code> containing the 1200 * outbound application data 1201 * @param offset 1202 * The offset within the buffer array of the first buffer from 1203 * which bytes are to be retrieved; it must be non-negative 1204 * and no larger than <code>srcs.length</code> 1205 * @param length 1206 * The maximum number of buffers to be accessed; it must be 1207 * non-negative and no larger than 1208 * <code>srcs.length</code> - <code>offset</code> 1209 * @param dst 1210 * a <code>ByteBuffer</code> to hold outbound network data 1211 * @return an <code>SSLEngineResult</code> describing the result 1212 * of this operation. 1213 * @throws SSLException 1214 * A problem was encountered while processing the 1215 * data that caused the <code>SSLEngine</code> to abort. 1216 * See the class description for more information on 1217 * engine closure. 1218 * @throws IndexOutOfBoundsException 1219 * if the preconditions on the <code>offset</code> and 1220 * <code>length</code> parameters do not hold. 1221 * @throws ReadOnlyBufferException 1222 * if the <code>dst</code> buffer is read-only. 1223 * @throws IllegalArgumentException 1224 * if either <code>srcs</code> or <code>dst</code> 1225 * is null, or if any element in the <code>srcs</code> 1226 * subsequence specified is null. 1227 * @throws IllegalStateException if the client/server mode 1228 * has not yet been set. 1229 * @see java.nio.channels.GatheringByteChannel 1230 * @see java.nio.channels.GatheringByteChannel#write( 1231 * ByteBuffer[], int, int) 1232 */ wrap(ByteBuffer [] srcs, int offset, int length, ByteBuffer dst)1233 public abstract SSLEngineResult wrap(ByteBuffer [] srcs, int offset, 1234 int length, ByteBuffer dst) throws SSLException; 1235 1236 /** 1237 * Attempts to decode SSL/TLS network data into a plaintext 1238 * application data buffer. 1239 * <P> 1240 * An invocation of this method behaves in exactly the same manner 1241 * as the invocation: 1242 * <blockquote><pre> 1243 * {@link #unwrap(ByteBuffer, ByteBuffer [], int, int) 1244 * engine.unwrap(src, new ByteBuffer [] { dst }, 0, 1);} 1245 * </pre></blockquote> 1246 * 1247 * @param src 1248 * a <code>ByteBuffer</code> containing inbound network data. 1249 * @param dst 1250 * a <code>ByteBuffer</code> to hold inbound application data. 1251 * @return an <code>SSLEngineResult</code> describing the result 1252 * of this operation. 1253 * @throws SSLException 1254 * A problem was encountered while processing the 1255 * data that caused the <code>SSLEngine</code> to abort. 1256 * See the class description for more information on 1257 * engine closure. 1258 * @throws ReadOnlyBufferException 1259 * if the <code>dst</code> buffer is read-only. 1260 * @throws IllegalArgumentException 1261 * if either <code>src</code> or <code>dst</code> 1262 * is null. 1263 * @throws IllegalStateException if the client/server mode 1264 * has not yet been set. 1265 * @see #unwrap(ByteBuffer, ByteBuffer [], int, int) 1266 */ unwrap(ByteBuffer src, ByteBuffer dst)1267 public SSLEngineResult unwrap(ByteBuffer src, 1268 ByteBuffer dst) throws SSLException { 1269 return unwrap(src, new ByteBuffer [] { dst }, 0, 1); 1270 } 1271 1272 /** 1273 * Attempts to decode SSL/TLS network data into a sequence of plaintext 1274 * application data buffers. 1275 * <P> 1276 * An invocation of this method behaves in exactly the same manner 1277 * as the invocation: 1278 * <blockquote><pre> 1279 * {@link #unwrap(ByteBuffer, ByteBuffer [], int, int) 1280 * engine.unwrap(src, dsts, 0, dsts.length);} 1281 * </pre></blockquote> 1282 * 1283 * @param src 1284 * a <code>ByteBuffer</code> containing inbound network data. 1285 * @param dsts 1286 * an array of <code>ByteBuffer</code>s to hold inbound 1287 * application data. 1288 * @return an <code>SSLEngineResult</code> describing the result 1289 * of this operation. 1290 * @throws SSLException 1291 * A problem was encountered while processing the 1292 * data that caused the <code>SSLEngine</code> to abort. 1293 * See the class description for more information on 1294 * engine closure. 1295 * @throws ReadOnlyBufferException 1296 * if any of the <code>dst</code> buffers are read-only. 1297 * @throws IllegalArgumentException 1298 * if either <code>src</code> or <code>dsts</code> 1299 * is null, or if any element in <code>dsts</code> is null. 1300 * @throws IllegalStateException if the client/server mode 1301 * has not yet been set. 1302 * @see #unwrap(ByteBuffer, ByteBuffer [], int, int) 1303 */ unwrap(ByteBuffer src, ByteBuffer [] dsts)1304 public SSLEngineResult unwrap(ByteBuffer src, 1305 ByteBuffer [] dsts) throws SSLException { 1306 if (dsts == null) { 1307 throw new IllegalArgumentException("dsts == null"); 1308 } 1309 return unwrap(src, dsts, 0, dsts.length); 1310 } 1311 1312 /** 1313 * Attempts to decode SSL/TLS network data into a subsequence of 1314 * plaintext application data buffers. This <i>"scattering"</i> 1315 * operation decodes, in a single invocation, a sequence of bytes 1316 * into one or more of a given sequence of buffers. Scattering 1317 * unwraps are often useful when implementing network protocols or 1318 * file formats that, for example, group data into segments 1319 * consisting of one or more fixed-length headers followed by a 1320 * variable-length body. See 1321 * {@link java.nio.channels.ScatteringByteChannel} for more 1322 * information on scattering, and {@link 1323 * java.nio.channels.ScatteringByteChannel#read(ByteBuffer[], 1324 * int, int)} for more information on the subsequence 1325 * behavior. 1326 * <P> 1327 * Depending on the state of the SSLEngine, this method may consume 1328 * network data without producing any application data (for example, 1329 * it may consume handshake data.) 1330 * <P> 1331 * The application is responsible for reliably obtaining the network 1332 * data from the peer, and for invoking unwrap() on the data in the 1333 * order it was received. The application must properly synchronize 1334 * multiple calls to this method. 1335 * <P> 1336 * If this <code>SSLEngine</code> has not yet started its initial 1337 * handshake, this method will automatically start the handshake. 1338 * <P> 1339 * This method will attempt to consume one complete SSL/TLS network 1340 * packet, but will never consume more than the sum of the bytes 1341 * remaining in the buffers. Each <code>ByteBuffer</code>'s 1342 * position is updated to reflect the amount of data consumed or 1343 * produced. The limits remain the same. 1344 * <P> 1345 * The underlying memory used by the <code>src</code> and 1346 * <code>dsts ByteBuffer</code>s must not be the same. 1347 * <P> 1348 * The inbound network buffer may be modified as a result of this 1349 * call: therefore if the network data packet is required for some 1350 * secondary purpose, the data should be duplicated before calling this 1351 * method. Note: the network data will not be useful to a second 1352 * SSLEngine, as each SSLEngine contains unique random state which 1353 * influences the SSL/TLS messages. 1354 * <P> 1355 * See the class description for more information on engine closure. 1356 * 1357 * @param src 1358 * a <code>ByteBuffer</code> containing inbound network data. 1359 * @param dsts 1360 * an array of <code>ByteBuffer</code>s to hold inbound 1361 * application data. 1362 * @param offset 1363 * The offset within the buffer array of the first buffer from 1364 * which bytes are to be transferred; it must be non-negative 1365 * and no larger than <code>dsts.length</code>. 1366 * @param length 1367 * The maximum number of buffers to be accessed; it must be 1368 * non-negative and no larger than 1369 * <code>dsts.length</code> - <code>offset</code>. 1370 * @return an <code>SSLEngineResult</code> describing the result 1371 * of this operation. 1372 * @throws SSLException 1373 * A problem was encountered while processing the 1374 * data that caused the <code>SSLEngine</code> to abort. 1375 * See the class description for more information on 1376 * engine closure. 1377 * @throws IndexOutOfBoundsException 1378 * If the preconditions on the <code>offset</code> and 1379 * <code>length</code> parameters do not hold. 1380 * @throws ReadOnlyBufferException 1381 * if any of the <code>dst</code> buffers are read-only. 1382 * @throws IllegalArgumentException 1383 * if either <code>src</code> or <code>dsts</code> 1384 * is null, or if any element in the <code>dsts</code> 1385 * subsequence specified is null. 1386 * @throws IllegalStateException if the client/server mode 1387 * has not yet been set. 1388 * @see java.nio.channels.ScatteringByteChannel 1389 * @see java.nio.channels.ScatteringByteChannel#read( 1390 * ByteBuffer[], int, int) 1391 */ unwrap(ByteBuffer src, ByteBuffer [] dsts, int offset, int length)1392 public abstract SSLEngineResult unwrap(ByteBuffer src, 1393 ByteBuffer [] dsts, int offset, int length) throws SSLException; 1394 1395 1396 /** 1397 * Returns a delegated <code>Runnable</code> task for 1398 * this <code>SSLEngine</code>. 1399 * <P> 1400 * <code>SSLEngine</code> operations may require the results of 1401 * operations that block, or may take an extended period of time to 1402 * complete. This method is used to obtain an outstanding {@link 1403 * java.lang.Runnable} operation (task). Each task must be assigned 1404 * a thread (possibly the current) to perform the {@link 1405 * java.lang.Runnable#run() run} operation. Once the 1406 * <code>run</code> method returns, the <code>Runnable</code> object 1407 * is no longer needed and may be discarded. 1408 * <P> 1409 * Delegated tasks run in the <code>AccessControlContext</code> 1410 * in place when this object was created. 1411 * <P> 1412 * A call to this method will return each outstanding task 1413 * exactly once. 1414 * <P> 1415 * Multiple delegated tasks can be run in parallel. 1416 * 1417 * @return a delegated <code>Runnable</code> task, or null 1418 * if none are available. 1419 */ getDelegatedTask()1420 public abstract Runnable getDelegatedTask(); 1421 1422 1423 /** 1424 * Signals that no more inbound network data will be sent 1425 * to this <code>SSLEngine</code>. 1426 * <P> 1427 * If the application initiated the closing process by calling 1428 * {@link #closeOutbound()}, under some circumstances it is not 1429 * required that the initiator wait for the peer's corresponding 1430 * close message. (See section 7.2.1 of the TLS specification (<A 1431 * HREF="http://www.ietf.org/rfc/rfc2246.txt">RFC 2246</A>) for more 1432 * information on waiting for closure alerts.) In such cases, this 1433 * method need not be called. 1434 * <P> 1435 * But if the application did not initiate the closure process, or 1436 * if the circumstances above do not apply, this method should be 1437 * called whenever the end of the SSL/TLS data stream is reached. 1438 * This ensures closure of the inbound side, and checks that the 1439 * peer followed the SSL/TLS close procedure properly, thus 1440 * detecting possible truncation attacks. 1441 * <P> 1442 * This method is idempotent: if the inbound side has already 1443 * been closed, this method does not do anything. 1444 * <P> 1445 * {@link #wrap(ByteBuffer, ByteBuffer) wrap()} should be 1446 * called to flush any remaining handshake data. 1447 * 1448 * @throws SSLException 1449 * if this engine has not received the proper SSL/TLS close 1450 * notification message from the peer. 1451 * 1452 * @see #isInboundDone() 1453 * @see #isOutboundDone() 1454 */ closeInbound()1455 public abstract void closeInbound() throws SSLException; 1456 1457 1458 /** 1459 * Returns whether {@link #unwrap(ByteBuffer, ByteBuffer)} will 1460 * accept any more inbound data messages. 1461 * 1462 * @return true if the <code>SSLEngine</code> will not 1463 * consume anymore network data (and by implication, 1464 * will not produce any more application data.) 1465 * @see #closeInbound() 1466 */ isInboundDone()1467 public abstract boolean isInboundDone(); 1468 1469 1470 /** 1471 * Signals that no more outbound application data will be sent 1472 * on this <code>SSLEngine</code>. 1473 * <P> 1474 * This method is idempotent: if the outbound side has already 1475 * been closed, this method does not do anything. 1476 * <P> 1477 * {@link #wrap(ByteBuffer, ByteBuffer)} should be 1478 * called to flush any remaining handshake data. 1479 * 1480 * @see #isOutboundDone() 1481 */ closeOutbound()1482 public abstract void closeOutbound(); 1483 1484 1485 /** 1486 * Returns whether {@link #wrap(ByteBuffer, ByteBuffer)} will 1487 * produce any more outbound data messages. 1488 * <P> 1489 * Note that during the closure phase, a <code>SSLEngine</code> may 1490 * generate handshake closure data that must be sent to the peer. 1491 * <code>wrap()</code> must be called to generate this data. When 1492 * this method returns true, no more outbound data will be created. 1493 * 1494 * @return true if the <code>SSLEngine</code> will not produce 1495 * any more network data 1496 * 1497 * @see #closeOutbound() 1498 * @see #closeInbound() 1499 */ isOutboundDone()1500 public abstract boolean isOutboundDone(); 1501 1502 1503 /** 1504 * Returns the names of the cipher suites which could be enabled for use 1505 * on this engine. Normally, only a subset of these will actually 1506 * be enabled by default, since this list may include cipher suites which 1507 * do not meet quality of service requirements for those defaults. Such 1508 * cipher suites might be useful in specialized applications. 1509 * 1510 * @return an array of cipher suite names 1511 * @see #getEnabledCipherSuites() 1512 * @see #setEnabledCipherSuites(String []) 1513 */ getSupportedCipherSuites()1514 public abstract String [] getSupportedCipherSuites(); 1515 1516 1517 /** 1518 * Returns the names of the SSL cipher suites which are currently 1519 * enabled for use on this engine. When an SSLEngine is first 1520 * created, all enabled cipher suites support a minimum quality of 1521 * service. Thus, in some environments this value might be empty. 1522 * <P> 1523 * Even if a suite has been enabled, it might never be used. (For 1524 * example, the peer does not support it, the requisite 1525 * certificates/private keys for the suite are not available, or an 1526 * anonymous suite is enabled but authentication is required.) 1527 * 1528 * @return an array of cipher suite names 1529 * @see #getSupportedCipherSuites() 1530 * @see #setEnabledCipherSuites(String []) 1531 */ getEnabledCipherSuites()1532 public abstract String [] getEnabledCipherSuites(); 1533 1534 1535 /** 1536 * Sets the cipher suites enabled for use on this engine. 1537 * <P> 1538 * Each cipher suite in the <code>suites</code> parameter must have 1539 * been listed by getSupportedCipherSuites(), or the method will 1540 * fail. Following a successful call to this method, only suites 1541 * listed in the <code>suites</code> parameter are enabled for use. 1542 * <P> 1543 * See {@link #getEnabledCipherSuites()} for more information 1544 * on why a specific cipher suite may never be used on a engine. 1545 * 1546 * @param suites Names of all the cipher suites to enable 1547 * @throws IllegalArgumentException when one or more of the ciphers 1548 * named by the parameter is not supported, or when the 1549 * parameter is null. 1550 * @see #getSupportedCipherSuites() 1551 * @see #getEnabledCipherSuites() 1552 */ setEnabledCipherSuites(String suites [])1553 public abstract void setEnabledCipherSuites(String suites []); 1554 1555 1556 /** 1557 * Returns the names of the protocols which could be enabled for use 1558 * with this <code>SSLEngine</code>. 1559 * 1560 * @return an array of protocols supported 1561 */ getSupportedProtocols()1562 public abstract String [] getSupportedProtocols(); 1563 1564 1565 /** 1566 * Returns the names of the protocol versions which are currently 1567 * enabled for use with this <code>SSLEngine</code>. 1568 * 1569 * @return an array of protocols 1570 * @see #setEnabledProtocols(String []) 1571 */ getEnabledProtocols()1572 public abstract String [] getEnabledProtocols(); 1573 1574 1575 /** 1576 * Set the protocol versions enabled for use on this engine. 1577 * <P> 1578 * The protocols must have been listed by getSupportedProtocols() 1579 * as being supported. Following a successful call to this method, 1580 * only protocols listed in the <code>protocols</code> parameter 1581 * are enabled for use. 1582 * 1583 * @param protocols Names of all the protocols to enable. 1584 * @throws IllegalArgumentException when one or more of 1585 * the protocols named by the parameter is not supported or 1586 * when the protocols parameter is null. 1587 * @see #getEnabledProtocols() 1588 */ setEnabledProtocols(String protocols[])1589 public abstract void setEnabledProtocols(String protocols[]); 1590 1591 1592 /** 1593 * Returns the <code>SSLSession</code> in use in this 1594 * <code>SSLEngine</code>. 1595 * <P> 1596 * These can be long lived, and frequently correspond to an entire 1597 * login session for some user. The session specifies a particular 1598 * cipher suite which is being actively used by all connections in 1599 * that session, as well as the identities of the session's client 1600 * and server. 1601 * <P> 1602 * Unlike {@link SSLSocket#getSession()} 1603 * this method does not block until handshaking is complete. 1604 * <P> 1605 * Until the initial handshake has completed, this method returns 1606 * a session object which reports an invalid cipher suite of 1607 * "SSL_NULL_WITH_NULL_NULL". 1608 * 1609 * @return the <code>SSLSession</code> for this <code>SSLEngine</code> 1610 * @see SSLSession 1611 */ getSession()1612 public abstract SSLSession getSession(); 1613 1614 1615 /** 1616 * Returns the {@code SSLSession} being constructed during a SSL/TLS 1617 * handshake. 1618 * <p> 1619 * TLS protocols may negotiate parameters that are needed when using 1620 * an instance of this class, but before the {@code SSLSession} has 1621 * been completely initialized and made available via {@code getSession}. 1622 * For example, the list of valid signature algorithms may restrict 1623 * the type of certificates that can used during TrustManager 1624 * decisions, or the maximum TLS fragment packet sizes can be 1625 * resized to better support the network environment. 1626 * <p> 1627 * This method provides early access to the {@code SSLSession} being 1628 * constructed. Depending on how far the handshake has progressed, 1629 * some data may not yet be available for use. For example, if a 1630 * remote server will be sending a Certificate chain, but that chain 1631 * has yet not been processed, the {@code getPeerCertificates} 1632 * method of {@code SSLSession} will throw a 1633 * SSLPeerUnverifiedException. Once that chain has been processed, 1634 * {@code getPeerCertificates} will return the proper value. 1635 * 1636 * @see SSLSocket 1637 * @see SSLSession 1638 * @see ExtendedSSLSession 1639 * @see X509ExtendedKeyManager 1640 * @see X509ExtendedTrustManager 1641 * 1642 * @return null if this instance is not currently handshaking, or 1643 * if the current handshake has not progressed far enough to 1644 * create a basic SSLSession. Otherwise, this method returns the 1645 * {@code SSLSession} currently being negotiated. 1646 * @throws UnsupportedOperationException if the underlying provider 1647 * does not implement the operation. 1648 * 1649 * @since 1.7 1650 */ getHandshakeSession()1651 public SSLSession getHandshakeSession() { 1652 throw new UnsupportedOperationException(); 1653 } 1654 1655 1656 /** 1657 * Initiates handshaking (initial or renegotiation) on this SSLEngine. 1658 * <P> 1659 * This method is not needed for the initial handshake, as the 1660 * <code>wrap()</code> and <code>unwrap()</code> methods will 1661 * implicitly call this method if handshaking has not already begun. 1662 * <P> 1663 * Note that the peer may also request a session renegotiation with 1664 * this <code>SSLEngine</code> by sending the appropriate 1665 * session renegotiate handshake message. 1666 * <P> 1667 * Unlike the {@link SSLSocket#startHandshake() 1668 * SSLSocket#startHandshake()} method, this method does not block 1669 * until handshaking is completed. 1670 * <P> 1671 * To force a complete SSL/TLS session renegotiation, the current 1672 * session should be invalidated prior to calling this method. 1673 * <P> 1674 * Some protocols may not support multiple handshakes on an existing 1675 * engine and may throw an <code>SSLException</code>. 1676 * 1677 * @throws SSLException 1678 * if a problem was encountered while signaling the 1679 * <code>SSLEngine</code> to begin a new handshake. 1680 * See the class description for more information on 1681 * engine closure. 1682 * @throws IllegalStateException if the client/server mode 1683 * has not yet been set. 1684 * @see SSLSession#invalidate() 1685 */ beginHandshake()1686 public abstract void beginHandshake() throws SSLException; 1687 1688 1689 /** 1690 * Returns the current handshake status for this <code>SSLEngine</code>. 1691 * 1692 * @return the current <code>SSLEngineResult.HandshakeStatus</code>. 1693 */ getHandshakeStatus()1694 public abstract SSLEngineResult.HandshakeStatus getHandshakeStatus(); 1695 1696 1697 /** 1698 * Configures the engine to use client (or server) mode when 1699 * handshaking. 1700 * <P> 1701 * This method must be called before any handshaking occurs. 1702 * Once handshaking has begun, the mode can not be reset for the 1703 * life of this engine. 1704 * <P> 1705 * Servers normally authenticate themselves, and clients 1706 * are not required to do so. 1707 * 1708 * @param mode true if the engine should start its handshaking 1709 * in "client" mode 1710 * @throws IllegalArgumentException if a mode change is attempted 1711 * after the initial handshake has begun. 1712 * @see #getUseClientMode() 1713 */ setUseClientMode(boolean mode)1714 public abstract void setUseClientMode(boolean mode); 1715 1716 1717 /** 1718 * Returns true if the engine is set to use client mode when 1719 * handshaking. 1720 * 1721 * @return true if the engine should do handshaking 1722 * in "client" mode 1723 * @see #setUseClientMode(boolean) 1724 */ getUseClientMode()1725 public abstract boolean getUseClientMode(); 1726 1727 1728 /** 1729 * Configures the engine to <i>require</i> client authentication. This 1730 * option is only useful for engines in the server mode. 1731 * <P> 1732 * An engine's client authentication setting is one of the following: 1733 * <ul> 1734 * <li> client authentication required 1735 * <li> client authentication requested 1736 * <li> no client authentication desired 1737 * </ul> 1738 * <P> 1739 * Unlike {@link #setWantClientAuth(boolean)}, if this option is set and 1740 * the client chooses not to provide authentication information 1741 * about itself, <i>the negotiations will stop and the engine will 1742 * begin its closure procedure</i>. 1743 * <P> 1744 * Calling this method overrides any previous setting made by 1745 * this method or {@link #setWantClientAuth(boolean)}. 1746 * 1747 * @param need set to true if client authentication is required, 1748 * or false if no client authentication is desired. 1749 * @see #getNeedClientAuth() 1750 * @see #setWantClientAuth(boolean) 1751 * @see #getWantClientAuth() 1752 * @see #setUseClientMode(boolean) 1753 */ setNeedClientAuth(boolean need)1754 public abstract void setNeedClientAuth(boolean need); 1755 1756 1757 /** 1758 * Returns true if the engine will <i>require</i> client authentication. 1759 * This option is only useful to engines in the server mode. 1760 * 1761 * @return true if client authentication is required, 1762 * or false if no client authentication is desired. 1763 * @see #setNeedClientAuth(boolean) 1764 * @see #setWantClientAuth(boolean) 1765 * @see #getWantClientAuth() 1766 * @see #setUseClientMode(boolean) 1767 */ getNeedClientAuth()1768 public abstract boolean getNeedClientAuth(); 1769 1770 1771 /** 1772 * Configures the engine to <i>request</i> client authentication. 1773 * This option is only useful for engines in the server mode. 1774 * <P> 1775 * An engine's client authentication setting is one of the following: 1776 * <ul> 1777 * <li> client authentication required 1778 * <li> client authentication requested 1779 * <li> no client authentication desired 1780 * </ul> 1781 * <P> 1782 * Unlike {@link #setNeedClientAuth(boolean)}, if this option is set and 1783 * the client chooses not to provide authentication information 1784 * about itself, <i>the negotiations will continue</i>. 1785 * <P> 1786 * Calling this method overrides any previous setting made by 1787 * this method or {@link #setNeedClientAuth(boolean)}. 1788 * 1789 * @param want set to true if client authentication is requested, 1790 * or false if no client authentication is desired. 1791 * @see #getWantClientAuth() 1792 * @see #setNeedClientAuth(boolean) 1793 * @see #getNeedClientAuth() 1794 * @see #setUseClientMode(boolean) 1795 */ setWantClientAuth(boolean want)1796 public abstract void setWantClientAuth(boolean want); 1797 1798 1799 /** 1800 * Returns true if the engine will <i>request</i> client authentication. 1801 * This option is only useful for engines in the server mode. 1802 * 1803 * @return true if client authentication is requested, 1804 * or false if no client authentication is desired. 1805 * @see #setNeedClientAuth(boolean) 1806 * @see #getNeedClientAuth() 1807 * @see #setWantClientAuth(boolean) 1808 * @see #setUseClientMode(boolean) 1809 */ getWantClientAuth()1810 public abstract boolean getWantClientAuth(); 1811 1812 1813 /** 1814 * Controls whether new SSL sessions may be established by this engine. 1815 * If session creations are not allowed, and there are no 1816 * existing sessions to resume, there will be no successful 1817 * handshaking. 1818 * 1819 * @param flag true indicates that sessions may be created; this 1820 * is the default. false indicates that an existing session 1821 * must be resumed 1822 * @see #getEnableSessionCreation() 1823 */ setEnableSessionCreation(boolean flag)1824 public abstract void setEnableSessionCreation(boolean flag); 1825 1826 1827 /** 1828 * Returns true if new SSL sessions may be established by this engine. 1829 * 1830 * @return true indicates that sessions may be created; this 1831 * is the default. false indicates that an existing session 1832 * must be resumed 1833 * @see #setEnableSessionCreation(boolean) 1834 */ getEnableSessionCreation()1835 public abstract boolean getEnableSessionCreation(); 1836 1837 /** 1838 * Returns the SSLParameters in effect for this SSLEngine. 1839 * The ciphersuites and protocols of the returned SSLParameters 1840 * are always non-null. 1841 * 1842 * @return the SSLParameters in effect for this SSLEngine. 1843 * @since 1.6 1844 */ getSSLParameters()1845 public SSLParameters getSSLParameters() { 1846 SSLParameters params = new SSLParameters(); 1847 params.setCipherSuites(getEnabledCipherSuites()); 1848 params.setProtocols(getEnabledProtocols()); 1849 if (getNeedClientAuth()) { 1850 params.setNeedClientAuth(true); 1851 } else if (getWantClientAuth()) { 1852 params.setWantClientAuth(true); 1853 } 1854 return params; 1855 } 1856 1857 /** 1858 * Applies SSLParameters to this engine. 1859 * 1860 * <p>This means: 1861 * <ul> 1862 * <li>If {@code params.getCipherSuites()} is non-null, 1863 * {@code setEnabledCipherSuites()} is called with that value.</li> 1864 * <li>If {@code params.getProtocols()} is non-null, 1865 * {@code setEnabledProtocols()} is called with that value.</li> 1866 * <li>If {@code params.getNeedClientAuth()} or 1867 * {@code params.getWantClientAuth()} return {@code true}, 1868 * {@code setNeedClientAuth(true)} and 1869 * {@code setWantClientAuth(true)} are called, respectively; 1870 * otherwise {@code setWantClientAuth(false)} is called.</li> 1871 * <li>If {@code params.getServerNames()} is non-null, the engine will 1872 * configure its server names with that value.</li> 1873 * <li>If {@code params.getSNIMatchers()} is non-null, the engine will 1874 * configure its SNI matchers with that value.</li> 1875 * </ul> 1876 * 1877 * @param params the parameters 1878 * @throws IllegalArgumentException if the setEnabledCipherSuites() or 1879 * the setEnabledProtocols() call fails 1880 * @since 1.6 1881 */ setSSLParameters(SSLParameters params)1882 public void setSSLParameters(SSLParameters params) { 1883 String[] s; 1884 s = params.getCipherSuites(); 1885 if (s != null) { 1886 setEnabledCipherSuites(s); 1887 } 1888 s = params.getProtocols(); 1889 if (s != null) { 1890 setEnabledProtocols(s); 1891 } 1892 if (params.getNeedClientAuth()) { 1893 setNeedClientAuth(true); 1894 } else if (params.getWantClientAuth()) { 1895 setWantClientAuth(true); 1896 } else { 1897 setWantClientAuth(false); 1898 } 1899 } 1900 1901 } 1902