1 /* 2 * Copyright (c) 1997, 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 27 package javax.net.ssl; 28 29 import java.io.IOException; 30 import java.net.*; 31 import java.util.List; 32 import java.util.function.BiFunction; 33 34 35 /** 36 * This class extends <code>Socket</code>s and provides secure 37 * socket using protocols such as the "Secure 38 * Sockets Layer" (SSL) or IETF "Transport Layer Security" (TLS) protocols. 39 * <P> 40 * Such sockets are normal stream sockets, but they 41 * add a layer of security protections over the underlying network transport 42 * protocol, such as TCP. Those protections include: <UL> 43 * 44 * <LI> <em>Integrity Protection</em>. SSL protects against 45 * modification of messages by an active wiretapper. 46 * 47 * <LI> <em>Authentication</em>. In most modes, SSL provides 48 * peer authentication. Servers are usually authenticated, 49 * and clients may be authenticated as requested by servers. 50 * 51 * <LI> <em>Confidentiality (Privacy Protection)</em>. In most 52 * modes, SSL encrypts data being sent between client and server. 53 * This protects the confidentiality of data, so that passive 54 * wiretappers won't see sensitive data such as financial 55 * information or personal information of many kinds. 56 * 57 * </UL> 58 * 59 * <P>These kinds of protection are specified by a "cipher suite", which 60 * is a combination of cryptographic algorithms used by a given SSL connection. 61 * During the negotiation process, the two endpoints must agree on 62 * a ciphersuite that is available in both environments. 63 * If there is no such suite in common, no SSL connection can 64 * be established, and no data can be exchanged. 65 * 66 * <P> The cipher suite used is established by a negotiation process 67 * called "handshaking". The goal of this 68 * process is to create or rejoin a "session", which may protect many 69 * connections over time. After handshaking has completed, you can access 70 * session attributes by using the <em>getSession</em> method. 71 * The initial handshake on this connection can be initiated in 72 * one of three ways: <UL> 73 * 74 * <LI> calling <code>startHandshake</code> which explicitly 75 * begins handshakes, or 76 * <LI> any attempt to read or write application data on 77 * this socket causes an implicit handshake, or 78 * <LI> a call to <code>getSession</code> tries to set up a session 79 * if there is no currently valid session, and 80 * an implicit handshake is done. 81 * </UL> 82 * 83 * <P>If handshaking fails for any reason, the <code>SSLSocket</code> 84 * is closed, and no further communications can be done. 85 * 86 * <P>There are two groups of cipher suites which you will need to know 87 * about when managing cipher suites: <UL> 88 * 89 * <LI> <em>Supported</em> cipher suites: all the suites which are 90 * supported by the SSL implementation. This list is reported 91 * using <em>getSupportedCipherSuites</em>. 92 * 93 * <LI> <em>Enabled</em> cipher suites, which may be fewer 94 * than the full set of supported suites. This group is 95 * set using the <em>setEnabledCipherSuites</em> method, and 96 * queried using the <em>getEnabledCipherSuites</em> method. 97 * Initially, a default set of cipher suites will be enabled on 98 * a new socket that represents the minimum suggested configuration. 99 * 100 * </UL> 101 * 102 * <P> Implementation defaults require that only cipher 103 * suites which authenticate servers and provide confidentiality 104 * be enabled by default. 105 * Only if both sides explicitly agree to unauthenticated and/or 106 * non-private (unencrypted) communications will such a ciphersuite be 107 * selected. 108 * 109 * <P>When <code>SSLSocket</code>s are first created, no handshaking 110 * is done so that applications may first set their communication 111 * preferences: what cipher suites to use, whether the socket should be 112 * in client or server mode, etc. 113 * However, security is always provided by the time that application data 114 * is sent over the connection. 115 * 116 * <P> You may register to receive event notification of handshake 117 * completion. This involves 118 * the use of two additional classes. <em>HandshakeCompletedEvent</em> 119 * objects are passed to <em>HandshakeCompletedListener</em> instances, 120 * which are registered by users of this API. 121 * 122 * <code>SSLSocket</code>s are created by <code>SSLSocketFactory</code>s, 123 * or by <code>accept</code>ing a connection from a 124 * <code>SSLServerSocket</code>. 125 * 126 * <P>A SSL socket must choose to operate in the client or server mode. 127 * This will determine who begins the handshaking process, as well 128 * as which messages should be sent by each party. Each 129 * connection must have one client and one server, or handshaking 130 * will not progress properly. Once the initial handshaking has started, a 131 * socket can not switch between client and server modes, even when 132 * performing renegotiations. 133 * 134 * <h3>Default configuration for different Android versions</h3> 135 * <p>{@code SSLSocket} instances obtained from default {@link SSLSocketFactory}, 136 * {@link SSLServerSocketFactory}, and {@link SSLContext} are configured as follows: 137 * 138 * <style type="text/css"> 139 * tr.deprecated { 140 * background-color: #ccc; 141 * color: #999; 142 * font-style: italic; 143 * } 144 * </style> 145 * 146 * <h4>Protocols</h4> 147 * 148 * <p>Client socket: 149 * <table> 150 * <thead> 151 * <tr> 152 * <th>Protocol</th> 153 * <th>Supported (API Levels)</th> 154 * <th>Enabled by default (API Levels)</th> 155 * </tr> 156 * </thead> 157 * <tbody> 158 * <tr class="deprecated"> 159 * <td>SSLv3</td> 160 * <td>1–25</td> 161 * <td>1–22</td> 162 * </tr> 163 * <tr> 164 * <td>TLSv1</td> 165 * <td>1+</td> 166 * <td>1+</td> 167 * </tr> 168 * <tr> 169 * <td>TLSv1.1</td> 170 * <td>16+</td> 171 * <td>20+</td> 172 * </tr> 173 * <tr> 174 * <td>TLSv1.2</td> 175 * <td>16+</td> 176 * <td>20+</td> 177 * </tr> 178 * <tr> 179 * <td>TLSv1.3</td> 180 * <td>29+</td> 181 * <td>29+</td> 182 * </tr> 183 * </tbody> 184 * </table> 185 * 186 * <p>Server socket: 187 * <table> 188 * <thead> 189 * <tr> 190 * <th>Protocol</th> 191 * <th>Supported (API Levels)</th> 192 * <th>Enabled by default (API Levels)</th> 193 * </tr> 194 * </thead> 195 * <tbody> 196 * <tr class="deprecated"> 197 * <td>SSLv3</td> 198 * <td>1–25</td> 199 * <td>1–22</td> 200 * </tr> 201 * <tr> 202 * <td>TLSv1</td> 203 * <td>1+</td> 204 * <td>1+</td> 205 * </tr> 206 * <tr> 207 * <td>TLSv1.1</td> 208 * <td>16+</td> 209 * <td>16+</td> 210 * </tr> 211 * <tr> 212 * <td>TLSv1.2</td> 213 * <td>16+</td> 214 * <td>16+</td> 215 * </tr> 216 * <tr> 217 * <td>TLSv1.3</td> 218 * <td>29+</td> 219 * <td>29+</td> 220 * </tr> 221 * </tbody> 222 * </table> 223 * 224 * <h4>Cipher suites</h4> 225 * 226 * <p>Methods that operate with cipher suite names (for example, 227 * {@link #getSupportedCipherSuites() getSupportedCipherSuites}, 228 * {@link #setEnabledCipherSuites(String[]) setEnabledCipherSuites}) have used 229 * standard names for cipher suites since API Level 9, as listed in the table 230 * below. Prior to API Level 9, non-standard (OpenSSL) names had been used (see 231 * the table following this table). 232 * <table> 233 * <thead> 234 * <tr> 235 * <th>Cipher suite</th> 236 * <th>Supported (API Levels)</th> 237 * <th>Enabled by default (API Levels)</th> 238 * </tr> 239 * </thead> 240 * <tbody> 241 * <tr class="deprecated"> 242 * <td>SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA</td> 243 * <td>9-22</td> 244 * <td>9-19</td> 245 * </tr> 246 * <tr class="deprecated"> 247 * <td>SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA</td> 248 * <td>9-22</td> 249 * <td>9-19</td> 250 * </tr> 251 * <tr class="deprecated"> 252 * <td>SSL_DHE_DSS_WITH_DES_CBC_SHA</td> 253 * <td>9-22</td> 254 * <td>9-19</td> 255 * </tr> 256 * <tr class="deprecated"> 257 * <td>SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA</td> 258 * <td>9-22</td> 259 * <td>9-19</td> 260 * </tr> 261 * <tr class="deprecated"> 262 * <td>SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA</td> 263 * <td>9-22</td> 264 * <td>9-19</td> 265 * </tr> 266 * <tr class="deprecated"> 267 * <td>SSL_DHE_RSA_WITH_DES_CBC_SHA</td> 268 * <td>9-22</td> 269 * <td>9-19</td> 270 * </tr> 271 * <tr class="deprecated"> 272 * <td>SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA</td> 273 * <td>9-22</td> 274 * <td></td> 275 * </tr> 276 * <tr class="deprecated"> 277 * <td>SSL_DH_anon_EXPORT_WITH_RC4_40_MD5</td> 278 * <td>9-22</td> 279 * <td></td> 280 * </tr> 281 * <tr class="deprecated"> 282 * <td>SSL_DH_anon_WITH_3DES_EDE_CBC_SHA</td> 283 * <td>9-22</td> 284 * <td></td> 285 * </tr> 286 * <tr class="deprecated"> 287 * <td>SSL_DH_anon_WITH_DES_CBC_SHA</td> 288 * <td>9-22</td> 289 * <td></td> 290 * </tr> 291 * <tr class="deprecated"> 292 * <td>SSL_DH_anon_WITH_RC4_128_MD5</td> 293 * <td>9-22</td> 294 * <td></td> 295 * </tr> 296 * <tr class="deprecated"> 297 * <td>SSL_RSA_EXPORT_WITH_DES40_CBC_SHA</td> 298 * <td>9-22</td> 299 * <td>9-19</td> 300 * </tr> 301 * <tr class="deprecated"> 302 * <td>SSL_RSA_EXPORT_WITH_RC4_40_MD5</td> 303 * <td>9-22</td> 304 * <td>9-19</td> 305 * </tr> 306 * <tr> 307 * <td>SSL_RSA_WITH_3DES_EDE_CBC_SHA</td> 308 * <td>9+</td> 309 * <td>9-19</td> 310 * </tr> 311 * <tr class="deprecated"> 312 * <td>SSL_RSA_WITH_DES_CBC_SHA</td> 313 * <td>9-22</td> 314 * <td>9-19</td> 315 * </tr> 316 * <tr class="deprecated"> 317 * <td>SSL_RSA_WITH_NULL_MD5</td> 318 * <td>9-22</td> 319 * <td></td> 320 * </tr> 321 * <tr class="deprecated"> 322 * <td>SSL_RSA_WITH_NULL_SHA</td> 323 * <td>9-22</td> 324 * <td></td> 325 * </tr> 326 * <tr class="deprecated"> 327 * <td>SSL_RSA_WITH_RC4_128_MD5</td> 328 * <td>9-25</td> 329 * <td>9-19</td> 330 * </tr> 331 * <tr class="deprecated"> 332 * <td>SSL_RSA_WITH_RC4_128_SHA</td> 333 * <td>9-25</td> 334 * <td>9-23</td> 335 * </tr> 336 * <tr> 337 * <td>TLS_AES_128_GCM_SHA256</td> 338 * <td>29+</td> 339 * <td>29+</td> 340 * </tr> 341 * <tr> 342 * <td>TLS_AES_256_GCM_SHA384</td> 343 * <td>29+</td> 344 * <td>29+</td> 345 * </tr> 346 * <tr> 347 * <td>TLS_CHACHA20_POLY1305_SHA256</td> 348 * <td>29+</td> 349 * <td>29+</td> 350 * </tr> 351 * <tr class="deprecated"> 352 * <td>TLS_DHE_DSS_WITH_AES_128_CBC_SHA</td> 353 * <td>9-22</td> 354 * <td>9-22</td> 355 * </tr> 356 * <tr class="deprecated"> 357 * <td>TLS_DHE_DSS_WITH_AES_128_CBC_SHA256</td> 358 * <td>20-22</td> 359 * <td></td> 360 * </tr> 361 * <tr class="deprecated"> 362 * <td>TLS_DHE_DSS_WITH_AES_128_GCM_SHA256</td> 363 * <td>20-22</td> 364 * <td></td> 365 * </tr> 366 * <tr class="deprecated"> 367 * <td>TLS_DHE_DSS_WITH_AES_256_CBC_SHA</td> 368 * <td>9-22</td> 369 * <td>11-22</td> 370 * </tr> 371 * <tr class="deprecated"> 372 * <td>TLS_DHE_DSS_WITH_AES_256_CBC_SHA256</td> 373 * <td>20-22</td> 374 * <td></td> 375 * </tr> 376 * <tr class="deprecated"> 377 * <td>TLS_DHE_DSS_WITH_AES_256_GCM_SHA384</td> 378 * <td>20-22</td> 379 * <td></td> 380 * </tr> 381 * <tr class="deprecated"> 382 * <td>TLS_DHE_RSA_WITH_AES_128_CBC_SHA</td> 383 * <td>9-25</td> 384 * <td>9-25</td> 385 * </tr> 386 * <tr class="deprecated"> 387 * <td>TLS_DHE_RSA_WITH_AES_128_CBC_SHA256</td> 388 * <td>20-25</td> 389 * <td></td> 390 * </tr> 391 * <tr class="deprecated"> 392 * <td>TLS_DHE_RSA_WITH_AES_128_GCM_SHA256</td> 393 * <td>20-25</td> 394 * <td>20-25</td> 395 * </tr> 396 * <tr class="deprecated"> 397 * <td>TLS_DHE_RSA_WITH_AES_256_CBC_SHA</td> 398 * <td>9-25</td> 399 * <td>11-25</td> 400 * </tr> 401 * <tr class="deprecated"> 402 * <td>TLS_DHE_RSA_WITH_AES_256_CBC_SHA256</td> 403 * <td>20-25</td> 404 * <td></td> 405 * </tr> 406 * <tr class="deprecated"> 407 * <td>TLS_DHE_RSA_WITH_AES_256_GCM_SHA384</td> 408 * <td>20-25</td> 409 * <td>20-25</td> 410 * </tr> 411 * <tr class="deprecated"> 412 * <td>TLS_DH_anon_WITH_AES_128_CBC_SHA</td> 413 * <td>9-22</td> 414 * <td></td> 415 * </tr> 416 * <tr class="deprecated"> 417 * <td>TLS_DH_anon_WITH_AES_128_CBC_SHA256</td> 418 * <td>20-22</td> 419 * <td></td> 420 * </tr> 421 * <tr class="deprecated"> 422 * <td>TLS_DH_anon_WITH_AES_128_GCM_SHA256</td> 423 * <td>20-22</td> 424 * <td></td> 425 * </tr> 426 * <tr class="deprecated"> 427 * <td>TLS_DH_anon_WITH_AES_256_CBC_SHA</td> 428 * <td>9-22</td> 429 * <td></td> 430 * </tr> 431 * <tr class="deprecated"> 432 * <td>TLS_DH_anon_WITH_AES_256_CBC_SHA256</td> 433 * <td>20-22</td> 434 * <td></td> 435 * </tr> 436 * <tr class="deprecated"> 437 * <td>TLS_DH_anon_WITH_AES_256_GCM_SHA384</td> 438 * <td>20-22</td> 439 * <td></td> 440 * </tr> 441 * <tr class="deprecated"> 442 * <td>TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA</td> 443 * <td>11-22</td> 444 * <td>11-19</td> 445 * </tr> 446 * <tr> 447 * <td>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</td> 448 * <td>11+</td> 449 * <td>11+</td> 450 * </tr> 451 * <tr class="deprecated"> 452 * <td>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256</td> 453 * <td>20-28</td> 454 * <td></td> 455 * </tr> 456 * <tr> 457 * <td>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</td> 458 * <td>20+</td> 459 * <td>20+</td> 460 * </tr> 461 * <tr> 462 * <td>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</td> 463 * <td>11+</td> 464 * <td>11+</td> 465 * </tr> 466 * <tr class="deprecated"> 467 * <td>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384</td> 468 * <td>20-28</td> 469 * <td></td> 470 * </tr> 471 * <tr> 472 * <td>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</td> 473 * <td>20+</td> 474 * <td>20+</td> 475 * </tr> 476 * <tr> 477 * <td>TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256</td> 478 * <td>24+</td> 479 * <td>24+</td> 480 * </tr> 481 * <tr class="deprecated"> 482 * <td>TLS_ECDHE_ECDSA_WITH_NULL_SHA</td> 483 * <td>11-22</td> 484 * <td></td> 485 * </tr> 486 * <tr class="deprecated"> 487 * <td>TLS_ECDHE_ECDSA_WITH_RC4_128_SHA</td> 488 * <td>11-25</td> 489 * <td>11-23</td> 490 * </tr> 491 * <tr> 492 * <td>TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA</td> 493 * <td>21+</td> 494 * <td>21+</td> 495 * </tr> 496 * <tr> 497 * <td>TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA</td> 498 * <td>21+</td> 499 * <td>21+</td> 500 * </tr> 501 * <tr> 502 * <td>TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256</td> 503 * <td>24+</td> 504 * <td>24+</td> 505 * </tr> 506 * <tr class="deprecated"> 507 * <td>TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA</td> 508 * <td>11-22</td> 509 * <td>11-19</td> 510 * </tr> 511 * <tr> 512 * <td>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</td> 513 * <td>11+</td> 514 * <td>11+</td> 515 * </tr> 516 * <tr class="deprecated"> 517 * <td>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</td> 518 * <td>20-28</td> 519 * <td></td> 520 * </tr> 521 * <tr> 522 * <td>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</td> 523 * <td>20+</td> 524 * <td>20+</td> 525 * </tr> 526 * <tr> 527 * <td>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</td> 528 * <td>11+</td> 529 * <td>11+</td> 530 * </tr> 531 * <tr class="deprecated"> 532 * <td>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384</td> 533 * <td>20-28</td> 534 * <td></td> 535 * </tr> 536 * <tr> 537 * <td>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</td> 538 * <td>20+</td> 539 * <td>20+</td> 540 * </tr> 541 * <tr> 542 * <td>TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256</td> 543 * <td>24+</td> 544 * <td>24+</td> 545 * </tr> 546 * <tr class="deprecated"> 547 * <td>TLS_ECDHE_RSA_WITH_NULL_SHA</td> 548 * <td>11-22</td> 549 * <td></td> 550 * </tr> 551 * <tr class="deprecated"> 552 * <td>TLS_ECDHE_RSA_WITH_RC4_128_SHA</td> 553 * <td>11-25</td> 554 * <td>11-23</td> 555 * </tr> 556 * <tr class="deprecated"> 557 * <td>TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA</td> 558 * <td>11-22</td> 559 * <td>11-19</td> 560 * </tr> 561 * <tr class="deprecated"> 562 * <td>TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA</td> 563 * <td>11-22</td> 564 * <td>11-19</td> 565 * </tr> 566 * <tr class="deprecated"> 567 * <td>TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256</td> 568 * <td>20-22</td> 569 * <td></td> 570 * </tr> 571 * <tr class="deprecated"> 572 * <td>TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256</td> 573 * <td>20-22</td> 574 * <td></td> 575 * </tr> 576 * <tr class="deprecated"> 577 * <td>TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA</td> 578 * <td>11-22</td> 579 * <td>11-19</td> 580 * </tr> 581 * <tr class="deprecated"> 582 * <td>TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384</td> 583 * <td>20-22</td> 584 * <td></td> 585 * </tr> 586 * <tr class="deprecated"> 587 * <td>TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384</td> 588 * <td>20-22</td> 589 * <td></td> 590 * </tr> 591 * <tr class="deprecated"> 592 * <td>TLS_ECDH_ECDSA_WITH_NULL_SHA</td> 593 * <td>11-22</td> 594 * <td></td> 595 * </tr> 596 * <tr class="deprecated"> 597 * <td>TLS_ECDH_ECDSA_WITH_RC4_128_SHA</td> 598 * <td>11-22</td> 599 * <td>11-19</td> 600 * </tr> 601 * <tr class="deprecated"> 602 * <td>TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA</td> 603 * <td>11-22</td> 604 * <td>11-19</td> 605 * </tr> 606 * <tr class="deprecated"> 607 * <td>TLS_ECDH_RSA_WITH_AES_128_CBC_SHA</td> 608 * <td>11-22</td> 609 * <td>11-19</td> 610 * </tr> 611 * <tr class="deprecated"> 612 * <td>TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256</td> 613 * <td>20-22</td> 614 * <td></td> 615 * </tr> 616 * <tr class="deprecated"> 617 * <td>TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256</td> 618 * <td>20-22</td> 619 * <td></td> 620 * </tr> 621 * <tr class="deprecated"> 622 * <td>TLS_ECDH_RSA_WITH_AES_256_CBC_SHA</td> 623 * <td>11-22</td> 624 * <td>11-19</td> 625 * </tr> 626 * <tr class="deprecated"> 627 * <td>TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384</td> 628 * <td>20-22</td> 629 * <td></td> 630 * </tr> 631 * <tr class="deprecated"> 632 * <td>TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384</td> 633 * <td>20-22</td> 634 * <td></td> 635 * </tr> 636 * <tr class="deprecated"> 637 * <td>TLS_ECDH_RSA_WITH_NULL_SHA</td> 638 * <td>11-22</td> 639 * <td></td> 640 * </tr> 641 * <tr class="deprecated"> 642 * <td>TLS_ECDH_RSA_WITH_RC4_128_SHA</td> 643 * <td>11-22</td> 644 * <td>11-19</td> 645 * </tr> 646 * <tr class="deprecated"> 647 * <td>TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA</td> 648 * <td>11-22</td> 649 * <td></td> 650 * </tr> 651 * <tr class="deprecated"> 652 * <td>TLS_ECDH_anon_WITH_AES_128_CBC_SHA</td> 653 * <td>11-22</td> 654 * <td></td> 655 * </tr> 656 * <tr class="deprecated"> 657 * <td>TLS_ECDH_anon_WITH_AES_256_CBC_SHA</td> 658 * <td>11-22</td> 659 * <td></td> 660 * </tr> 661 * <tr class="deprecated"> 662 * <td>TLS_ECDH_anon_WITH_NULL_SHA</td> 663 * <td>11-22</td> 664 * <td></td> 665 * </tr> 666 * <tr class="deprecated"> 667 * <td>TLS_ECDH_anon_WITH_RC4_128_SHA</td> 668 * <td>11-22</td> 669 * <td></td> 670 * </tr> 671 * <tr> 672 * <td>TLS_EMPTY_RENEGOTIATION_INFO_SCSV</td> 673 * <td>11+</td> 674 * <td>11+</td> 675 * </tr> 676 * <tr> 677 * <td>TLS_FALLBACK_SCSV</td> 678 * <td>21+</td> 679 * <td></td> 680 * </tr> 681 * <tr class="deprecated"> 682 * <td>TLS_PSK_WITH_3DES_EDE_CBC_SHA</td> 683 * <td>21-22</td> 684 * <td></td> 685 * </tr> 686 * <tr> 687 * <td>TLS_PSK_WITH_AES_128_CBC_SHA</td> 688 * <td>21+</td> 689 * <td>21+</td> 690 * </tr> 691 * <tr> 692 * <td>TLS_PSK_WITH_AES_256_CBC_SHA</td> 693 * <td>21+</td> 694 * <td>21+</td> 695 * </tr> 696 * <tr class="deprecated"> 697 * <td>TLS_PSK_WITH_RC4_128_SHA</td> 698 * <td>21-25</td> 699 * <td></td> 700 * </tr> 701 * <tr> 702 * <td>TLS_RSA_WITH_AES_128_CBC_SHA</td> 703 * <td>9+</td> 704 * <td>9+</td> 705 * </tr> 706 * <tr class="deprecated"> 707 * <td>TLS_RSA_WITH_AES_128_CBC_SHA256</td> 708 * <td>20-28</td> 709 * <td></td> 710 * </tr> 711 * <tr> 712 * <td>TLS_RSA_WITH_AES_128_GCM_SHA256</td> 713 * <td>20+</td> 714 * <td>20+</td> 715 * </tr> 716 * <tr> 717 * <td>TLS_RSA_WITH_AES_256_CBC_SHA</td> 718 * <td>9+</td> 719 * <td>11+</td> 720 * </tr> 721 * <tr class="deprecated"> 722 * <td>TLS_RSA_WITH_AES_256_CBC_SHA256</td> 723 * <td>20-28</td> 724 * <td></td> 725 * </tr> 726 * <tr> 727 * <td>TLS_RSA_WITH_AES_256_GCM_SHA384</td> 728 * <td>20+</td> 729 * <td>20+</td> 730 * </tr> 731 * <tr class="deprecated"> 732 * <td>TLS_RSA_WITH_NULL_SHA256</td> 733 * <td>20-22</td> 734 * <td></td> 735 * </tr> 736 * </tbody> 737 * </table> 738 * 739 * <p><em>NOTE</em>: PSK cipher suites are enabled by default only if the {@code SSLContext} through 740 * which the socket was created has been initialized with a {@code PSKKeyManager}. 741 * 742 * <p>API Levels 1 to 8 use OpenSSL names for cipher suites. The table below 743 * lists these OpenSSL names and their corresponding standard names used in API 744 * Levels 9 and newer. 745 * <table> 746 * <thead> 747 * <tr> 748 * <th>OpenSSL cipher suite</th> 749 * <th>Standard cipher suite</th> 750 * <th>Supported (API Levels)</th> 751 * <th>Enabled by default (API Levels)</th> 752 * </tr> 753 * </thead> 754 * 755 * <tbody> 756 * <tr> 757 * <td>AES128-SHA</td> 758 * <td>TLS_RSA_WITH_AES_128_CBC_SHA</td> 759 * <td>1+</td> 760 * <td>1+</td> 761 * </tr> 762 * <tr> 763 * <td>AES256-SHA</td> 764 * <td>TLS_RSA_WITH_AES_256_CBC_SHA</td> 765 * <td>1+</td> 766 * <td>1–8, 11+</td> 767 * </tr> 768 * <tr> 769 * <td>DES-CBC-MD5</td> 770 * <td>SSL_CK_DES_64_CBC_WITH_MD5</td> 771 * <td>1–8</td> 772 * <td>1–8</td> 773 * </tr> 774 * <tr class="deprecated"> 775 * <td>DES-CBC-SHA</td> 776 * <td>SSL_RSA_WITH_DES_CBC_SHA</td> 777 * <td>1–22</td> 778 * <td>1–19</td> 779 * </tr> 780 * <tr> 781 * <td>DES-CBC3-MD5</td> 782 * <td>SSL_CK_DES_192_EDE3_CBC_WITH_MD5</td> 783 * <td>1–8</td> 784 * <td>1–8</td> 785 * </tr> 786 * <tr> 787 * <td>DES-CBC3-SHA</td> 788 * <td>SSL_RSA_WITH_3DES_EDE_CBC_SHA</td> 789 * <td>1+</td> 790 * <td>1–19</td> 791 * </tr> 792 * <tr class="deprecated"> 793 * <td>DHE-DSS-AES128-SHA</td> 794 * <td>TLS_DHE_DSS_WITH_AES_128_CBC_SHA</td> 795 * <td>1–22</td> 796 * <td>1–22</td> 797 * </tr> 798 * <tr class="deprecated"> 799 * <td>DHE-DSS-AES256-SHA</td> 800 * <td>TLS_DHE_DSS_WITH_AES_256_CBC_SHA</td> 801 * <td>1–22</td> 802 * <td>1–8, 11–22</td> 803 * </tr> 804 * <tr> 805 * <td>DHE-RSA-AES128-SHA</td> 806 * <td>TLS_DHE_RSA_WITH_AES_128_CBC_SHA</td> 807 * <td>1+</td> 808 * <td>1+</td> 809 * </tr> 810 * <tr> 811 * <td>DHE-RSA-AES256-SHA</td> 812 * <td>TLS_DHE_RSA_WITH_AES_256_CBC_SHA</td> 813 * <td>1+</td> 814 * <td>1–8, 11+</td> 815 * </tr> 816 * <tr class="deprecated"> 817 * <td>EDH-DSS-DES-CBC-SHA</td> 818 * <td>SSL_DHE_DSS_WITH_DES_CBC_SHA</td> 819 * <td>1–22</td> 820 * <td>1–19</td> 821 * </tr> 822 * <tr class="deprecated"> 823 * <td>EDH-DSS-DES-CBC3-SHA</td> 824 * <td>SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA</td> 825 * <td>1–22</td> 826 * <td>1–19</td> 827 * </tr> 828 * <tr class="deprecated"> 829 * <td>EDH-RSA-DES-CBC-SHA</td> 830 * <td>SSL_DHE_RSA_WITH_DES_CBC_SHA</td> 831 * <td>1–22</td> 832 * <td>1–19</td> 833 * </tr> 834 * <tr class="deprecated"> 835 * <td>EDH-RSA-DES-CBC3-SHA</td> 836 * <td>SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA</td> 837 * <td>1–22</td> 838 * <td>1–19</td> 839 * </tr> 840 * <tr class="deprecated"> 841 * <td>EXP-DES-CBC-SHA</td> 842 * <td>SSL_RSA_EXPORT_WITH_DES40_CBC_SHA</td> 843 * <td>1–22</td> 844 * <td>1–19</td> 845 * </tr> 846 * <tr class="deprecated"> 847 * <td>EXP-EDH-DSS-DES-CBC-SHA</td> 848 * <td>SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA</td> 849 * <td>1–22</td> 850 * <td>1–19</td> 851 * </tr> 852 * <tr class="deprecated"> 853 * <td>EXP-EDH-RSA-DES-CBC-SHA</td> 854 * <td>SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA</td> 855 * <td>1–22</td> 856 * <td>1–19</td> 857 * </tr> 858 * <tr> 859 * <td>EXP-RC2-CBC-MD5</td> 860 * <td>SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5</td> 861 * <td>1–8</td> 862 * <td>1–8</td> 863 * </tr> 864 * <tr class="deprecated"> 865 * <td>EXP-RC4-MD5</td> 866 * <td>SSL_RSA_EXPORT_WITH_RC4_40_MD5</td> 867 * <td>1–22</td> 868 * <td>1–19</td> 869 * </tr> 870 * <tr> 871 * <td>RC2-CBC-MD5</td> 872 * <td>SSL_CK_RC2_128_CBC_WITH_MD5</td> 873 * <td>1–8</td> 874 * <td>1–8</td> 875 * </tr> 876 * <tr class="deprecated"> 877 * <td>RC4-MD5</td> 878 * <td>SSL_RSA_WITH_RC4_128_MD5</td> 879 * <td>1–25</td> 880 * <td>1–19</td> 881 * </tr> 882 * <tr class="deprecated"> 883 * <td>RC4-SHA</td> 884 * <td>SSL_RSA_WITH_RC4_128_SHA</td> 885 * <td>1–25</td> 886 * <td>1–23</td> 887 * </tr> 888 * </tbody> 889 * </table> 890 * 891 * @see java.net.Socket 892 * @see SSLServerSocket 893 * @see SSLSocketFactory 894 * 895 * @since 1.4 896 * @author David Brownell 897 */ 898 public abstract class SSLSocket extends Socket 899 { 900 /** 901 * Used only by subclasses. 902 * Constructs an uninitialized, unconnected TCP socket. 903 */ SSLSocket()904 protected SSLSocket() 905 { super(); } 906 907 908 /** 909 * Used only by subclasses. 910 * Constructs a TCP connection to a named host at a specified port. 911 * This acts as the SSL client. 912 * <p> 913 * If there is a security manager, its <code>checkConnect</code> 914 * method is called with the host address and <code>port</code> 915 * as its arguments. This could result in a SecurityException. 916 * 917 * @param host name of the host with which to connect, or 918 * <code>null</code> for the loopback address. 919 * @param port number of the server's port 920 * @throws IOException if an I/O error occurs when creating the socket 921 * @throws SecurityException if a security manager exists and its 922 * <code>checkConnect</code> method doesn't allow the operation. 923 * @throws UnknownHostException if the host is not known 924 * @throws IllegalArgumentException if the port parameter is outside the 925 * specified range of valid port values, which is between 0 and 926 * 65535, inclusive. 927 * @see SecurityManager#checkConnect 928 */ SSLSocket(String host, int port)929 protected SSLSocket(String host, int port) 930 throws IOException, UnknownHostException 931 { super(host, port); } 932 933 934 /** 935 * Used only by subclasses. 936 * Constructs a TCP connection to a server at a specified address 937 * and port. This acts as the SSL client. 938 * <p> 939 * If there is a security manager, its <code>checkConnect</code> 940 * method is called with the host address and <code>port</code> 941 * as its arguments. This could result in a SecurityException. 942 * 943 * @param address the server's host 944 * @param port its port 945 * @throws IOException if an I/O error occurs when creating the socket 946 * @throws SecurityException if a security manager exists and its 947 * <code>checkConnect</code> method doesn't allow the operation. 948 * @throws IllegalArgumentException if the port parameter is outside the 949 * specified range of valid port values, which is between 0 and 950 * 65535, inclusive. 951 * @throws NullPointerException if <code>address</code> is null. 952 * @see SecurityManager#checkConnect 953 */ SSLSocket(InetAddress address, int port)954 protected SSLSocket(InetAddress address, int port) 955 throws IOException 956 { super(address, port); } 957 958 959 /** 960 * Used only by subclasses. 961 * Constructs an SSL connection to a named host at a specified port, 962 * binding the client side of the connection a given address and port. 963 * This acts as the SSL client. 964 * <p> 965 * If there is a security manager, its <code>checkConnect</code> 966 * method is called with the host address and <code>port</code> 967 * as its arguments. This could result in a SecurityException. 968 * 969 * @param host name of the host with which to connect, or 970 * <code>null</code> for the loopback address. 971 * @param port number of the server's port 972 * @param clientAddress the client's address the socket is bound to, or 973 * <code>null</code> for the <code>anyLocal</code> address. 974 * @param clientPort the client's port the socket is bound to, or 975 * <code>zero</code> for a system selected free port. 976 * @throws IOException if an I/O error occurs when creating the socket 977 * @throws SecurityException if a security manager exists and its 978 * <code>checkConnect</code> method doesn't allow the operation. 979 * @throws UnknownHostException if the host is not known 980 * @throws IllegalArgumentException if the port parameter or clientPort 981 * parameter is outside the specified range of valid port values, 982 * which is between 0 and 65535, inclusive. 983 * @see SecurityManager#checkConnect 984 */ SSLSocket(String host, int port, InetAddress clientAddress, int clientPort)985 protected SSLSocket(String host, int port, 986 InetAddress clientAddress, int clientPort) 987 throws IOException, UnknownHostException 988 { super(host, port, clientAddress, clientPort); } 989 990 991 /** 992 * Used only by subclasses. 993 * Constructs an SSL connection to a server at a specified address 994 * and TCP port, binding the client side of the connection a given 995 * address and port. This acts as the SSL client. 996 * <p> 997 * If there is a security manager, its <code>checkConnect</code> 998 * method is called with the host address and <code>port</code> 999 * as its arguments. This could result in a SecurityException. 1000 * 1001 * @param address the server's host 1002 * @param port its port 1003 * @param clientAddress the client's address the socket is bound to, or 1004 * <code>null</code> for the <code>anyLocal</code> address. 1005 * @param clientPort the client's port the socket is bound to, or 1006 * <code>zero</code> for a system selected free port. 1007 * @throws IOException if an I/O error occurs when creating the socket 1008 * @throws SecurityException if a security manager exists and its 1009 * <code>checkConnect</code> method doesn't allow the operation. 1010 * @throws IllegalArgumentException if the port parameter or clientPort 1011 * parameter is outside the specified range of valid port values, 1012 * which is between 0 and 65535, inclusive. 1013 * @throws NullPointerException if <code>address</code> is null. 1014 * @see SecurityManager#checkConnect 1015 */ SSLSocket(InetAddress address, int port, InetAddress clientAddress, int clientPort)1016 protected SSLSocket(InetAddress address, int port, 1017 InetAddress clientAddress, int clientPort) 1018 throws IOException 1019 { super(address, port, clientAddress, clientPort); } 1020 1021 1022 // Android-changed: Added warnings about misuse 1023 /** 1024 * Returns the names of the cipher suites which could be enabled for use 1025 * on this connection. Normally, only a subset of these will actually 1026 * be enabled by default, since this list may include cipher suites which 1027 * do not meet quality of service requirements for those defaults. Such 1028 * cipher suites might be useful in specialized applications. 1029 * 1030 * <p class="caution">Applications should not blindly enable all supported 1031 * cipher suites. The supported cipher suites can include signaling cipher suite 1032 * values that can cause connection problems if enabled inappropriately. 1033 * 1034 * <p>The proper way to use this method is to either check if a specific cipher 1035 * suite is supported via {@code Arrays.asList(getSupportedCipherSuites()).contains(...)} 1036 * or to filter a desired list of cipher suites to only the supported ones via 1037 * {@code desiredSuiteSet.retainAll(Arrays.asList(getSupportedCipherSuites()))}. 1038 * 1039 * @return an array of cipher suite names 1040 * @see #getEnabledCipherSuites() 1041 * @see #setEnabledCipherSuites(String []) 1042 */ getSupportedCipherSuites()1043 public abstract String [] getSupportedCipherSuites(); 1044 1045 1046 /** 1047 * Returns the names of the SSL cipher suites which are currently 1048 * enabled for use on this connection. When an SSLSocket is first 1049 * created, all enabled cipher suites support a minimum quality of 1050 * service. Thus, in some environments this value might be empty. 1051 * <P> 1052 * Even if a suite has been enabled, it might never be used. (For 1053 * example, the peer does not support it, the requisite certificates 1054 * (and private keys) for the suite are not available, or an 1055 * anonymous suite is enabled but authentication is required. 1056 * 1057 * @return an array of cipher suite names 1058 * @see #getSupportedCipherSuites() 1059 * @see #setEnabledCipherSuites(String []) 1060 */ getEnabledCipherSuites()1061 public abstract String [] getEnabledCipherSuites(); 1062 1063 1064 /** 1065 * Sets the cipher suites enabled for use on this connection. 1066 * <P> 1067 * Each cipher suite in the <code>suites</code> parameter must have 1068 * been listed by getSupportedCipherSuites(), or the method will 1069 * fail. Following a successful call to this method, only suites 1070 * listed in the <code>suites</code> parameter are enabled for use. 1071 * <P> 1072 * See {@link #getEnabledCipherSuites()} for more information 1073 * on why a specific ciphersuite may never be used on a connection. 1074 * 1075 * @param suites Names of all the cipher suites to enable 1076 * @throws IllegalArgumentException when one or more of the ciphers 1077 * named by the parameter is not supported, or when the 1078 * parameter is null. 1079 * @see #getSupportedCipherSuites() 1080 * @see #getEnabledCipherSuites() 1081 */ setEnabledCipherSuites(String suites [])1082 public abstract void setEnabledCipherSuites(String suites []); 1083 1084 1085 /** 1086 * Returns the names of the protocols which could be enabled for use 1087 * on an SSL connection. 1088 * 1089 * @return an array of protocols supported 1090 */ getSupportedProtocols()1091 public abstract String [] getSupportedProtocols(); 1092 1093 1094 /** 1095 * Returns the names of the protocol versions which are currently 1096 * enabled for use on this connection. 1097 * @see #setEnabledProtocols(String []) 1098 * @return an array of protocols 1099 */ getEnabledProtocols()1100 public abstract String [] getEnabledProtocols(); 1101 1102 1103 // Android-added: Added paragraph about contiguous protocols. 1104 /** 1105 * Sets the protocol versions enabled for use on this connection. 1106 * <P> 1107 * The protocols must have been listed by 1108 * <code>getSupportedProtocols()</code> as being supported. 1109 * Following a successful call to this method, only protocols listed 1110 * in the <code>protocols</code> parameter are enabled for use. 1111 * <p> 1112 * Because of the way the protocol version is negotiated, connections 1113 * will only be able to use a member of the lowest set of contiguous 1114 * enabled protocol versions. For example, enabling TLSv1.2 and TLSv1 1115 * will result in connections only being able to use TLSv1. 1116 * 1117 * @param protocols Names of all the protocols to enable. 1118 * @throws IllegalArgumentException when one or more of 1119 * the protocols named by the parameter is not supported or 1120 * when the protocols parameter is null. 1121 * @see #getEnabledProtocols() 1122 */ setEnabledProtocols(String protocols[])1123 public abstract void setEnabledProtocols(String protocols[]); 1124 1125 1126 /** 1127 * Returns the SSL Session in use by this connection. These can 1128 * be long lived, and frequently correspond to an entire login session 1129 * for some user. The session specifies a particular cipher suite 1130 * which is being actively used by all connections in that session, 1131 * as well as the identities of the session's client and server. 1132 * <P> 1133 * This method will initiate the initial handshake if 1134 * necessary and then block until the handshake has been 1135 * established. 1136 * <P> 1137 * If an error occurs during the initial handshake, this method 1138 * returns an invalid session object which reports an invalid 1139 * cipher suite of "SSL_NULL_WITH_NULL_NULL". 1140 * 1141 * @return the <code>SSLSession</code> 1142 */ getSession()1143 public abstract SSLSession getSession(); 1144 1145 1146 /** 1147 * Returns the {@code SSLSession} being constructed during a SSL/TLS 1148 * handshake. 1149 * <p> 1150 * TLS protocols may negotiate parameters that are needed when using 1151 * an instance of this class, but before the {@code SSLSession} has 1152 * been completely initialized and made available via {@code getSession}. 1153 * For example, the list of valid signature algorithms may restrict 1154 * the type of certificates that can used during TrustManager 1155 * decisions, or the maximum TLS fragment packet sizes can be 1156 * resized to better support the network environment. 1157 * <p> 1158 * This method provides early access to the {@code SSLSession} being 1159 * constructed. Depending on how far the handshake has progressed, 1160 * some data may not yet be available for use. For example, if a 1161 * remote server will be sending a Certificate chain, but that chain 1162 * has yet not been processed, the {@code getPeerCertificates} 1163 * method of {@code SSLSession} will throw a 1164 * SSLPeerUnverifiedException. Once that chain has been processed, 1165 * {@code getPeerCertificates} will return the proper value. 1166 * <p> 1167 * Unlike {@link #getSession()}, this method does not initiate the 1168 * initial handshake and does not block until handshaking is 1169 * complete. 1170 * 1171 * @see SSLEngine 1172 * @see SSLSession 1173 * @see ExtendedSSLSession 1174 * @see X509ExtendedKeyManager 1175 * @see X509ExtendedTrustManager 1176 * 1177 * @return null if this instance is not currently handshaking, or 1178 * if the current handshake has not progressed far enough to 1179 * create a basic SSLSession. Otherwise, this method returns the 1180 * {@code SSLSession} currently being negotiated. 1181 * @throws UnsupportedOperationException if the underlying provider 1182 * does not implement the operation. 1183 * 1184 * @since 1.7 1185 */ getHandshakeSession()1186 public SSLSession getHandshakeSession() { 1187 throw new UnsupportedOperationException(); 1188 } 1189 1190 1191 /** 1192 * Registers an event listener to receive notifications that an 1193 * SSL handshake has completed on this connection. 1194 * 1195 * @param listener the HandShake Completed event listener 1196 * @see #startHandshake() 1197 * @see #removeHandshakeCompletedListener(HandshakeCompletedListener) 1198 * @throws IllegalArgumentException if the argument is null. 1199 */ addHandshakeCompletedListener( HandshakeCompletedListener listener)1200 public abstract void addHandshakeCompletedListener( 1201 HandshakeCompletedListener listener); 1202 1203 1204 /** 1205 * Removes a previously registered handshake completion listener. 1206 * 1207 * @param listener the HandShake Completed event listener 1208 * @throws IllegalArgumentException if the listener is not registered, 1209 * or the argument is null. 1210 * @see #addHandshakeCompletedListener(HandshakeCompletedListener) 1211 */ removeHandshakeCompletedListener( HandshakeCompletedListener listener)1212 public abstract void removeHandshakeCompletedListener( 1213 HandshakeCompletedListener listener); 1214 1215 1216 /** 1217 * Starts an SSL handshake on this connection. Common reasons include 1218 * a need to use new encryption keys, to change cipher suites, or to 1219 * initiate a new session. To force complete reauthentication, the 1220 * current session could be invalidated before starting this handshake. 1221 * 1222 * <P> If data has already been sent on the connection, it continues 1223 * to flow during this handshake. When the handshake completes, this 1224 * will be signaled with an event. 1225 * 1226 * This method is synchronous for the initial handshake on a connection 1227 * and returns when the negotiated handshake is complete. Some 1228 * protocols may not support multiple handshakes on an existing socket 1229 * and may throw an IOException. 1230 * 1231 * @throws IOException on a network level error 1232 * @see #addHandshakeCompletedListener(HandshakeCompletedListener) 1233 */ startHandshake()1234 public abstract void startHandshake() throws IOException; 1235 1236 1237 /** 1238 * Configures the socket to use client (or server) mode when 1239 * handshaking. 1240 * <P> 1241 * This method must be called before any handshaking occurs. 1242 * Once handshaking has begun, the mode can not be reset for the 1243 * life of this socket. 1244 * <P> 1245 * Servers normally authenticate themselves, and clients 1246 * are not required to do so. 1247 * 1248 * @param mode true if the socket should start its handshaking 1249 * in "client" mode 1250 * @throws IllegalArgumentException if a mode change is attempted 1251 * after the initial handshake has begun. 1252 * @see #getUseClientMode() 1253 */ setUseClientMode(boolean mode)1254 public abstract void setUseClientMode(boolean mode); 1255 1256 1257 /** 1258 * Returns true if the socket is set to use client mode when 1259 * handshaking. 1260 * 1261 * @return true if the socket should do handshaking 1262 * in "client" mode 1263 * @see #setUseClientMode(boolean) 1264 */ getUseClientMode()1265 public abstract boolean getUseClientMode(); 1266 1267 1268 /** 1269 * Configures the socket to <i>require</i> client authentication. This 1270 * option is only useful for sockets in the server mode. 1271 * <P> 1272 * A socket's client authentication setting is one of the following: 1273 * <ul> 1274 * <li> client authentication required 1275 * <li> client authentication requested 1276 * <li> no client authentication desired 1277 * </ul> 1278 * <P> 1279 * Unlike {@link #setWantClientAuth(boolean)}, if this option is set and 1280 * the client chooses not to provide authentication information 1281 * about itself, <i>the negotiations will stop and the connection 1282 * will be dropped</i>. 1283 * <P> 1284 * Calling this method overrides any previous setting made by 1285 * this method or {@link #setWantClientAuth(boolean)}. 1286 * 1287 * @param need set to true if client authentication is required, 1288 * or false if no client authentication is desired. 1289 * @see #getNeedClientAuth() 1290 * @see #setWantClientAuth(boolean) 1291 * @see #getWantClientAuth() 1292 * @see #setUseClientMode(boolean) 1293 */ setNeedClientAuth(boolean need)1294 public abstract void setNeedClientAuth(boolean need); 1295 1296 1297 /** 1298 * Returns true if the socket will <i>require</i> client authentication. 1299 * This option is only useful to sockets in the server mode. 1300 * 1301 * @return true if client authentication is required, 1302 * or false if no client authentication is desired. 1303 * @see #setNeedClientAuth(boolean) 1304 * @see #setWantClientAuth(boolean) 1305 * @see #getWantClientAuth() 1306 * @see #setUseClientMode(boolean) 1307 */ getNeedClientAuth()1308 public abstract boolean getNeedClientAuth(); 1309 1310 1311 /** 1312 * Configures the socket to <i>request</i> client authentication. 1313 * This option is only useful for sockets in the server mode. 1314 * <P> 1315 * A socket's client authentication setting is one of the following: 1316 * <ul> 1317 * <li> client authentication required 1318 * <li> client authentication requested 1319 * <li> no client authentication desired 1320 * </ul> 1321 * <P> 1322 * Unlike {@link #setNeedClientAuth(boolean)}, if this option is set and 1323 * the client chooses not to provide authentication information 1324 * about itself, <i>the negotiations will continue</i>. 1325 * <P> 1326 * Calling this method overrides any previous setting made by 1327 * this method or {@link #setNeedClientAuth(boolean)}. 1328 * 1329 * @param want set to true if client authentication is requested, 1330 * or false if no client authentication is desired. 1331 * @see #getWantClientAuth() 1332 * @see #setNeedClientAuth(boolean) 1333 * @see #getNeedClientAuth() 1334 * @see #setUseClientMode(boolean) 1335 */ setWantClientAuth(boolean want)1336 public abstract void setWantClientAuth(boolean want); 1337 1338 1339 /** 1340 * Returns true if the socket will <i>request</i> client authentication. 1341 * This option is only useful for sockets in the server mode. 1342 * 1343 * @return true if client authentication is requested, 1344 * or false if no client authentication is desired. 1345 * @see #setNeedClientAuth(boolean) 1346 * @see #getNeedClientAuth() 1347 * @see #setWantClientAuth(boolean) 1348 * @see #setUseClientMode(boolean) 1349 */ getWantClientAuth()1350 public abstract boolean getWantClientAuth(); 1351 1352 1353 /** 1354 * Controls whether new SSL sessions may be established by this socket. 1355 * If session creations are not allowed, and there are no 1356 * existing sessions to resume, there will be no successful 1357 * handshaking. 1358 * 1359 * @param flag true indicates that sessions may be created; this 1360 * is the default. false indicates that an existing session 1361 * must be resumed 1362 * @see #getEnableSessionCreation() 1363 */ setEnableSessionCreation(boolean flag)1364 public abstract void setEnableSessionCreation(boolean flag); 1365 1366 1367 /** 1368 * Returns true if new SSL sessions may be established by this socket. 1369 * 1370 * @return true indicates that sessions may be created; this 1371 * is the default. false indicates that an existing session 1372 * must be resumed 1373 * @see #setEnableSessionCreation(boolean) 1374 */ getEnableSessionCreation()1375 public abstract boolean getEnableSessionCreation(); 1376 1377 /** 1378 * Returns the SSLParameters in effect for this SSLSocket. 1379 * The ciphersuites and protocols of the returned SSLParameters 1380 * are always non-null. 1381 * 1382 * @return the SSLParameters in effect for this SSLSocket. 1383 * @since 1.6 1384 */ getSSLParameters()1385 public SSLParameters getSSLParameters() { 1386 SSLParameters params = new SSLParameters(); 1387 params.setCipherSuites(getEnabledCipherSuites()); 1388 params.setProtocols(getEnabledProtocols()); 1389 if (getNeedClientAuth()) { 1390 params.setNeedClientAuth(true); 1391 } else if (getWantClientAuth()) { 1392 params.setWantClientAuth(true); 1393 } 1394 return params; 1395 } 1396 1397 /** 1398 * Applies SSLParameters to this socket. 1399 * 1400 * <p>This means: 1401 * <ul> 1402 * <li>If {@code params.getCipherSuites()} is non-null, 1403 * {@code setEnabledCipherSuites()} is called with that value.</li> 1404 * <li>If {@code params.getProtocols()} is non-null, 1405 * {@code setEnabledProtocols()} is called with that value.</li> 1406 * <li>If {@code params.getNeedClientAuth()} or 1407 * {@code params.getWantClientAuth()} return {@code true}, 1408 * {@code setNeedClientAuth(true)} and 1409 * {@code setWantClientAuth(true)} are called, respectively; 1410 * otherwise {@code setWantClientAuth(false)} is called.</li> 1411 * <li>If {@code params.getServerNames()} is non-null, the socket will 1412 * configure its server names with that value.</li> 1413 * <li>If {@code params.getSNIMatchers()} is non-null, the socket will 1414 * configure its SNI matchers with that value.</li> 1415 * </ul> 1416 * 1417 * @param params the parameters 1418 * @throws IllegalArgumentException if the setEnabledCipherSuites() or 1419 * the setEnabledProtocols() call fails 1420 * @since 1.6 1421 */ setSSLParameters(SSLParameters params)1422 public void setSSLParameters(SSLParameters params) { 1423 String[] s; 1424 s = params.getCipherSuites(); 1425 if (s != null) { 1426 setEnabledCipherSuites(s); 1427 } 1428 s = params.getProtocols(); 1429 if (s != null) { 1430 setEnabledProtocols(s); 1431 } 1432 if (params.getNeedClientAuth()) { 1433 setNeedClientAuth(true); 1434 } else if (params.getWantClientAuth()) { 1435 setWantClientAuth(true); 1436 } else { 1437 setWantClientAuth(false); 1438 } 1439 } 1440 1441 // BEGIN Android-added: Add ALPN-related methods from OpenJDK 9. 1442 // Also removed references to DTLS in documentation; Android doesn't support DTLS. 1443 /** 1444 * Returns the most recent application protocol value negotiated for this 1445 * connection. 1446 * <p> 1447 * If supported by the underlying SSL/TLS implementation, 1448 * application name negotiation mechanisms such as <a 1449 * href="http://www.ietf.org/rfc/rfc7301.txt"> RFC 7301 </a>, the 1450 * Application-Layer Protocol Negotiation (ALPN), can negotiate 1451 * application-level values between peers. 1452 * <p> 1453 * @implSpec 1454 * The implementation in this class throws 1455 * {@code UnsupportedOperationException} and performs no other action. 1456 * 1457 * @return null if it has not yet been determined if application 1458 * protocols might be used for this connection, an empty 1459 * {@code String} if application protocols values will not 1460 * be used, or a non-empty application protocol {@code String} 1461 * if a value was successfully negotiated. 1462 * @throws UnsupportedOperationException if the underlying provider 1463 * does not implement the operation. 1464 * @since 9 1465 */ getApplicationProtocol()1466 public String getApplicationProtocol() { 1467 throw new UnsupportedOperationException(); 1468 } 1469 1470 /** 1471 * Returns the application protocol value negotiated on a SSL/TLS 1472 * handshake currently in progress. 1473 * <p> 1474 * Like {@link #getHandshakeSession()}, 1475 * a connection may be in the middle of a handshake. The 1476 * application protocol may or may not yet be available. 1477 * <p> 1478 * @implSpec 1479 * The implementation in this class throws 1480 * {@code UnsupportedOperationException} and performs no other action. 1481 * 1482 * @return null if it has not yet been determined if application 1483 * protocols might be used for this handshake, an empty 1484 * {@code String} if application protocols values will not 1485 * be used, or a non-empty application protocol {@code String} 1486 * if a value was successfully negotiated. 1487 * @throws UnsupportedOperationException if the underlying provider 1488 * does not implement the operation. 1489 * @since 9 1490 */ getHandshakeApplicationProtocol()1491 public String getHandshakeApplicationProtocol() { 1492 throw new UnsupportedOperationException(); 1493 } 1494 1495 1496 /** 1497 * Registers a callback function that selects an application protocol 1498 * value for a SSL/TLS handshake. 1499 * The function overrides any values supplied using 1500 * {@link SSLParameters#setApplicationProtocols 1501 * SSLParameters.setApplicationProtocols} and it supports the following 1502 * type parameters: 1503 * <blockquote> 1504 * <dl> 1505 * <dt> {@code SSLSocket} 1506 * <dd> The function's first argument allows the current {@code SSLSocket} 1507 * to be inspected, including the handshake session and configuration 1508 * settings. 1509 * <dt> {@code List<String>} 1510 * <dd> The function's second argument lists the application protocol names 1511 * advertised by the TLS peer. 1512 * <dt> {@code String} 1513 * <dd> The function's result is an application protocol name, or null to 1514 * indicate that none of the advertised names are acceptable. 1515 * If the return value is an empty {@code String} then application 1516 * protocol indications will not be used. 1517 * If the return value is null (no value chosen) or is a value that 1518 * was not advertised by the peer, the underlying protocol will 1519 * determine what action to take. (For example, ALPN will send a 1520 * "no_application_protocol" alert and terminate the connection.) 1521 * </dl> 1522 * </blockquote> 1523 * 1524 * For example, the following call registers a callback function that 1525 * examines the TLS handshake parameters and selects an application protocol 1526 * name: 1527 * <pre>{@code 1528 * serverSocket.setHandshakeApplicationProtocolSelector( 1529 * (serverSocket, clientProtocols) -> { 1530 * SSLSession session = serverSocket.getHandshakeSession(); 1531 * return chooseApplicationProtocol( 1532 * serverSocket, 1533 * clientProtocols, 1534 * session.getProtocol(), 1535 * session.getCipherSuite()); 1536 * }); 1537 * }</pre> 1538 * 1539 * @apiNote 1540 * This method should be called by TLS server applications before the TLS 1541 * handshake begins. Also, this {@code SSLSocket} should be configured with 1542 * parameters that are compatible with the application protocol selected by 1543 * the callback function. For example, enabling a poor choice of cipher 1544 * suites could result in no suitable application protocol. 1545 * See {@link SSLParameters}. 1546 * 1547 * @implSpec 1548 * The implementation in this class throws 1549 * {@code UnsupportedOperationException} and performs no other action. 1550 * 1551 * @param selector the callback function, or null to de-register. 1552 * @throws UnsupportedOperationException if the underlying provider 1553 * does not implement the operation. 1554 * @since 9 1555 */ setHandshakeApplicationProtocolSelector( BiFunction<SSLSocket, List<String>, String> selector)1556 public void setHandshakeApplicationProtocolSelector( 1557 BiFunction<SSLSocket, List<String>, String> selector) { 1558 throw new UnsupportedOperationException(); 1559 } 1560 1561 /** 1562 * Retrieves the callback function that selects an application protocol 1563 * value during a SSL/TLS handshake. 1564 * See {@link #setHandshakeApplicationProtocolSelector 1565 * setHandshakeApplicationProtocolSelector} 1566 * for the function's type parameters. 1567 * 1568 * @implSpec 1569 * The implementation in this class throws 1570 * {@code UnsupportedOperationException} and performs no other action. 1571 * 1572 * @return the callback function, or null if none has been set. 1573 * @throws UnsupportedOperationException if the underlying provider 1574 * does not implement the operation. 1575 * @since 9 1576 */ 1577 public BiFunction<SSLSocket, List<String>, String> getHandshakeApplicationProtocolSelector()1578 getHandshakeApplicationProtocolSelector() { 1579 throw new UnsupportedOperationException(); 1580 } 1581 // END Android-added: Add ALPN-related methods from OpenJDK 9. 1582 1583 // Android-added: Make toString explicit that this is an SSLSocket (http://b/6602228) 1584 @Override toString()1585 public String toString() { 1586 return "SSL" + super.toString(); 1587 } 1588 } 1589