1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package javax.net.ssl; 19 20 import java.io.IOException; 21 import java.net.InetAddress; 22 import java.net.Socket; 23 import java.net.UnknownHostException; 24 25 /** 26 * The extension of {@code Socket} providing secure protocols like SSL (Secure 27 * Sockets Layer) or TLS (Transport Layer Security). 28 * 29 * <h3>Default configuration</h3> 30 * <p>{@code SSLSocket} instances obtained from default {@link SSLSocketFactory}, 31 * {@link SSLServerSocketFactory}, and {@link SSLContext} are configured as follows: 32 * 33 * <style type="text/css"> 34 * tr.deprecated { 35 * background-color: #ccc; 36 * color: #999; 37 * font-style: italic; 38 * } 39 * </style> 40 * 41 * <h4>Protocols</h4> 42 * 43 * <p>Client socket: 44 * <table> 45 * <thead> 46 * <tr> 47 * <th>Protocol</th> 48 * <th>Supported (API Levels)</th> 49 * <th>Enabled by default (API Levels)</th> 50 * </tr> 51 * </thead> 52 * <tbody> 53 * <tr> 54 * <td>SSLv3</td> 55 * <td>1+</td> 56 * <td>1+</td> 57 * </tr> 58 * <tr> 59 * <td>TLSv1</td> 60 * <td>1+</td> 61 * <td>1+</td> 62 * </tr> 63 * <tr> 64 * <td>TLSv1.1</td> 65 * <td>16+</td> 66 * <td>20+</td> 67 * </tr> 68 * <tr> 69 * <td>TLSv1.2</td> 70 * <td>16+</td> 71 * <td>20+</td> 72 * </tr> 73 * </tbody> 74 * </table> 75 * 76 * <p>Server socket: 77 * <table> 78 * <thead> 79 * <tr> 80 * <th>Protocol</th> 81 * <th>Supported (API Levels)</th> 82 * <th>Enabled by default (API Levels)</th> 83 * </tr> 84 * </thead> 85 * <tbody> 86 * <tr> 87 * <td>SSLv3</td> 88 * <td>1+</td> 89 * <td>1+</td> 90 * </tr> 91 * <tr> 92 * <td>TLSv1</td> 93 * <td>1+</td> 94 * <td>1+</td> 95 * </tr> 96 * <tr> 97 * <td>TLSv1.1</td> 98 * <td>16+</td> 99 * <td>16+</td> 100 * </tr> 101 * <tr> 102 * <td>TLSv1.2</td> 103 * <td>16+</td> 104 * <td>16+</td> 105 * </tr> 106 * </tbody> 107 * </table> 108 * 109 * <h4>Cipher suites</h4> 110 * 111 * <p>Methods that operate with cipher suite names (for example, 112 * {@link #getSupportedCipherSuites() getSupportedCipherSuites}, 113 * {@link #setEnabledCipherSuites(String[]) setEnabledCipherSuites}) have used 114 * standard names for cipher suites since API Level 9, as listed in the table 115 * below. Prior to API Level 9, non-standard (OpenSSL) names had been used (see 116 * the table following this table). 117 * <table> 118 * <thead> 119 * <tr> 120 * <th>Cipher suite</th> 121 * <th>Supported (API Levels)</th> 122 * <th>Enabled by default (API Levels)</th> 123 * </tr> 124 * </thead> 125 * <tbody> 126 * <tr class="deprecated"> 127 * <td>SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA</td> 128 * <td>9–22</td> 129 * <td>9–19</td> 130 * </tr> 131 * <tr class="deprecated"> 132 * <td>SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA</td> 133 * <td>9–22</td> 134 * <td>9–19</td> 135 * </tr> 136 * <tr class="deprecated"> 137 * <td>SSL_DHE_DSS_WITH_DES_CBC_SHA</td> 138 * <td>9–22</td> 139 * <td>9–19</td> 140 * </tr> 141 * <tr class="deprecated"> 142 * <td>SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA</td> 143 * <td>9–22</td> 144 * <td>9–19</td> 145 * </tr> 146 * <tr class="deprecated"> 147 * <td>SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA</td> 148 * <td>9–22</td> 149 * <td>9–19</td> 150 * </tr> 151 * <tr class="deprecated"> 152 * <td>SSL_DHE_RSA_WITH_DES_CBC_SHA</td> 153 * <td>9–22</td> 154 * <td>9–19</td> 155 * </tr> 156 * <tr class="deprecated"> 157 * <td>SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA</td> 158 * <td>9–22</td> 159 * <td></td> 160 * </tr> 161 * <tr class="deprecated"> 162 * <td>SSL_DH_anon_EXPORT_WITH_RC4_40_MD5</td> 163 * <td>9–22</td> 164 * <td></td> 165 * </tr> 166 * <tr class="deprecated"> 167 * <td>SSL_DH_anon_WITH_3DES_EDE_CBC_SHA</td> 168 * <td>9–22</td> 169 * <td></td> 170 * </tr> 171 * <tr class="deprecated"> 172 * <td>SSL_DH_anon_WITH_DES_CBC_SHA</td> 173 * <td>9–22</td> 174 * <td></td> 175 * </tr> 176 * <tr class="deprecated"> 177 * <td>SSL_DH_anon_WITH_RC4_128_MD5</td> 178 * <td>9–22</td> 179 * <td></td> 180 * </tr> 181 * <tr class="deprecated"> 182 * <td>SSL_RSA_EXPORT_WITH_DES40_CBC_SHA</td> 183 * <td>9–22</td> 184 * <td>9–19</td> 185 * </tr> 186 * <tr class="deprecated"> 187 * <td>SSL_RSA_EXPORT_WITH_RC4_40_MD5</td> 188 * <td>9–22</td> 189 * <td>9–19</td> 190 * </tr> 191 * <tr> 192 * <td>SSL_RSA_WITH_3DES_EDE_CBC_SHA</td> 193 * <td>9+</td> 194 * <td>9–19</td> 195 * </tr> 196 * <tr class="deprecated"> 197 * <td>SSL_RSA_WITH_DES_CBC_SHA</td> 198 * <td>9–22</td> 199 * <td>9–19</td> 200 * </tr> 201 * <tr class="deprecated"> 202 * <td>SSL_RSA_WITH_NULL_MD5</td> 203 * <td>9–22</td> 204 * <td></td> 205 * </tr> 206 * <tr class="deprecated"> 207 * <td>SSL_RSA_WITH_NULL_SHA</td> 208 * <td>9–22</td> 209 * <td></td> 210 * </tr> 211 * <tr> 212 * <td>SSL_RSA_WITH_RC4_128_MD5</td> 213 * <td>9+</td> 214 * <td>9–19</td> 215 * </tr> 216 * <tr> 217 * <td>SSL_RSA_WITH_RC4_128_SHA</td> 218 * <td>9+</td> 219 * <td>9+</td> 220 * </tr> 221 * <tr class="deprecated"> 222 * <td>TLS_DHE_DSS_WITH_AES_128_CBC_SHA</td> 223 * <td>9–22</td> 224 * <td>9–22</td> 225 * </tr> 226 * <tr class="deprecated"> 227 * <td>TLS_DHE_DSS_WITH_AES_128_CBC_SHA256</td> 228 * <td>20–22</td> 229 * <td></td> 230 * </tr> 231 * <tr class="deprecated"> 232 * <td>TLS_DHE_DSS_WITH_AES_128_GCM_SHA256</td> 233 * <td>20–22</td> 234 * <td></td> 235 * </tr> 236 * <tr class="deprecated"> 237 * <td>TLS_DHE_DSS_WITH_AES_256_CBC_SHA</td> 238 * <td>9–22</td> 239 * <td>11–22</td> 240 * </tr> 241 * <tr class="deprecated"> 242 * <td>TLS_DHE_DSS_WITH_AES_256_CBC_SHA256</td> 243 * <td>20–22</td> 244 * <td></td> 245 * </tr> 246 * <tr class="deprecated"> 247 * <td>TLS_DHE_DSS_WITH_AES_256_GCM_SHA384</td> 248 * <td>20–22</td> 249 * <td></td> 250 * </tr> 251 * <tr> 252 * <td>TLS_DHE_RSA_WITH_AES_128_CBC_SHA</td> 253 * <td>9+</td> 254 * <td>9+</td> 255 * </tr> 256 * <tr> 257 * <td>TLS_DHE_RSA_WITH_AES_128_CBC_SHA256</td> 258 * <td>20+</td> 259 * <td></td> 260 * </tr> 261 * <tr> 262 * <td>TLS_DHE_RSA_WITH_AES_128_GCM_SHA256</td> 263 * <td>20+</td> 264 * <td>20+</td> 265 * </tr> 266 * <tr> 267 * <td>TLS_DHE_RSA_WITH_AES_256_CBC_SHA</td> 268 * <td>9+</td> 269 * <td>11+</td> 270 * </tr> 271 * <tr> 272 * <td>TLS_DHE_RSA_WITH_AES_256_CBC_SHA256</td> 273 * <td>20+</td> 274 * <td></td> 275 * </tr> 276 * <tr> 277 * <td>TLS_DHE_RSA_WITH_AES_256_GCM_SHA384</td> 278 * <td>20+</td> 279 * <td>20+</td> 280 * </tr> 281 * <tr class="deprecated"> 282 * <td>TLS_DH_anon_WITH_AES_128_CBC_SHA</td> 283 * <td>9–22</td> 284 * <td></td> 285 * </tr> 286 * <tr class="deprecated"> 287 * <td>TLS_DH_anon_WITH_AES_128_CBC_SHA256</td> 288 * <td>20–22</td> 289 * <td></td> 290 * </tr> 291 * <tr class="deprecated"> 292 * <td>TLS_DH_anon_WITH_AES_128_GCM_SHA256</td> 293 * <td>20–22</td> 294 * <td></td> 295 * </tr> 296 * <tr class="deprecated"> 297 * <td>TLS_DH_anon_WITH_AES_256_CBC_SHA</td> 298 * <td>9–22</td> 299 * <td></td> 300 * </tr> 301 * <tr class="deprecated"> 302 * <td>TLS_DH_anon_WITH_AES_256_CBC_SHA256</td> 303 * <td>20–22</td> 304 * <td></td> 305 * </tr> 306 * <tr class="deprecated"> 307 * <td>TLS_DH_anon_WITH_AES_256_GCM_SHA384</td> 308 * <td>20–22</td> 309 * <td></td> 310 * </tr> 311 * <tr class="deprecated"> 312 * <td>TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA</td> 313 * <td>11–22</td> 314 * <td>11–19</td> 315 * </tr> 316 * <tr> 317 * <td>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</td> 318 * <td>11+</td> 319 * <td>11+</td> 320 * </tr> 321 * <tr> 322 * <td>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256</td> 323 * <td>20+</td> 324 * <td></td> 325 * </tr> 326 * <tr> 327 * <td>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</td> 328 * <td>20+</td> 329 * <td>20+</td> 330 * </tr> 331 * <tr> 332 * <td>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</td> 333 * <td>11+</td> 334 * <td>11+</td> 335 * </tr> 336 * <tr> 337 * <td>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384</td> 338 * <td>20+</td> 339 * <td></td> 340 * </tr> 341 * <tr> 342 * <td>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</td> 343 * <td>20+</td> 344 * <td>20+</td> 345 * </tr> 346 * <tr class="deprecated"> 347 * <td>TLS_ECDHE_ECDSA_WITH_NULL_SHA</td> 348 * <td>11–22</td> 349 * <td></td> 350 * </tr> 351 * <tr> 352 * <td>TLS_ECDHE_ECDSA_WITH_RC4_128_SHA</td> 353 * <td>11+</td> 354 * <td>11+</td> 355 * </tr> 356 * <tr> 357 * <td>TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA</td> 358 * <td>21+</td> 359 * <td>21+</td> 360 * </tr> 361 * <tr> 362 * <td>TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA</td> 363 * <td>21+</td> 364 * <td>21+</td> 365 * </tr> 366 * <tr class="deprecated"> 367 * <td>TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA</td> 368 * <td>11–22</td> 369 * <td>11–19</td> 370 * </tr> 371 * <tr> 372 * <td>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</td> 373 * <td>11+</td> 374 * <td>11+</td> 375 * </tr> 376 * <tr> 377 * <td>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</td> 378 * <td>20+</td> 379 * <td></td> 380 * </tr> 381 * <tr> 382 * <td>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</td> 383 * <td>20+</td> 384 * <td>20+</td> 385 * </tr> 386 * <tr> 387 * <td>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</td> 388 * <td>11+</td> 389 * <td>11+</td> 390 * </tr> 391 * <tr> 392 * <td>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384</td> 393 * <td>20+</td> 394 * <td></td> 395 * </tr> 396 * <tr> 397 * <td>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</td> 398 * <td>20+</td> 399 * <td>20+</td> 400 * </tr> 401 * <tr class="deprecated"> 402 * <td>TLS_ECDHE_RSA_WITH_NULL_SHA</td> 403 * <td>11–22</td> 404 * <td></td> 405 * </tr> 406 * <tr> 407 * <td>TLS_ECDHE_RSA_WITH_RC4_128_SHA</td> 408 * <td>11+</td> 409 * <td>11+</td> 410 * </tr> 411 * <tr class="deprecated"> 412 * <td>TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA</td> 413 * <td>11–22</td> 414 * <td>11–19</td> 415 * </tr> 416 * <tr class="deprecated"> 417 * <td>TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA</td> 418 * <td>11–22</td> 419 * <td>11–19</td> 420 * </tr> 421 * <tr class="deprecated"> 422 * <td>TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256</td> 423 * <td>20–22</td> 424 * <td></td> 425 * </tr> 426 * <tr class="deprecated"> 427 * <td>TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256</td> 428 * <td>20–22</td> 429 * <td></td> 430 * </tr> 431 * <tr class="deprecated"> 432 * <td>TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA</td> 433 * <td>11–22</td> 434 * <td>11–19</td> 435 * </tr> 436 * <tr class="deprecated"> 437 * <td>TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384</td> 438 * <td>20–22</td> 439 * <td></td> 440 * </tr> 441 * <tr class="deprecated"> 442 * <td>TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384</td> 443 * <td>20–22</td> 444 * <td></td> 445 * </tr> 446 * <tr class="deprecated"> 447 * <td>TLS_ECDH_ECDSA_WITH_NULL_SHA</td> 448 * <td>11–22</td> 449 * <td></td> 450 * </tr> 451 * <tr class="deprecated"> 452 * <td>TLS_ECDH_ECDSA_WITH_RC4_128_SHA</td> 453 * <td>11–22</td> 454 * <td>11–19</td> 455 * </tr> 456 * <tr class="deprecated"> 457 * <td>TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA</td> 458 * <td>11–22</td> 459 * <td>11–19</td> 460 * </tr> 461 * <tr class="deprecated"> 462 * <td>TLS_ECDH_RSA_WITH_AES_128_CBC_SHA</td> 463 * <td>11–22</td> 464 * <td>11–19</td> 465 * </tr> 466 * <tr class="deprecated"> 467 * <td>TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256</td> 468 * <td>20–22</td> 469 * <td></td> 470 * </tr> 471 * <tr class="deprecated"> 472 * <td>TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256</td> 473 * <td>20–22</td> 474 * <td></td> 475 * </tr> 476 * <tr class="deprecated"> 477 * <td>TLS_ECDH_RSA_WITH_AES_256_CBC_SHA</td> 478 * <td>11–22</td> 479 * <td>11–19</td> 480 * </tr> 481 * <tr class="deprecated"> 482 * <td>TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384</td> 483 * <td>20–22</td> 484 * <td></td> 485 * </tr> 486 * <tr class="deprecated"> 487 * <td>TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384</td> 488 * <td>20–22</td> 489 * <td></td> 490 * </tr> 491 * <tr class="deprecated"> 492 * <td>TLS_ECDH_RSA_WITH_NULL_SHA</td> 493 * <td>11–22</td> 494 * <td></td> 495 * </tr> 496 * <tr class="deprecated"> 497 * <td>TLS_ECDH_RSA_WITH_RC4_128_SHA</td> 498 * <td>11–22</td> 499 * <td>11–19</td> 500 * </tr> 501 * <tr class="deprecated"> 502 * <td>TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA</td> 503 * <td>11–22</td> 504 * <td></td> 505 * </tr> 506 * <tr class="deprecated"> 507 * <td>TLS_ECDH_anon_WITH_AES_128_CBC_SHA</td> 508 * <td>11–22</td> 509 * <td></td> 510 * </tr> 511 * <tr class="deprecated"> 512 * <td>TLS_ECDH_anon_WITH_AES_256_CBC_SHA</td> 513 * <td>11–22</td> 514 * <td></td> 515 * </tr> 516 * <tr class="deprecated"> 517 * <td>TLS_ECDH_anon_WITH_NULL_SHA</td> 518 * <td>11–22</td> 519 * <td></td> 520 * </tr> 521 * <tr class="deprecated"> 522 * <td>TLS_ECDH_anon_WITH_RC4_128_SHA</td> 523 * <td>11–22</td> 524 * <td></td> 525 * </tr> 526 * <tr> 527 * <td>TLS_EMPTY_RENEGOTIATION_INFO_SCSV</td> 528 * <td>11+</td> 529 * <td>11+</td> 530 * </tr> 531 * <tr> 532 * <td>TLS_FALLBACK_SCSV</td> 533 * <td>21+</td> 534 * <td></td> 535 * </tr> 536 * <tr class="deprecated"> 537 * <td>TLS_PSK_WITH_3DES_EDE_CBC_SHA</td> 538 * <td>21–22</td> 539 * <td></td> 540 * </tr> 541 * <tr> 542 * <td>TLS_PSK_WITH_AES_128_CBC_SHA</td> 543 * <td>21+</td> 544 * <td>21+</td> 545 * </tr> 546 * <tr> 547 * <td>TLS_PSK_WITH_AES_256_CBC_SHA</td> 548 * <td>21+</td> 549 * <td>21+</td> 550 * </tr> 551 * <tr> 552 * <td>TLS_PSK_WITH_RC4_128_SHA</td> 553 * <td>21+</td> 554 * <td></td> 555 * </tr> 556 * <tr> 557 * <td>TLS_RSA_WITH_AES_128_CBC_SHA</td> 558 * <td>9+</td> 559 * <td>9+</td> 560 * </tr> 561 * <tr> 562 * <td>TLS_RSA_WITH_AES_128_CBC_SHA256</td> 563 * <td>20+</td> 564 * <td></td> 565 * </tr> 566 * <tr> 567 * <td>TLS_RSA_WITH_AES_128_GCM_SHA256</td> 568 * <td>20+</td> 569 * <td>20+</td> 570 * </tr> 571 * <tr> 572 * <td>TLS_RSA_WITH_AES_256_CBC_SHA</td> 573 * <td>9+</td> 574 * <td>11+</td> 575 * </tr> 576 * <tr> 577 * <td>TLS_RSA_WITH_AES_256_CBC_SHA256</td> 578 * <td>20+</td> 579 * <td></td> 580 * </tr> 581 * <tr> 582 * <td>TLS_RSA_WITH_AES_256_GCM_SHA384</td> 583 * <td>20+</td> 584 * <td>20+</td> 585 * </tr> 586 * <tr class="deprecated"> 587 * <td>TLS_RSA_WITH_NULL_SHA256</td> 588 * <td>20–22</td> 589 * <td></td> 590 * </tr> 591 * </tbody> 592 * </table> 593 * 594 * <p><em>NOTE</em>: PSK cipher suites are enabled by default only if the {@code SSLContext} through 595 * which the socket was created has been initialized with a {@code PSKKeyManager}. 596 * 597 * <p>API Levels 1 to 8 use OpenSSL names for cipher suites. The table below 598 * lists these OpenSSL names and their corresponding standard names used in API 599 * Levels 9 and newer. 600 * <table> 601 * <thead> 602 * <tr> 603 * <th>OpenSSL cipher suite</th> 604 * <th>Standard cipher suite</th> 605 * <th>Supported (API Levels)</th> 606 * <th>Enabled by default (API Levels)</th> 607 * </tr> 608 * </thead> 609 * 610 * <tbody> 611 * <tr> 612 * <td>AES128-SHA</td> 613 * <td>TLS_RSA_WITH_AES_128_CBC_SHA</td> 614 * <td>1+</td> 615 * <td>1+</td> 616 * </tr> 617 * <tr> 618 * <td>AES256-SHA</td> 619 * <td>TLS_RSA_WITH_AES_256_CBC_SHA</td> 620 * <td>1+</td> 621 * <td>1–8, 11+</td> 622 * </tr> 623 * <tr> 624 * <td>DES-CBC-MD5</td> 625 * <td>SSL_CK_DES_64_CBC_WITH_MD5</td> 626 * <td>1–8</td> 627 * <td>1–8</td> 628 * </tr> 629 * <tr class="deprecated"> 630 * <td>DES-CBC-SHA</td> 631 * <td>SSL_RSA_WITH_DES_CBC_SHA</td> 632 * <td>1–22</td> 633 * <td>1–19</td> 634 * </tr> 635 * <tr> 636 * <td>DES-CBC3-MD5</td> 637 * <td>SSL_CK_DES_192_EDE3_CBC_WITH_MD5</td> 638 * <td>1–8</td> 639 * <td>1–8</td> 640 * </tr> 641 * <tr> 642 * <td>DES-CBC3-SHA</td> 643 * <td>SSL_RSA_WITH_3DES_EDE_CBC_SHA</td> 644 * <td>1+</td> 645 * <td>1–19</td> 646 * </tr> 647 * <tr class="deprecated"> 648 * <td>DHE-DSS-AES128-SHA</td> 649 * <td>TLS_DHE_DSS_WITH_AES_128_CBC_SHA</td> 650 * <td>1–22</td> 651 * <td>1–22</td> 652 * </tr> 653 * <tr class="deprecated"> 654 * <td>DHE-DSS-AES256-SHA</td> 655 * <td>TLS_DHE_DSS_WITH_AES_256_CBC_SHA</td> 656 * <td>1–22</td> 657 * <td>1–8, 11–22</td> 658 * </tr> 659 * <tr> 660 * <td>DHE-RSA-AES128-SHA</td> 661 * <td>TLS_DHE_RSA_WITH_AES_128_CBC_SHA</td> 662 * <td>1+</td> 663 * <td>1+</td> 664 * </tr> 665 * <tr> 666 * <td>DHE-RSA-AES256-SHA</td> 667 * <td>TLS_DHE_RSA_WITH_AES_256_CBC_SHA</td> 668 * <td>1+</td> 669 * <td>1–8, 11+</td> 670 * </tr> 671 * <tr class="deprecated"> 672 * <td>EDH-DSS-DES-CBC-SHA</td> 673 * <td>SSL_DHE_DSS_WITH_DES_CBC_SHA</td> 674 * <td>1–22</td> 675 * <td>1–19</td> 676 * </tr> 677 * <tr class="deprecated"> 678 * <td>EDH-DSS-DES-CBC3-SHA</td> 679 * <td>SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA</td> 680 * <td>1–22</td> 681 * <td>1–19</td> 682 * </tr> 683 * <tr class="deprecated"> 684 * <td>EDH-RSA-DES-CBC-SHA</td> 685 * <td>SSL_DHE_RSA_WITH_DES_CBC_SHA</td> 686 * <td>1–22</td> 687 * <td>1–19</td> 688 * </tr> 689 * <tr class="deprecated"> 690 * <td>EDH-RSA-DES-CBC3-SHA</td> 691 * <td>SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA</td> 692 * <td>1–22</td> 693 * <td>1–19</td> 694 * </tr> 695 * <tr class="deprecated"> 696 * <td>EXP-DES-CBC-SHA</td> 697 * <td>SSL_RSA_EXPORT_WITH_DES40_CBC_SHA</td> 698 * <td>1–22</td> 699 * <td>1–19</td> 700 * </tr> 701 * <tr class="deprecated"> 702 * <td>EXP-EDH-DSS-DES-CBC-SHA</td> 703 * <td>SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA</td> 704 * <td>1–22</td> 705 * <td>1–19</td> 706 * </tr> 707 * <tr class="deprecated"> 708 * <td>EXP-EDH-RSA-DES-CBC-SHA</td> 709 * <td>SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA</td> 710 * <td>1–22</td> 711 * <td>1–19</td> 712 * </tr> 713 * <tr> 714 * <td>EXP-RC2-CBC-MD5</td> 715 * <td>SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5</td> 716 * <td>1–8</td> 717 * <td>1–8</td> 718 * </tr> 719 * <tr class="deprecated"> 720 * <td>EXP-RC4-MD5</td> 721 * <td>SSL_RSA_EXPORT_WITH_RC4_40_MD5</td> 722 * <td>1–22</td> 723 * <td>1–19</td> 724 * </tr> 725 * <tr> 726 * <td>RC2-CBC-MD5</td> 727 * <td>SSL_CK_RC2_128_CBC_WITH_MD5</td> 728 * <td>1–8</td> 729 * <td>1–8</td> 730 * </tr> 731 * <tr> 732 * <td>RC4-MD5</td> 733 * <td>SSL_RSA_WITH_RC4_128_MD5</td> 734 * <td>1+</td> 735 * <td>1–19</td> 736 * </tr> 737 * <tr> 738 * <td>RC4-SHA</td> 739 * <td>SSL_RSA_WITH_RC4_128_SHA</td> 740 * <td>1+</td> 741 * <td>1+</td> 742 * </tr> 743 * </tbody> 744 * </table> 745 */ 746 public abstract class SSLSocket extends Socket { 747 748 /** 749 * Only to be used by subclasses. 750 * <p> 751 * Creates a TCP socket. 752 */ 753 protected SSLSocket() { 754 } 755 756 /** 757 * Only to be used by subclasses. 758 * <p> 759 * Creates a TCP socket connection to the specified host at the specified 760 * port. 761 * 762 * @param host 763 * the host name to connect to. 764 * @param port 765 * the port number to connect to. 766 * @throws IOException 767 * if creating the socket fails. 768 * @throws UnknownHostException 769 * if the specified host is not known. 770 */ 771 protected SSLSocket(String host, int port) throws IOException, UnknownHostException { 772 super(host, port); 773 } 774 775 /** 776 * Only to be used by subclasses. 777 * <p> 778 * Creates a TCP socket connection to the specified address at the specified 779 * port. 780 * 781 * @param address 782 * the address to connect to. 783 * @param port 784 * the port number to connect to. 785 * @throws IOException 786 * if creating the socket fails. 787 */ 788 protected SSLSocket(InetAddress address, int port) throws IOException { 789 super(address, port); 790 } 791 792 /** 793 * Only to be used by subclasses. 794 * <p> 795 * Creates a TCP socket connection to the specified host at the specified 796 * port with the client side bound to the specified address and port. 797 * 798 * @param host 799 * the host name to connect to. 800 * @param port 801 * the port number to connect to. 802 * @param clientAddress 803 * the client address to bind to 804 * @param clientPort 805 * the client port number to bind to. 806 * @throws IOException 807 * if creating the socket fails. 808 * @throws UnknownHostException 809 * if the specified host is not known. 810 */ 811 protected SSLSocket(String host, int port, InetAddress clientAddress, int clientPort) 812 throws IOException, UnknownHostException { 813 super(host, port, clientAddress, clientPort); 814 } 815 816 /** 817 * Only to be used by subclasses. 818 * <p> 819 * Creates a TCP socket connection to the specified address at the specified 820 * port with the client side bound to the specified address and port. 821 * 822 * @param address 823 * the address to connect to. 824 * @param port 825 * the port number to connect to. 826 * @param clientAddress 827 * the client address to bind to. 828 * @param clientPort 829 * the client port number to bind to. 830 * @throws IOException 831 * if creating the socket fails. 832 */ 833 protected SSLSocket(InetAddress address, int port, InetAddress clientAddress, int clientPort) 834 throws IOException { 835 super(address, port, clientAddress, clientPort); 836 } 837 838 /** 839 * Unsupported for SSL because reading from an SSL socket may require 840 * writing to the network. 841 */ 842 @Override public void shutdownInput() throws IOException { 843 throw new UnsupportedOperationException(); 844 } 845 846 /** 847 * Unsupported for SSL because writing to an SSL socket may require reading 848 * from the network. 849 */ 850 @Override public void shutdownOutput() throws IOException { 851 throw new UnsupportedOperationException(); 852 } 853 854 /** 855 * Returns the names of the supported cipher suites. 856 */ 857 public abstract String[] getSupportedCipherSuites(); 858 859 /** 860 * Returns the names of the enabled cipher suites. 861 */ 862 public abstract String[] getEnabledCipherSuites(); 863 864 /** 865 * Sets the names of the cipher suites to be enabled. 866 * Only cipher suites returned by {@link #getSupportedCipherSuites()} are 867 * allowed. 868 * 869 * @param suites 870 * the names of the to be enabled cipher suites. 871 * @throws IllegalArgumentException 872 * if one of the cipher suite names is not supported. 873 */ 874 public abstract void setEnabledCipherSuites(String[] suites); 875 876 /** 877 * Returns the names of the supported protocols. 878 */ 879 public abstract String[] getSupportedProtocols(); 880 881 /** 882 * Returns the names of the enabled protocols. 883 */ 884 public abstract String[] getEnabledProtocols(); 885 886 /** 887 * Sets the names of the protocols to be enabled. Only 888 * protocols returned by {@link #getSupportedProtocols()} are allowed. 889 * 890 * @param protocols 891 * the names of the to be enabled protocols. 892 * @throws IllegalArgumentException 893 * if one of the protocols is not supported. 894 */ 895 public abstract void setEnabledProtocols(String[] protocols); 896 897 /** 898 * Returns the {@code SSLSession} for this connection. If necessary, a 899 * handshake will be initiated, in which case this method will block until the handshake 900 * has been established. If the handshake fails, an invalid session object 901 * will be returned. 902 * 903 * @return the session object. 904 */ 905 public abstract SSLSession getSession(); 906 907 /** 908 * Registers the specified listener to receive notification on completion of 909 * a handshake on this connection. 910 * 911 * @param listener the listener to register. 912 * @throws IllegalArgumentException if {@code listener} is {@code null}. 913 */ 914 public abstract void addHandshakeCompletedListener(HandshakeCompletedListener listener); 915 916 /** 917 * Removes the specified handshake completion listener. 918 * 919 * @param listener 920 * the listener to remove. 921 * @throws IllegalArgumentException 922 * if the specified listener is not registered or {@code null}. 923 */ 924 public abstract void removeHandshakeCompletedListener(HandshakeCompletedListener listener); 925 926 /** 927 * Starts a new SSL handshake on this connection. 928 * 929 * @throws IOException 930 * if an error occurs. 931 */ 932 public abstract void startHandshake() throws IOException; 933 934 /** 935 * Sets whether this connection should act in client mode when handshaking. 936 * 937 * @param mode 938 * {@code true} if this connection should act in client mode, 939 * {@code false} if not. 940 */ 941 public abstract void setUseClientMode(boolean mode); 942 943 /** 944 * Returns true if this connection will act in client mode when handshaking. 945 */ 946 public abstract boolean getUseClientMode(); 947 948 /** 949 * Sets whether the server should require client authentication. This 950 * does not apply to sockets in {@link #getUseClientMode() client mode}. 951 * Client authentication is one of the following: 952 * <ul> 953 * <li>authentication required</li> 954 * <li>authentication requested</li> 955 * <li>no authentication needed</li> 956 * </ul> 957 * This method overrides the setting of {@link #setWantClientAuth(boolean)}. 958 */ 959 public abstract void setNeedClientAuth(boolean need); 960 961 /** 962 * Sets whether the server should request client authentication. Unlike 963 * {@link #setNeedClientAuth} this won't stop the negotiation if the client 964 * doesn't authenticate. This does not apply to sockets in {@link 965 * #getUseClientMode() client mode}.The client authentication is one of: 966 * <ul> 967 * <li>authentication required</li> 968 * <li>authentication requested</li> 969 * <li>no authentication needed</li> 970 * </ul> 971 * This method overrides the setting of {@link #setNeedClientAuth(boolean)}. 972 */ 973 public abstract void setWantClientAuth(boolean want); 974 975 /** 976 * Returns true if the server socket should require client authentication. 977 * This does not apply to sockets in {@link #getUseClientMode() client 978 * mode}. 979 */ 980 public abstract boolean getNeedClientAuth(); 981 982 /** 983 * Returns true if the server should request client authentication. This 984 * does not apply to sockets in {@link #getUseClientMode() client mode}. 985 */ 986 public abstract boolean getWantClientAuth(); 987 988 /** 989 * Sets whether new SSL sessions may be created by this socket or if 990 * existing sessions must be reused. If {@code flag} is false and there are 991 * no sessions to resume, handshaking will fail. 992 * 993 * @param flag {@code true} if new sessions may be created. 994 */ 995 public abstract void setEnableSessionCreation(boolean flag); 996 997 /** 998 * Returns whether new SSL sessions may be created by this socket or if 999 * existing sessions must be reused. 1000 * 1001 * @return {@code true} if new sessions may be created, otherwise 1002 * {@code false}. 1003 */ 1004 public abstract boolean getEnableSessionCreation(); 1005 1006 /** 1007 * Returns a new SSLParameters based on this SSLSocket's current 1008 * cipher suites, protocols, and client authentication settings. 1009 * 1010 * @since 1.6 1011 */ 1012 public SSLParameters getSSLParameters() { 1013 SSLParameters p = new SSLParameters(); 1014 p.setCipherSuites(getEnabledCipherSuites()); 1015 p.setProtocols(getEnabledProtocols()); 1016 p.setNeedClientAuth(getNeedClientAuth()); 1017 p.setWantClientAuth(getWantClientAuth()); 1018 return p; 1019 } 1020 1021 /** 1022 * Sets various SSL handshake parameters based on the SSLParameter 1023 * argument. Specifically, sets the SSLSocket's enabled cipher 1024 * suites if the parameter's cipher suites are non-null. Similarly 1025 * sets the enabled protocols. If the parameters specify the want 1026 * or need for client authentication, those requirements are set 1027 * on the SSLSocket, otherwise both are set to false. 1028 * @since 1.6 1029 */ 1030 public void setSSLParameters(SSLParameters p) { 1031 String[] cipherSuites = p.getCipherSuites(); 1032 if (cipherSuites != null) { 1033 setEnabledCipherSuites(cipherSuites); 1034 } 1035 String[] protocols = p.getProtocols(); 1036 if (protocols != null) { 1037 setEnabledProtocols(protocols); 1038 } 1039 if (p.getNeedClientAuth()) { 1040 setNeedClientAuth(true); 1041 } else if (p.getWantClientAuth()) { 1042 setWantClientAuth(true); 1043 } else { 1044 setWantClientAuth(false); 1045 } 1046 } 1047 } 1048