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