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