1/* 2 * Copyright (c) 2003, 2010, 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 26package javax.net.ssl; 27 28import java.nio.ByteBuffer; 29import 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> 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 * <P> 333 * <HR> 334 * 335 * <B>Concurrency Notes</B>: 336 * There are two concurrency issues to be aware of: 337 * 338 * <OL> 339 * <li>The <code>wrap()</code> and <code>unwrap()</code> methods 340 * may execute concurrently of each other. 341 * 342 * <li> The SSL/TLS protocols employ ordered packets. 343 * Applications must take care to ensure that generated packets 344 * are delivered in sequence. If packets arrive 345 * out-of-order, unexpected or fatal results may occur. 346 * <P> 347 * For example: 348 * <P> 349 * <pre> 350 * synchronized (outboundLock) { 351 * sslEngine.wrap(src, dst); 352 * outboundQueue.put(dst); 353 * } 354 * </pre> 355 * 356 * As a corollary, two threads must not attempt to call the same method 357 * (either <code>wrap()</code> or <code>unwrap()</code>) concurrently, 358 * because there is no way to guarantee the eventual packet ordering. 359 * </OL> 360 * 361 * <h3>Default configuration for different Android versions</h3> 362 * <p>{@code SSLEngine} instances obtained from default {@link SSLContext} are configured as 363 * follows: 364 * 365 * <style type="text/css"> 366 * tr.deprecated { 367 * background-color: #ccc; 368 * color: #999; 369 * font-style: italic; 370 * } 371 * </style> 372 * 373 * <h4>Protocols</h4> 374 * <table> 375 * <thead> 376 * <tr> 377 * <th>Protocol</th> 378 * <th>Supported (API Levels)</th> 379 * <th>Enabled by default (API Levels)</th> 380 * </tr> 381 * </thead> 382 * <tbody> 383 * <tr> 384 * <td>SSLv3</td> 385 * <td>1+</td> 386 * <td>1–22</td> 387 * </tr> 388 * <tr> 389 * <td>TLSv1</td> 390 * <td>1+</td> 391 * <td>1+</td> 392 * </tr> 393 * <tr> 394 * <td>TLSv1.1</td> 395 * <td>20+</td> 396 * <td>20+</td> 397 * </tr> 398 * <tr> 399 * <td>TLSv1.2</td> 400 * <td>20+</td> 401 * <td>20+</td> 402 * </tr> 403 * </tbody> 404 * </table> 405 * 406 * <h4>Cipher suites</h4> 407 * <table> 408 * <thead> 409 * <tr> 410 * <th>Cipher suite</th> 411 * <th>Supported (API Levels)</th> 412 * <th>Enabled by default (API Levels)</th> 413 * </tr> 414 * </thead> 415 * <tbody> 416 * <tr class="deprecated"> 417 * <td>SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA</td> 418 * <td>9–22</td> 419 * <td>9–19</td> 420 * </tr> 421 * <tr class="deprecated"> 422 * <td>SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA</td> 423 * <td>9–22</td> 424 * <td>9–19</td> 425 * </tr> 426 * <tr class="deprecated"> 427 * <td>SSL_DHE_DSS_WITH_DES_CBC_SHA</td> 428 * <td>9–22</td> 429 * <td>9–19</td> 430 * </tr> 431 * <tr class="deprecated"> 432 * <td>SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA</td> 433 * <td>9–22</td> 434 * <td>9–19</td> 435 * </tr> 436 * <tr class="deprecated"> 437 * <td>SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA</td> 438 * <td>9–22</td> 439 * <td>9–19</td> 440 * </tr> 441 * <tr class="deprecated"> 442 * <td>SSL_DHE_RSA_WITH_DES_CBC_SHA</td> 443 * <td>9–22</td> 444 * <td>9–19</td> 445 * </tr> 446 * <tr class="deprecated"> 447 * <td>SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA</td> 448 * <td>9–22</td> 449 * <td></td> 450 * </tr> 451 * <tr class="deprecated"> 452 * <td>SSL_DH_anon_EXPORT_WITH_RC4_40_MD5</td> 453 * <td>9–22</td> 454 * <td></td> 455 * </tr> 456 * <tr class="deprecated"> 457 * <td>SSL_DH_anon_WITH_3DES_EDE_CBC_SHA</td> 458 * <td>9–22</td> 459 * <td></td> 460 * </tr> 461 * <tr class="deprecated"> 462 * <td>SSL_DH_anon_WITH_DES_CBC_SHA</td> 463 * <td>9–22</td> 464 * <td></td> 465 * </tr> 466 * <tr class="deprecated"> 467 * <td>SSL_DH_anon_WITH_RC4_128_MD5</td> 468 * <td>9–22</td> 469 * <td></td> 470 * </tr> 471 * <tr class="deprecated"> 472 * <td>SSL_RSA_EXPORT_WITH_DES40_CBC_SHA</td> 473 * <td>9–22</td> 474 * <td>9–19</td> 475 * </tr> 476 * <tr class="deprecated"> 477 * <td>SSL_RSA_EXPORT_WITH_RC4_40_MD5</td> 478 * <td>9–22</td> 479 * <td>9–19</td> 480 * </tr> 481 * <tr> 482 * <td>SSL_RSA_WITH_3DES_EDE_CBC_SHA</td> 483 * <td>9+</td> 484 * <td>9–19</td> 485 * </tr> 486 * <tr class="deprecated"> 487 * <td>SSL_RSA_WITH_DES_CBC_SHA</td> 488 * <td>9–22</td> 489 * <td>9–19</td> 490 * </tr> 491 * <tr class="deprecated"> 492 * <td>SSL_RSA_WITH_NULL_MD5</td> 493 * <td>9–22</td> 494 * <td></td> 495 * </tr> 496 * <tr class="deprecated"> 497 * <td>SSL_RSA_WITH_NULL_SHA</td> 498 * <td>9–22</td> 499 * <td></td> 500 * </tr> 501 * <tr> 502 * <td>SSL_RSA_WITH_RC4_128_MD5</td> 503 * <td>9+</td> 504 * <td>9–19</td> 505 * </tr> 506 * <tr> 507 * <td>SSL_RSA_WITH_RC4_128_SHA</td> 508 * <td>9+</td> 509 * <td>9–23</td> 510 * </tr> 511 * <tr class="deprecated"> 512 * <td>TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA</td> 513 * <td>1–8</td> 514 * <td>1–8</td> 515 * </tr> 516 * <tr class="deprecated"> 517 * <td>TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA</td> 518 * <td>1–8</td> 519 * <td>1–8</td> 520 * </tr> 521 * <tr class="deprecated"> 522 * <td>TLS_DHE_DSS_WITH_AES_128_CBC_SHA</td> 523 * <td>9–22</td> 524 * <td>9–22</td> 525 * </tr> 526 * <tr class="deprecated"> 527 * <td>TLS_DHE_DSS_WITH_AES_128_CBC_SHA256</td> 528 * <td>20–22</td> 529 * <td></td> 530 * </tr> 531 * <tr class="deprecated"> 532 * <td>TLS_DHE_DSS_WITH_AES_128_GCM_SHA256</td> 533 * <td>20–22</td> 534 * <td></td> 535 * </tr> 536 * <tr class="deprecated"> 537 * <td>TLS_DHE_DSS_WITH_AES_256_CBC_SHA</td> 538 * <td>9–22</td> 539 * <td>20–22</td> 540 * </tr> 541 * <tr class="deprecated"> 542 * <td>TLS_DHE_DSS_WITH_AES_256_CBC_SHA256</td> 543 * <td>20–22</td> 544 * <td></td> 545 * </tr> 546 * <tr class="deprecated"> 547 * <td>TLS_DHE_DSS_WITH_AES_256_GCM_SHA384</td> 548 * <td>20–22</td> 549 * <td></td> 550 * </tr> 551 * <tr class="deprecated"> 552 * <td>TLS_DHE_DSS_WITH_DES_CBC_SHA</td> 553 * <td>1–8</td> 554 * <td>1–8</td> 555 * </tr> 556 * <tr class="deprecated"> 557 * <td>TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA</td> 558 * <td>1–8</td> 559 * <td>1–8</td> 560 * </tr> 561 * <tr class="deprecated"> 562 * <td>TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA</td> 563 * <td>1–8</td> 564 * <td>1–8</td> 565 * </tr> 566 * <tr> 567 * <td>TLS_DHE_RSA_WITH_AES_128_CBC_SHA</td> 568 * <td>9+</td> 569 * <td>9+</td> 570 * </tr> 571 * <tr> 572 * <td>TLS_DHE_RSA_WITH_AES_128_CBC_SHA256</td> 573 * <td>20+</td> 574 * <td></td> 575 * </tr> 576 * <tr> 577 * <td>TLS_DHE_RSA_WITH_AES_128_GCM_SHA256</td> 578 * <td>20+</td> 579 * <td>20+</td> 580 * </tr> 581 * <tr> 582 * <td>TLS_DHE_RSA_WITH_AES_256_CBC_SHA</td> 583 * <td>9+</td> 584 * <td>20+</td> 585 * </tr> 586 * <tr> 587 * <td>TLS_DHE_RSA_WITH_AES_256_CBC_SHA256</td> 588 * <td>20+</td> 589 * <td></td> 590 * </tr> 591 * <tr> 592 * <td>TLS_DHE_RSA_WITH_AES_256_GCM_SHA384</td> 593 * <td>20+</td> 594 * <td>20+</td> 595 * </tr> 596 * <tr class="deprecated"> 597 * <td>TLS_DHE_RSA_WITH_DES_CBC_SHA</td> 598 * <td>1–8</td> 599 * <td>1–8</td> 600 * </tr> 601 * <tr class="deprecated"> 602 * <td>TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA</td> 603 * <td>1–8</td> 604 * <td></td> 605 * </tr> 606 * <tr class="deprecated"> 607 * <td>TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA</td> 608 * <td>1–8</td> 609 * <td></td> 610 * </tr> 611 * <tr class="deprecated"> 612 * <td>TLS_DH_DSS_WITH_DES_CBC_SHA</td> 613 * <td>1–8</td> 614 * <td></td> 615 * </tr> 616 * <tr class="deprecated"> 617 * <td>TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA</td> 618 * <td>1–8</td> 619 * <td></td> 620 * </tr> 621 * <tr class="deprecated"> 622 * <td>TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA</td> 623 * <td>1–8</td> 624 * <td></td> 625 * </tr> 626 * <tr class="deprecated"> 627 * <td>TLS_DH_RSA_WITH_DES_CBC_SHA</td> 628 * <td>1–8</td> 629 * <td></td> 630 * </tr> 631 * <tr class="deprecated"> 632 * <td>TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA</td> 633 * <td>1–8</td> 634 * <td></td> 635 * </tr> 636 * <tr class="deprecated"> 637 * <td>TLS_DH_anon_WITH_3DES_EDE_CBC_SHA</td> 638 * <td>1–8</td> 639 * <td></td> 640 * </tr> 641 * <tr class="deprecated"> 642 * <td>TLS_DH_anon_WITH_AES_128_CBC_SHA</td> 643 * <td>9–22</td> 644 * <td></td> 645 * </tr> 646 * <tr class="deprecated"> 647 * <td>TLS_DH_anon_WITH_AES_128_CBC_SHA256</td> 648 * <td>20–22</td> 649 * <td></td> 650 * </tr> 651 * <tr class="deprecated"> 652 * <td>TLS_DH_anon_WITH_AES_128_GCM_SHA256</td> 653 * <td>20–22</td> 654 * <td></td> 655 * </tr> 656 * <tr class="deprecated"> 657 * <td>TLS_DH_anon_WITH_AES_256_CBC_SHA</td> 658 * <td>9–22</td> 659 * <td></td> 660 * </tr> 661 * <tr class="deprecated"> 662 * <td>TLS_DH_anon_WITH_AES_256_CBC_SHA256</td> 663 * <td>20–22</td> 664 * <td></td> 665 * </tr> 666 * <tr class="deprecated"> 667 * <td>TLS_DH_anon_WITH_AES_256_GCM_SHA384</td> 668 * <td>20–22</td> 669 * <td></td> 670 * </tr> 671 * <tr class="deprecated"> 672 * <td>TLS_DH_anon_WITH_DES_CBC_SHA</td> 673 * <td>1–8</td> 674 * <td></td> 675 * </tr> 676 * <tr class="deprecated"> 677 * <td>TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA</td> 678 * <td>20–22</td> 679 * <td></td> 680 * </tr> 681 * <tr> 682 * <td>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</td> 683 * <td>20+</td> 684 * <td>20+</td> 685 * </tr> 686 * <tr> 687 * <td>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256</td> 688 * <td>20+</td> 689 * <td></td> 690 * </tr> 691 * <tr> 692 * <td>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</td> 693 * <td>20+</td> 694 * <td>20+</td> 695 * </tr> 696 * <tr> 697 * <td>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</td> 698 * <td>20+</td> 699 * <td>20+</td> 700 * </tr> 701 * <tr> 702 * <td>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384</td> 703 * <td>20+</td> 704 * <td></td> 705 * </tr> 706 * <tr> 707 * <td>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</td> 708 * <td>20+</td> 709 * <td>20+</td> 710 * </tr> 711 * <tr> 712 * <td>TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256</td> 713 * <td>24+</td> 714 * <td>24+</td> 715 * </tr> 716 * <tr class="deprecated"> 717 * <td>TLS_ECDHE_ECDSA_WITH_NULL_SHA</td> 718 * <td>20–22</td> 719 * <td></td> 720 * </tr> 721 * <tr> 722 * <td>TLS_ECDHE_ECDSA_WITH_RC4_128_SHA</td> 723 * <td>20+</td> 724 * <td>20–23</td> 725 * </tr> 726 * <tr> 727 * <td>TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA</td> 728 * <td>21+</td> 729 * <td>21+</td> 730 * </tr> 731 * <tr> 732 * <td>TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA</td> 733 * <td>21+</td> 734 * <td>21+</td> 735 * </tr> 736 * <tr> 737 * <td>TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256</td> 738 * <td>24+</td> 739 * <td>24+</td> 740 * </tr> 741 * <tr class="deprecated"> 742 * <td>TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA</td> 743 * <td>20–22</td> 744 * <td></td> 745 * </tr> 746 * <tr> 747 * <td>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</td> 748 * <td>20+</td> 749 * <td>20+</td> 750 * </tr> 751 * <tr> 752 * <td>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</td> 753 * <td>20+</td> 754 * <td></td> 755 * </tr> 756 * <tr> 757 * <td>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</td> 758 * <td>20+</td> 759 * <td>20+</td> 760 * </tr> 761 * <tr> 762 * <td>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</td> 763 * <td>20+</td> 764 * <td>20+</td> 765 * </tr> 766 * <tr> 767 * <td>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384</td> 768 * <td>20+</td> 769 * <td></td> 770 * </tr> 771 * <tr> 772 * <td>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</td> 773 * <td>20+</td> 774 * <td>20+</td> 775 * </tr> 776 * <tr> 777 * <td>TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256</td> 778 * <td>24+</td> 779 * <td>24+</td> 780 * </tr> 781 * <tr class="deprecated"> 782 * <td>TLS_ECDHE_RSA_WITH_NULL_SHA</td> 783 * <td>20–22</td> 784 * <td></td> 785 * </tr> 786 * <tr> 787 * <td>TLS_ECDHE_RSA_WITH_RC4_128_SHA</td> 788 * <td>20+</td> 789 * <td>20–23</td> 790 * </tr> 791 * <tr class="deprecated"> 792 * <td>TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA</td> 793 * <td>20–22</td> 794 * <td></td> 795 * </tr> 796 * <tr class="deprecated"> 797 * <td>TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA</td> 798 * <td>20–22</td> 799 * <td></td> 800 * </tr> 801 * <tr class="deprecated"> 802 * <td>TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256</td> 803 * <td>20–22</td> 804 * <td></td> 805 * </tr> 806 * <tr class="deprecated"> 807 * <td>TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256</td> 808 * <td>20–22</td> 809 * <td></td> 810 * </tr> 811 * <tr class="deprecated"> 812 * <td>TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA</td> 813 * <td>20–22</td> 814 * <td></td> 815 * </tr> 816 * <tr class="deprecated"> 817 * <td>TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384</td> 818 * <td>20–22</td> 819 * <td></td> 820 * </tr> 821 * <tr class="deprecated"> 822 * <td>TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384</td> 823 * <td>20–22</td> 824 * <td></td> 825 * </tr> 826 * <tr class="deprecated"> 827 * <td>TLS_ECDH_ECDSA_WITH_NULL_SHA</td> 828 * <td>20–22</td> 829 * <td></td> 830 * </tr> 831 * <tr class="deprecated"> 832 * <td>TLS_ECDH_ECDSA_WITH_RC4_128_SHA</td> 833 * <td>20–22</td> 834 * <td></td> 835 * </tr> 836 * <tr class="deprecated"> 837 * <td>TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA</td> 838 * <td>20–22</td> 839 * <td></td> 840 * </tr> 841 * <tr class="deprecated"> 842 * <td>TLS_ECDH_RSA_WITH_AES_128_CBC_SHA</td> 843 * <td>20–22</td> 844 * <td></td> 845 * </tr> 846 * <tr class="deprecated"> 847 * <td>TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256</td> 848 * <td>20–22</td> 849 * <td></td> 850 * </tr> 851 * <tr class="deprecated"> 852 * <td>TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256</td> 853 * <td>20–22</td> 854 * <td></td> 855 * </tr> 856 * <tr class="deprecated"> 857 * <td>TLS_ECDH_RSA_WITH_AES_256_CBC_SHA</td> 858 * <td>20–22</td> 859 * <td></td> 860 * </tr> 861 * <tr class="deprecated"> 862 * <td>TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384</td> 863 * <td>20–22</td> 864 * <td></td> 865 * </tr> 866 * <tr class="deprecated"> 867 * <td>TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384</td> 868 * <td>20–22</td> 869 * <td></td> 870 * </tr> 871 * <tr class="deprecated"> 872 * <td>TLS_ECDH_RSA_WITH_NULL_SHA</td> 873 * <td>20–22</td> 874 * <td></td> 875 * </tr> 876 * <tr class="deprecated"> 877 * <td>TLS_ECDH_RSA_WITH_RC4_128_SHA</td> 878 * <td>20–22</td> 879 * <td></td> 880 * </tr> 881 * <tr class="deprecated"> 882 * <td>TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA</td> 883 * <td>20–22</td> 884 * <td></td> 885 * </tr> 886 * <tr class="deprecated"> 887 * <td>TLS_ECDH_anon_WITH_AES_128_CBC_SHA</td> 888 * <td>20–22</td> 889 * <td></td> 890 * </tr> 891 * <tr class="deprecated"> 892 * <td>TLS_ECDH_anon_WITH_AES_256_CBC_SHA</td> 893 * <td>20–22</td> 894 * <td></td> 895 * </tr> 896 * <tr class="deprecated"> 897 * <td>TLS_ECDH_anon_WITH_NULL_SHA</td> 898 * <td>20–22</td> 899 * <td></td> 900 * </tr> 901 * <tr class="deprecated"> 902 * <td>TLS_ECDH_anon_WITH_RC4_128_SHA</td> 903 * <td>20–22</td> 904 * <td></td> 905 * </tr> 906 * <tr> 907 * <td>TLS_EMPTY_RENEGOTIATION_INFO_SCSV</td> 908 * <td>20+</td> 909 * <td>20+</td> 910 * </tr> 911 * <tr> 912 * <td>TLS_FALLBACK_SCSV</td> 913 * <td>21+</td> 914 * <td></td> 915 * </tr> 916 * <tr class="deprecated"> 917 * <td>TLS_NULL_WITH_NULL_NULL</td> 918 * <td>1–8</td> 919 * <td></td> 920 * </tr> 921 * <tr class="deprecated"> 922 * <td>TLS_PSK_WITH_3DES_EDE_CBC_SHA</td> 923 * <td>21–22</td> 924 * <td></td> 925 * </tr> 926 * <tr> 927 * <td>TLS_PSK_WITH_AES_128_CBC_SHA</td> 928 * <td>21+</td> 929 * <td>21+</td> 930 * </tr> 931 * <tr> 932 * <td>TLS_PSK_WITH_AES_256_CBC_SHA</td> 933 * <td>21+</td> 934 * <td>21+</td> 935 * </tr> 936 * <tr> 937 * <td>TLS_PSK_WITH_RC4_128_SHA</td> 938 * <td>21+</td> 939 * <td></td> 940 * </tr> 941 * <tr class="deprecated"> 942 * <td>TLS_RSA_EXPORT_WITH_DES40_CBC_SHA</td> 943 * <td>1–8</td> 944 * <td>1–8</td> 945 * </tr> 946 * <tr class="deprecated"> 947 * <td>TLS_RSA_WITH_3DES_EDE_CBC_SHA</td> 948 * <td>1–8</td> 949 * <td>1–8</td> 950 * </tr> 951 * <tr> 952 * <td>TLS_RSA_WITH_AES_128_CBC_SHA</td> 953 * <td>9+</td> 954 * <td>9+</td> 955 * </tr> 956 * <tr> 957 * <td>TLS_RSA_WITH_AES_128_CBC_SHA256</td> 958 * <td>20+</td> 959 * <td></td> 960 * </tr> 961 * <tr> 962 * <td>TLS_RSA_WITH_AES_128_GCM_SHA256</td> 963 * <td>20+</td> 964 * <td>20+</td> 965 * </tr> 966 * <tr> 967 * <td>TLS_RSA_WITH_AES_256_CBC_SHA</td> 968 * <td>9+</td> 969 * <td>20+</td> 970 * </tr> 971 * <tr> 972 * <td>TLS_RSA_WITH_AES_256_CBC_SHA256</td> 973 * <td>20+</td> 974 * <td></td> 975 * </tr> 976 * <tr> 977 * <td>TLS_RSA_WITH_AES_256_GCM_SHA384</td> 978 * <td>20+</td> 979 * <td>20+</td> 980 * </tr> 981 * <tr class="deprecated"> 982 * <td>TLS_RSA_WITH_DES_CBC_SHA</td> 983 * <td>1–8</td> 984 * <td>1–8</td> 985 * </tr> 986 * <tr class="deprecated"> 987 * <td>TLS_RSA_WITH_NULL_MD5</td> 988 * <td>1–8</td> 989 * <td></td> 990 * </tr> 991 * <tr class="deprecated"> 992 * <td>TLS_RSA_WITH_NULL_SHA</td> 993 * <td>1–8</td> 994 * <td></td> 995 * </tr> 996 * <tr class="deprecated"> 997 * <td>TLS_RSA_WITH_NULL_SHA256</td> 998 * <td>20–22</td> 999 * <td></td> 1000 * </tr> 1001 * </tbody> 1002 * </table> 1003 * 1004 * <p><em>NOTE</em>: PSK cipher suites are enabled by default only if the {@code SSLContext} through 1005 * which the engine was created has been initialized with a {@code PSKKeyManager}. 1006 * 1007 * @see SSLContext 1008 * @see SSLSocket 1009 * @see SSLServerSocket 1010 * @see SSLSession 1011 * @see java.net.Socket 1012 * 1013 * @since 1.5 1014 * @author Brad R. Wetmore 1015 */ 1016 1017public abstract class SSLEngine { 1018 1019 private String peerHost = null; 1020 private int peerPort = -1; 1021 1022 /** 1023 * Constructor for an <code>SSLEngine</code> providing no hints 1024 * for an internal session reuse strategy. 1025 * 1026 * @see SSLContext#createSSLEngine() 1027 * @see SSLSessionContext 1028 */ 1029 protected SSLEngine() { 1030 } 1031 1032 /** 1033 * Constructor for an <code>SSLEngine</code>. 1034 * <P> 1035 * <code>SSLEngine</code> implementations may use the 1036 * <code>peerHost</code> and <code>peerPort</code> parameters as hints 1037 * for their internal session reuse strategy. 1038 * <P> 1039 * Some cipher suites (such as Kerberos) require remote hostname 1040 * information. Implementations of this class should use this 1041 * constructor to use Kerberos. 1042 * <P> 1043 * The parameters are not authenticated by the 1044 * <code>SSLEngine</code>. 1045 * 1046 * @param peerHost the name of the peer host 1047 * @param peerPort the port number of the peer 1048 * @see SSLContext#createSSLEngine(String, int) 1049 * @see SSLSessionContext 1050 */ 1051 protected SSLEngine(String peerHost, int peerPort) { 1052 this.peerHost = peerHost; 1053 this.peerPort = peerPort; 1054 } 1055 1056 /** 1057 * Returns the host name of the peer. 1058 * <P> 1059 * Note that the value is not authenticated, and should not be 1060 * relied upon. 1061 * 1062 * @return the host name of the peer, or null if nothing is 1063 * available. 1064 */ 1065 public String getPeerHost() { 1066 return peerHost; 1067 } 1068 1069 /** 1070 * Returns the port number of the peer. 1071 * <P> 1072 * Note that the value is not authenticated, and should not be 1073 * relied upon. 1074 * 1075 * @return the port number of the peer, or -1 if nothing is 1076 * available. 1077 */ 1078 public int getPeerPort() { 1079 return peerPort; 1080 } 1081 1082 /** 1083 * Attempts to encode a buffer of plaintext application data into 1084 * SSL/TLS network data. 1085 * <P> 1086 * An invocation of this method behaves in exactly the same manner 1087 * as the invocation: 1088 * <blockquote><pre> 1089 * {@link #wrap(ByteBuffer [], int, int, ByteBuffer) 1090 * engine.wrap(new ByteBuffer [] { src }, 0, 1, dst);} 1091 * </pre</blockquote> 1092 * 1093 * @param src 1094 * a <code>ByteBuffer</code> containing outbound application data 1095 * @param dst 1096 * a <code>ByteBuffer</code> to hold outbound network data 1097 * @return an <code>SSLEngineResult</code> describing the result 1098 * of this operation. 1099 * @throws SSLException 1100 * A problem was encountered while processing the 1101 * data that caused the <code>SSLEngine</code> to abort. 1102 * See the class description for more information on 1103 * engine closure. 1104 * @throws ReadOnlyBufferException 1105 * if the <code>dst</code> buffer is read-only. 1106 * @throws IllegalArgumentException 1107 * if either <code>src</code> or <code>dst</code> 1108 * is null. 1109 * @throws IllegalStateException if the client/server mode 1110 * has not yet been set. 1111 * @see #wrap(ByteBuffer [], int, int, ByteBuffer) 1112 */ 1113 public SSLEngineResult wrap(ByteBuffer src, 1114 ByteBuffer dst) throws SSLException { 1115 return wrap(new ByteBuffer [] { src }, 0, 1, dst); 1116 } 1117 1118 /** 1119 * Attempts to encode plaintext bytes from a sequence of data 1120 * buffers into SSL/TLS network data. 1121 * <P> 1122 * An invocation of this method behaves in exactly the same manner 1123 * as the invocation: 1124 * <blockquote><pre> 1125 * {@link #wrap(ByteBuffer [], int, int, ByteBuffer) 1126 * engine.wrap(srcs, 0, srcs.length, dst);} 1127 * </pre</blockquote> 1128 * 1129 * @param srcs 1130 * an array of <code>ByteBuffers</code> containing the 1131 * outbound application data 1132 * @param dst 1133 * a <code>ByteBuffer</code> to hold outbound network data 1134 * @return an <code>SSLEngineResult</code> describing the result 1135 * of this operation. 1136 * @throws SSLException 1137 * A problem was encountered while processing the 1138 * data that caused the <code>SSLEngine</code> to abort. 1139 * See the class description for more information on 1140 * engine closure. 1141 * @throws ReadOnlyBufferException 1142 * if the <code>dst</code> buffer is read-only. 1143 * @throws IllegalArgumentException 1144 * if either <code>srcs</code> or <code>dst</code> 1145 * is null, or if any element in <code>srcs</code> is null. 1146 * @throws IllegalStateException if the client/server mode 1147 * has not yet been set. 1148 * @see #wrap(ByteBuffer [], int, int, ByteBuffer) 1149 */ 1150 public SSLEngineResult wrap(ByteBuffer [] srcs, 1151 ByteBuffer dst) throws SSLException { 1152 if (srcs == null) { 1153 throw new IllegalArgumentException("src == null"); 1154 } 1155 return wrap(srcs, 0, srcs.length, dst); 1156 } 1157 1158 1159 /** 1160 * Attempts to encode plaintext bytes from a subsequence of data 1161 * buffers into SSL/TLS network data. This <i>"gathering"</i> 1162 * operation encodes, in a single invocation, a sequence of bytes 1163 * from one or more of a given sequence of buffers. Gathering 1164 * wraps are often useful when implementing network protocols or 1165 * file formats that, for example, group data into segments 1166 * consisting of one or more fixed-length headers followed by a 1167 * variable-length body. See 1168 * {@link java.nio.channels.GatheringByteChannel} for more 1169 * information on gathering, and {@link 1170 * java.nio.channels.GatheringByteChannel#write(ByteBuffer[], 1171 * int, int)} for more information on the subsequence 1172 * behavior. 1173 * <P> 1174 * Depending on the state of the SSLEngine, this method may produce 1175 * network data without consuming any application data (for example, 1176 * it may generate handshake data.) 1177 * <P> 1178 * The application is responsible for reliably transporting the 1179 * network data to the peer, and for ensuring that data created by 1180 * multiple calls to wrap() is transported in the same order in which 1181 * it was generated. The application must properly synchronize 1182 * multiple calls to this method. 1183 * <P> 1184 * If this <code>SSLEngine</code> has not yet started its initial 1185 * handshake, this method will automatically start the handshake. 1186 * <P> 1187 * This method will attempt to produce one SSL/TLS packet, and will 1188 * consume as much source data as possible, but will never consume 1189 * more than the sum of the bytes remaining in each buffer. Each 1190 * <code>ByteBuffer</code>'s position is updated to reflect the 1191 * amount of data consumed or produced. The limits remain the 1192 * same. 1193 * <P> 1194 * The underlying memory used by the <code>srcs</code> and 1195 * <code>dst ByteBuffer</code>s must not be the same. 1196 * <P> 1197 * See the class description for more information on engine closure. 1198 * 1199 * @param srcs 1200 * an array of <code>ByteBuffers</code> containing the 1201 * outbound application data 1202 * @param offset 1203 * The offset within the buffer array of the first buffer from 1204 * which bytes are to be retrieved; it must be non-negative 1205 * and no larger than <code>srcs.length</code> 1206 * @param length 1207 * The maximum number of buffers to be accessed; it must be 1208 * non-negative and no larger than 1209 * <code>srcs.length</code> - <code>offset</code> 1210 * @param dst 1211 * a <code>ByteBuffer</code> to hold outbound network data 1212 * @return an <code>SSLEngineResult</code> describing the result 1213 * of this operation. 1214 * @throws SSLException 1215 * A problem was encountered while processing the 1216 * data that caused the <code>SSLEngine</code> to abort. 1217 * See the class description for more information on 1218 * engine closure. 1219 * @throws IndexOutOfBoundsException 1220 * if the preconditions on the <code>offset</code> and 1221 * <code>length</code> parameters do not hold. 1222 * @throws ReadOnlyBufferException 1223 * if the <code>dst</code> buffer is read-only. 1224 * @throws IllegalArgumentException 1225 * if either <code>srcs</code> or <code>dst</code> 1226 * is null, or if any element in the <code>srcs</code> 1227 * subsequence specified is null. 1228 * @throws IllegalStateException if the client/server mode 1229 * has not yet been set. 1230 * @see java.nio.channels.GatheringByteChannel 1231 * @see java.nio.channels.GatheringByteChannel#write( 1232 * ByteBuffer[], int, int) 1233 */ 1234 public abstract SSLEngineResult wrap(ByteBuffer [] srcs, int offset, 1235 int length, ByteBuffer dst) throws SSLException; 1236 1237 /** 1238 * Attempts to decode SSL/TLS network data into a plaintext 1239 * application data buffer. 1240 * <P> 1241 * An invocation of this method behaves in exactly the same manner 1242 * as the invocation: 1243 * <blockquote><pre> 1244 * {@link #unwrap(ByteBuffer, ByteBuffer [], int, int) 1245 * engine.unwrap(src, new ByteBuffer [] { dst }, 0, 1);} 1246 * </pre</blockquote> 1247 * 1248 * @param src 1249 * a <code>ByteBuffer</code> containing inbound network data. 1250 * @param dst 1251 * a <code>ByteBuffer</code> to hold inbound application data. 1252 * @return an <code>SSLEngineResult</code> describing the result 1253 * of this operation. 1254 * @throws SSLException 1255 * A problem was encountered while processing the 1256 * data that caused the <code>SSLEngine</code> to abort. 1257 * See the class description for more information on 1258 * engine closure. 1259 * @throws ReadOnlyBufferException 1260 * if the <code>dst</code> buffer is read-only. 1261 * @throws IllegalArgumentException 1262 * if either <code>src</code> or <code>dst</code> 1263 * is null. 1264 * @throws IllegalStateException if the client/server mode 1265 * has not yet been set. 1266 * @see #unwrap(ByteBuffer, ByteBuffer [], int, int) 1267 */ 1268 public SSLEngineResult unwrap(ByteBuffer src, 1269 ByteBuffer dst) throws SSLException { 1270 return unwrap(src, new ByteBuffer [] { dst }, 0, 1); 1271 } 1272 1273 /** 1274 * Attempts to decode SSL/TLS network data into a sequence of plaintext 1275 * application data buffers. 1276 * <P> 1277 * An invocation of this method behaves in exactly the same manner 1278 * as the invocation: 1279 * <blockquote><pre> 1280 * {@link #unwrap(ByteBuffer, ByteBuffer [], int, int) 1281 * engine.unwrap(src, dsts, 0, dsts.length);} 1282 * </pre</blockquote> 1283 * 1284 * @param src 1285 * a <code>ByteBuffer</code> containing inbound network data. 1286 * @param dsts 1287 * an array of <code>ByteBuffer</code>s to hold inbound 1288 * application data. 1289 * @return an <code>SSLEngineResult</code> describing the result 1290 * of this operation. 1291 * @throws SSLException 1292 * A problem was encountered while processing the 1293 * data that caused the <code>SSLEngine</code> to abort. 1294 * See the class description for more information on 1295 * engine closure. 1296 * @throws ReadOnlyBufferException 1297 * if any of the <code>dst</code> buffers are read-only. 1298 * @throws IllegalArgumentException 1299 * if either <code>src</code> or <code>dsts</code> 1300 * is null, or if any element in <code>dsts</code> is null. 1301 * @throws IllegalStateException if the client/server mode 1302 * has not yet been set. 1303 * @see #unwrap(ByteBuffer, ByteBuffer [], int, int) 1304 */ 1305 public SSLEngineResult unwrap(ByteBuffer src, 1306 ByteBuffer [] dsts) throws SSLException { 1307 if (dsts == null) { 1308 throw new IllegalArgumentException("dsts == null"); 1309 } 1310 return unwrap(src, dsts, 0, dsts.length); 1311 } 1312 1313 /** 1314 * Attempts to decode SSL/TLS network data into a subsequence of 1315 * plaintext application data buffers. This <i>"scattering"</i> 1316 * operation decodes, in a single invocation, a sequence of bytes 1317 * into one or more of a given sequence of buffers. Scattering 1318 * unwraps are often useful when implementing network protocols or 1319 * file formats that, for example, group data into segments 1320 * consisting of one or more fixed-length headers followed by a 1321 * variable-length body. See 1322 * {@link java.nio.channels.ScatteringByteChannel} for more 1323 * information on scattering, and {@link 1324 * java.nio.channels.ScatteringByteChannel#read(ByteBuffer[], 1325 * int, int)} for more information on the subsequence 1326 * behavior. 1327 * <P> 1328 * Depending on the state of the SSLEngine, this method may consume 1329 * network data without producing any application data (for example, 1330 * it may consume handshake data.) 1331 * <P> 1332 * The application is responsible for reliably obtaining the network 1333 * data from the peer, and for invoking unwrap() on the data in the 1334 * order it was received. The application must properly synchronize 1335 * multiple calls to this method. 1336 * <P> 1337 * If this <code>SSLEngine</code> has not yet started its initial 1338 * handshake, this method will automatically start the handshake. 1339 * <P> 1340 * This method will attempt to consume one complete SSL/TLS network 1341 * packet, but will never consume more than the sum of the bytes 1342 * remaining in the buffers. Each <code>ByteBuffer</code>'s 1343 * position is updated to reflect the amount of data consumed or 1344 * produced. The limits remain the same. 1345 * <P> 1346 * The underlying memory used by the <code>src</code> and 1347 * <code>dsts ByteBuffer</code>s must not be the same. 1348 * <P> 1349 * The inbound network buffer may be modified as a result of this 1350 * call: therefore if the network data packet is required for some 1351 * secondary purpose, the data should be duplicated before calling this 1352 * method. Note: the network data will not be useful to a second 1353 * SSLEngine, as each SSLEngine contains unique random state which 1354 * influences the SSL/TLS messages. 1355 * <P> 1356 * See the class description for more information on engine closure. 1357 * 1358 * @param src 1359 * a <code>ByteBuffer</code> containing inbound network data. 1360 * @param dsts 1361 * an array of <code>ByteBuffer</code>s to hold inbound 1362 * application data. 1363 * @param offset 1364 * The offset within the buffer array of the first buffer from 1365 * which bytes are to be transferred; it must be non-negative 1366 * and no larger than <code>dsts.length</code>. 1367 * @param length 1368 * The maximum number of buffers to be accessed; it must be 1369 * non-negative and no larger than 1370 * <code>dsts.length</code> - <code>offset</code>. 1371 * @return an <code>SSLEngineResult</code> describing the result 1372 * of this operation. 1373 * @throws SSLException 1374 * A problem was encountered while processing the 1375 * data that caused the <code>SSLEngine</code> to abort. 1376 * See the class description for more information on 1377 * engine closure. 1378 * @throws IndexOutOfBoundsException 1379 * If the preconditions on the <code>offset</code> and 1380 * <code>length</code> parameters do not hold. 1381 * @throws ReadOnlyBufferException 1382 * if any of the <code>dst</code> buffers are read-only. 1383 * @throws IllegalArgumentException 1384 * if either <code>src</code> or <code>dsts</code> 1385 * is null, or if any element in the <code>dsts</code> 1386 * subsequence specified is null. 1387 * @throws IllegalStateException if the client/server mode 1388 * has not yet been set. 1389 * @see java.nio.channels.ScatteringByteChannel 1390 * @see java.nio.channels.ScatteringByteChannel#read( 1391 * ByteBuffer[], int, int) 1392 */ 1393 public abstract SSLEngineResult unwrap(ByteBuffer src, 1394 ByteBuffer [] dsts, int offset, int length) throws SSLException; 1395 1396 1397 /** 1398 * Returns a delegated <code>Runnable</code> task for 1399 * this <code>SSLEngine</code>. 1400 * <P> 1401 * <code>SSLEngine</code> operations may require the results of 1402 * operations that block, or may take an extended period of time to 1403 * complete. This method is used to obtain an outstanding {@link 1404 * java.lang.Runnable} operation (task). Each task must be assigned 1405 * a thread (possibly the current) to perform the {@link 1406 * java.lang.Runnable#run() run} operation. Once the 1407 * <code>run</code> method returns, the <code>Runnable</code> object 1408 * is no longer needed and may be discarded. 1409 * <P> 1410 * Delegated tasks run in the <code>AccessControlContext</code> 1411 * in place when this object was created. 1412 * <P> 1413 * A call to this method will return each outstanding task 1414 * exactly once. 1415 * <P> 1416 * Multiple delegated tasks can be run in parallel. 1417 * 1418 * @return a delegated <code>Runnable</code> task, or null 1419 * if none are available. 1420 */ 1421 public abstract Runnable getDelegatedTask(); 1422 1423 1424 /** 1425 * Signals that no more inbound network data will be sent 1426 * to this <code>SSLEngine</code>. 1427 * <P> 1428 * If the application initiated the closing process by calling 1429 * {@link #closeOutbound()}, under some circumstances it is not 1430 * required that the initiator wait for the peer's corresponding 1431 * close message. (See section 7.2.1 of the TLS specification (<A 1432 * HREF="http://www.ietf.org/rfc/rfc2246.txt">RFC 2246</A>) for more 1433 * information on waiting for closure alerts.) In such cases, this 1434 * method need not be called. 1435 * <P> 1436 * But if the application did not initiate the closure process, or 1437 * if the circumstances above do not apply, this method should be 1438 * called whenever the end of the SSL/TLS data stream is reached. 1439 * This ensures closure of the inbound side, and checks that the 1440 * peer followed the SSL/TLS close procedure properly, thus 1441 * detecting possible truncation attacks. 1442 * <P> 1443 * This method is idempotent: if the inbound side has already 1444 * been closed, this method does not do anything. 1445 * <P> 1446 * {@link #wrap(ByteBuffer, ByteBuffer) wrap()} should be 1447 * called to flush any remaining handshake data. 1448 * 1449 * @throws SSLException 1450 * if this engine has not received the proper SSL/TLS close 1451 * notification message from the peer. 1452 * 1453 * @see #isInboundDone() 1454 * @see #isOutboundDone() 1455 */ 1456 public abstract void closeInbound() throws SSLException; 1457 1458 1459 /** 1460 * Returns whether {@link #unwrap(ByteBuffer, ByteBuffer)} will 1461 * accept any more inbound data messages. 1462 * 1463 * @return true if the <code>SSLEngine</code> will not 1464 * consume anymore network data (and by implication, 1465 * will not produce any more application data.) 1466 * @see #closeInbound() 1467 */ 1468 public abstract boolean isInboundDone(); 1469 1470 1471 /** 1472 * Signals that no more outbound application data will be sent 1473 * on this <code>SSLEngine</code>. 1474 * <P> 1475 * This method is idempotent: if the outbound side has already 1476 * been closed, this method does not do anything. 1477 * <P> 1478 * {@link #wrap(ByteBuffer, ByteBuffer)} should be 1479 * called to flush any remaining handshake data. 1480 * 1481 * @see #isOutboundDone() 1482 */ 1483 public abstract void closeOutbound(); 1484 1485 1486 /** 1487 * Returns whether {@link #wrap(ByteBuffer, ByteBuffer)} will 1488 * produce any more outbound data messages. 1489 * <P> 1490 * Note that during the closure phase, a <code>SSLEngine</code> may 1491 * generate handshake closure data that must be sent to the peer. 1492 * <code>wrap()</code> must be called to generate this data. When 1493 * this method returns true, no more outbound data will be created. 1494 * 1495 * @return true if the <code>SSLEngine</code> will not produce 1496 * any more network data 1497 * 1498 * @see #closeOutbound() 1499 * @see #closeInbound() 1500 */ 1501 public abstract boolean isOutboundDone(); 1502 1503 1504 /** 1505 * Returns the names of the cipher suites which could be enabled for use 1506 * on this engine. Normally, only a subset of these will actually 1507 * be enabled by default, since this list may include cipher suites which 1508 * do not meet quality of service requirements for those defaults. Such 1509 * cipher suites might be useful in specialized applications. 1510 * 1511 * @return an array of cipher suite names 1512 * @see #getEnabledCipherSuites() 1513 * @see #setEnabledCipherSuites(String []) 1514 */ 1515 public abstract String [] getSupportedCipherSuites(); 1516 1517 1518 /** 1519 * Returns the names of the SSL cipher suites which are currently 1520 * enabled for use on this engine. When an SSLEngine is first 1521 * created, all enabled cipher suites support a minimum quality of 1522 * service. Thus, in some environments this value might be empty. 1523 * <P> 1524 * Even if a suite has been enabled, it might never be used. (For 1525 * example, the peer does not support it, the requisite 1526 * certificates/private keys for the suite are not available, or an 1527 * anonymous suite is enabled but authentication is required.) 1528 * 1529 * @return an array of cipher suite names 1530 * @see #getSupportedCipherSuites() 1531 * @see #setEnabledCipherSuites(String []) 1532 */ 1533 public abstract String [] getEnabledCipherSuites(); 1534 1535 1536 /** 1537 * Sets the cipher suites enabled for use on this engine. 1538 * <P> 1539 * Each cipher suite in the <code>suites</code> parameter must have 1540 * been listed by getSupportedCipherSuites(), or the method will 1541 * fail. Following a successful call to this method, only suites 1542 * listed in the <code>suites</code> parameter are enabled for use. 1543 * <P> 1544 * See {@link #getEnabledCipherSuites()} for more information 1545 * on why a specific cipher suite may never be used on a engine. 1546 * 1547 * @param suites Names of all the cipher suites to enable 1548 * @throws IllegalArgumentException when one or more of the ciphers 1549 * named by the parameter is not supported, or when the 1550 * parameter is null. 1551 * @see #getSupportedCipherSuites() 1552 * @see #getEnabledCipherSuites() 1553 */ 1554 public abstract void setEnabledCipherSuites(String suites []); 1555 1556 1557 /** 1558 * Returns the names of the protocols which could be enabled for use 1559 * with this <code>SSLEngine</code>. 1560 * 1561 * @return an array of protocols supported 1562 */ 1563 public abstract String [] getSupportedProtocols(); 1564 1565 1566 /** 1567 * Returns the names of the protocol versions which are currently 1568 * enabled for use with this <code>SSLEngine</code>. 1569 * 1570 * @return an array of protocols 1571 * @see #setEnabledProtocols(String []) 1572 */ 1573 public abstract String [] getEnabledProtocols(); 1574 1575 1576 /** 1577 * Set the protocol versions enabled for use on this engine. 1578 * <P> 1579 * The protocols must have been listed by getSupportedProtocols() 1580 * as being supported. Following a successful call to this method, 1581 * only protocols listed in the <code>protocols</code> parameter 1582 * are enabled for use. 1583 * 1584 * @param protocols Names of all the protocols to enable. 1585 * @throws IllegalArgumentException when one or more of 1586 * the protocols named by the parameter is not supported or 1587 * when the protocols parameter is null. 1588 * @see #getEnabledProtocols() 1589 */ 1590 public abstract void setEnabledProtocols(String protocols[]); 1591 1592 1593 /** 1594 * Returns the <code>SSLSession</code> in use in this 1595 * <code>SSLEngine</code>. 1596 * <P> 1597 * These can be long lived, and frequently correspond to an entire 1598 * login session for some user. The session specifies a particular 1599 * cipher suite which is being actively used by all connections in 1600 * that session, as well as the identities of the session's client 1601 * and server. 1602 * <P> 1603 * Unlike {@link SSLSocket#getSession()} 1604 * this method does not block until handshaking is complete. 1605 * <P> 1606 * Until the initial handshake has completed, this method returns 1607 * a session object which reports an invalid cipher suite of 1608 * "SSL_NULL_WITH_NULL_NULL". 1609 * 1610 * @return the <code>SSLSession</code> for this <code>SSLEngine</code> 1611 * @see SSLSession 1612 */ 1613 public abstract SSLSession getSession(); 1614 1615 1616 /** 1617 * Returns the {@code SSLSession} being constructed during a SSL/TLS 1618 * handshake. 1619 * <p> 1620 * TLS protocols may negotiate parameters that are needed when using 1621 * an instance of this class, but before the {@code SSLSession} has 1622 * been completely initialized and made available via {@code getSession}. 1623 * For example, the list of valid signature algorithms may restrict 1624 * the type of certificates that can used during TrustManager 1625 * decisions, or the maximum TLS fragment packet sizes can be 1626 * resized to better support the network environment. 1627 * <p> 1628 * This method provides early access to the {@code SSLSession} being 1629 * constructed. Depending on how far the handshake has progressed, 1630 * some data may not yet be available for use. For example, if a 1631 * remote server will be sending a Certificate chain, but that chain 1632 * has yet not been processed, the {@code getPeerCertificates} 1633 * method of {@code SSLSession} will throw a 1634 * SSLPeerUnverifiedException. Once that chain has been processed, 1635 * {@code getPeerCertificates} will return the proper value. 1636 * 1637 * @see SSLSocket 1638 * @see SSLSession 1639 * @see ExtendedSSLSession 1640 * @see X509ExtendedKeyManager 1641 * @see X509ExtendedTrustManager 1642 * 1643 * @return null if this instance is not currently handshaking, or 1644 * if the current handshake has not progressed far enough to 1645 * create a basic SSLSession. Otherwise, this method returns the 1646 * {@code SSLSession} currently being negotiated. 1647 * @throws UnsupportedOperationException if the underlying provider 1648 * does not implement the operation. 1649 * 1650 * @since 1.7 1651 */ 1652 public SSLSession getHandshakeSession() { 1653 throw new UnsupportedOperationException(); 1654 } 1655 1656 1657 /** 1658 * Initiates handshaking (initial or renegotiation) on this SSLEngine. 1659 * <P> 1660 * This method is not needed for the initial handshake, as the 1661 * <code>wrap()</code> and <code>unwrap()</code> methods will 1662 * implicitly call this method if handshaking has not already begun. 1663 * <P> 1664 * Note that the peer may also request a session renegotiation with 1665 * this <code>SSLEngine</code> by sending the appropriate 1666 * session renegotiate handshake message. 1667 * <P> 1668 * Unlike the {@link SSLSocket#startHandshake() 1669 * SSLSocket#startHandshake()} method, this method does not block 1670 * until handshaking is completed. 1671 * <P> 1672 * To force a complete SSL/TLS session renegotiation, the current 1673 * session should be invalidated prior to calling this method. 1674 * <P> 1675 * Some protocols may not support multiple handshakes on an existing 1676 * engine and may throw an <code>SSLException</code>. 1677 * 1678 * @throws SSLException 1679 * if a problem was encountered while signaling the 1680 * <code>SSLEngine</code> to begin a new handshake. 1681 * See the class description for more information on 1682 * engine closure. 1683 * @throws IllegalStateException if the client/server mode 1684 * has not yet been set. 1685 * @see SSLSession#invalidate() 1686 */ 1687 public abstract void beginHandshake() throws SSLException; 1688 1689 1690 /** 1691 * Returns the current handshake status for this <code>SSLEngine</code>. 1692 * 1693 * @return the current <code>SSLEngineResult.HandshakeStatus</code>. 1694 */ 1695 public abstract SSLEngineResult.HandshakeStatus getHandshakeStatus(); 1696 1697 1698 /** 1699 * Configures the engine to use client (or server) mode when 1700 * handshaking. 1701 * <P> 1702 * This method must be called before any handshaking occurs. 1703 * Once handshaking has begun, the mode can not be reset for the 1704 * life of this engine. 1705 * <P> 1706 * Servers normally authenticate themselves, and clients 1707 * are not required to do so. 1708 * 1709 * @param mode true if the engine should start its handshaking 1710 * in "client" mode 1711 * @throws IllegalArgumentException if a mode change is attempted 1712 * after the initial handshake has begun. 1713 * @see #getUseClientMode() 1714 */ 1715 public abstract void setUseClientMode(boolean mode); 1716 1717 1718 /** 1719 * Returns true if the engine is set to use client mode when 1720 * handshaking. 1721 * 1722 * @return true if the engine should do handshaking 1723 * in "client" mode 1724 * @see #setUseClientMode(boolean) 1725 */ 1726 public abstract boolean getUseClientMode(); 1727 1728 1729 /** 1730 * Configures the engine to <i>require</i> client authentication. This 1731 * option is only useful for engines in the server mode. 1732 * <P> 1733 * An engine's client authentication setting is one of the following: 1734 * <ul> 1735 * <li> client authentication required 1736 * <li> client authentication requested 1737 * <li> no client authentication desired 1738 * </ul> 1739 * <P> 1740 * Unlike {@link #setWantClientAuth(boolean)}, if this option is set and 1741 * the client chooses not to provide authentication information 1742 * about itself, <i>the negotiations will stop and the engine will 1743 * begin its closure procedure</i>. 1744 * <P> 1745 * Calling this method overrides any previous setting made by 1746 * this method or {@link #setWantClientAuth(boolean)}. 1747 * 1748 * @param need set to true if client authentication is required, 1749 * or false if no client authentication is desired. 1750 * @see #getNeedClientAuth() 1751 * @see #setWantClientAuth(boolean) 1752 * @see #getWantClientAuth() 1753 * @see #setUseClientMode(boolean) 1754 */ 1755 public abstract void setNeedClientAuth(boolean need); 1756 1757 1758 /** 1759 * Returns true if the engine will <i>require</i> client authentication. 1760 * This option is only useful to engines in the server mode. 1761 * 1762 * @return true if client authentication is required, 1763 * or false if no client authentication is desired. 1764 * @see #setNeedClientAuth(boolean) 1765 * @see #setWantClientAuth(boolean) 1766 * @see #getWantClientAuth() 1767 * @see #setUseClientMode(boolean) 1768 */ 1769 public abstract boolean getNeedClientAuth(); 1770 1771 1772 /** 1773 * Configures the engine to <i>request</i> client authentication. 1774 * This option is only useful for engines in the server mode. 1775 * <P> 1776 * An engine's client authentication setting is one of the following: 1777 * <ul> 1778 * <li> client authentication required 1779 * <li> client authentication requested 1780 * <li> no client authentication desired 1781 * </ul> 1782 * <P> 1783 * Unlike {@link #setNeedClientAuth(boolean)}, if this option is set and 1784 * the client chooses not to provide authentication information 1785 * about itself, <i>the negotiations will continue</i>. 1786 * <P> 1787 * Calling this method overrides any previous setting made by 1788 * this method or {@link #setNeedClientAuth(boolean)}. 1789 * 1790 * @param want set to true if client authentication is requested, 1791 * or false if no client authentication is desired. 1792 * @see #getWantClientAuth() 1793 * @see #setNeedClientAuth(boolean) 1794 * @see #getNeedClientAuth() 1795 * @see #setUseClientMode(boolean) 1796 */ 1797 public abstract void setWantClientAuth(boolean want); 1798 1799 1800 /** 1801 * Returns true if the engine will <i>request</i> client authentication. 1802 * This option is only useful for engines in the server mode. 1803 * 1804 * @return true if client authentication is requested, 1805 * or false if no client authentication is desired. 1806 * @see #setNeedClientAuth(boolean) 1807 * @see #getNeedClientAuth() 1808 * @see #setWantClientAuth(boolean) 1809 * @see #setUseClientMode(boolean) 1810 */ 1811 public abstract boolean getWantClientAuth(); 1812 1813 1814 /** 1815 * Controls whether new SSL sessions may be established by this engine. 1816 * If session creations are not allowed, and there are no 1817 * existing sessions to resume, there will be no successful 1818 * handshaking. 1819 * 1820 * @param flag true indicates that sessions may be created; this 1821 * is the default. false indicates that an existing session 1822 * must be resumed 1823 * @see #getEnableSessionCreation() 1824 */ 1825 public abstract void setEnableSessionCreation(boolean flag); 1826 1827 1828 /** 1829 * Returns true if new SSL sessions may be established by this engine. 1830 * 1831 * @return true indicates that sessions may be created; this 1832 * is the default. false indicates that an existing session 1833 * must be resumed 1834 * @see #setEnableSessionCreation(boolean) 1835 */ 1836 public abstract boolean getEnableSessionCreation(); 1837 1838 /** 1839 * Returns the SSLParameters in effect for this SSLEngine. 1840 * The ciphersuites and protocols of the returned SSLParameters 1841 * are always non-null. 1842 * 1843 * @return the SSLParameters in effect for this SSLEngine. 1844 * @since 1.6 1845 */ 1846 public SSLParameters getSSLParameters() { 1847 SSLParameters params = new SSLParameters(); 1848 params.setCipherSuites(getEnabledCipherSuites()); 1849 params.setProtocols(getEnabledProtocols()); 1850 if (getNeedClientAuth()) { 1851 params.setNeedClientAuth(true); 1852 } else if (getWantClientAuth()) { 1853 params.setWantClientAuth(true); 1854 } 1855 return params; 1856 } 1857 1858 /** 1859 * Applies SSLParameters to this engine. 1860 * 1861 * <p>This means: 1862 * <ul> 1863 * <li>if <code>params.getCipherSuites()</code> is non-null, 1864 * <code>setEnabledCipherSuites()</code> is called with that value 1865 * <li>if <code>params.getProtocols()</code> is non-null, 1866 * <code>setEnabledProtocols()</code> is called with that value 1867 * <li>if <code>params.getNeedClientAuth()</code> or 1868 * <code>params.getWantClientAuth()</code> return <code>true</code>, 1869 * <code>setNeedClientAuth(true)</code> and 1870 * <code>setWantClientAuth(true)</code> are called, respectively; 1871 * otherwise <code>setWantClientAuth(false)</code> is called. 1872 * </ul> 1873 * 1874 * @param params the parameters 1875 * @throws IllegalArgumentException if the setEnabledCipherSuites() or 1876 * the setEnabledProtocols() call fails 1877 * @since 1.6 1878 */ 1879 public void setSSLParameters(SSLParameters params) { 1880 String[] s; 1881 s = params.getCipherSuites(); 1882 if (s != null) { 1883 setEnabledCipherSuites(s); 1884 } 1885 s = params.getProtocols(); 1886 if (s != null) { 1887 setEnabledProtocols(s); 1888 } 1889 if (params.getNeedClientAuth()) { 1890 setNeedClientAuth(true); 1891 } else if (params.getWantClientAuth()) { 1892 setWantClientAuth(true); 1893 } else { 1894 setWantClientAuth(false); 1895 } 1896 } 1897 1898} 1899