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.nio.ByteBuffer; 21 22 /** 23 * The abstract implementation of secure communications using SSL, TLS, or other 24 * protocols. It includes the setup, handshake, and encrypt/decrypt 25 * functionality needed to create a secure connection. 26 * 27 * <h3>Default configuration</h3> 28 * <p>{@code SSLEngine} instances obtained from default {@link SSLContext} are configured as 29 * follows: 30 * 31 * <style type="text/css"> 32 * tr.deprecated { 33 * background-color: #ccc; 34 * color: #999; 35 * font-style: italic; 36 * } 37 * </style> 38 * 39 * <h4>Protocols</h4> 40 * <table> 41 * <thead> 42 * <tr> 43 * <th>Protocol</th> 44 * <th>Supported (API Levels)</th> 45 * <th>Enabled by default (API Levels)</th> 46 * </tr> 47 * </thead> 48 * <tbody> 49 * <tr> 50 * <td>SSLv3</td> 51 * <td>1+</td> 52 * <td>1+</td> 53 * </tr> 54 * <tr> 55 * <td>TLSv1</td> 56 * <td>1+</td> 57 * <td>1+</td> 58 * </tr> 59 * <tr> 60 * <td>TLSv1.1</td> 61 * <td>20+</td> 62 * <td>20+</td> 63 * </tr> 64 * <tr> 65 * <td>TLSv1.2</td> 66 * <td>20+</td> 67 * <td>20+</td> 68 * </tr> 69 * </tbody> 70 * </table> 71 * 72 * <h4>Cipher suites</h4> 73 * <table> 74 * <thead> 75 * <tr> 76 * <th>Cipher suite</th> 77 * <th>Supported (API Levels)</th> 78 * <th>Enabled by default (API Levels)</th> 79 * </tr> 80 * </thead> 81 * <tbody> 82 * <tr class="deprecated"> 83 * <td>SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA</td> 84 * <td>9–22</td> 85 * <td>9–19</td> 86 * </tr> 87 * <tr class="deprecated"> 88 * <td>SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA</td> 89 * <td>9–22</td> 90 * <td>9–19</td> 91 * </tr> 92 * <tr class="deprecated"> 93 * <td>SSL_DHE_DSS_WITH_DES_CBC_SHA</td> 94 * <td>9–22</td> 95 * <td>9–19</td> 96 * </tr> 97 * <tr class="deprecated"> 98 * <td>SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA</td> 99 * <td>9–22</td> 100 * <td>9–19</td> 101 * </tr> 102 * <tr class="deprecated"> 103 * <td>SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA</td> 104 * <td>9–22</td> 105 * <td>9–19</td> 106 * </tr> 107 * <tr class="deprecated"> 108 * <td>SSL_DHE_RSA_WITH_DES_CBC_SHA</td> 109 * <td>9–22</td> 110 * <td>9–19</td> 111 * </tr> 112 * <tr class="deprecated"> 113 * <td>SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA</td> 114 * <td>9–22</td> 115 * <td></td> 116 * </tr> 117 * <tr class="deprecated"> 118 * <td>SSL_DH_anon_EXPORT_WITH_RC4_40_MD5</td> 119 * <td>9–22</td> 120 * <td></td> 121 * </tr> 122 * <tr class="deprecated"> 123 * <td>SSL_DH_anon_WITH_3DES_EDE_CBC_SHA</td> 124 * <td>9–22</td> 125 * <td></td> 126 * </tr> 127 * <tr class="deprecated"> 128 * <td>SSL_DH_anon_WITH_DES_CBC_SHA</td> 129 * <td>9–22</td> 130 * <td></td> 131 * </tr> 132 * <tr class="deprecated"> 133 * <td>SSL_DH_anon_WITH_RC4_128_MD5</td> 134 * <td>9–22</td> 135 * <td></td> 136 * </tr> 137 * <tr class="deprecated"> 138 * <td>SSL_RSA_EXPORT_WITH_DES40_CBC_SHA</td> 139 * <td>9–22</td> 140 * <td>9–19</td> 141 * </tr> 142 * <tr class="deprecated"> 143 * <td>SSL_RSA_EXPORT_WITH_RC4_40_MD5</td> 144 * <td>9–22</td> 145 * <td>9–19</td> 146 * </tr> 147 * <tr> 148 * <td>SSL_RSA_WITH_3DES_EDE_CBC_SHA</td> 149 * <td>9+</td> 150 * <td>9–19</td> 151 * </tr> 152 * <tr class="deprecated"> 153 * <td>SSL_RSA_WITH_DES_CBC_SHA</td> 154 * <td>9–22</td> 155 * <td>9–19</td> 156 * </tr> 157 * <tr class="deprecated"> 158 * <td>SSL_RSA_WITH_NULL_MD5</td> 159 * <td>9–22</td> 160 * <td></td> 161 * </tr> 162 * <tr class="deprecated"> 163 * <td>SSL_RSA_WITH_NULL_SHA</td> 164 * <td>9–22</td> 165 * <td></td> 166 * </tr> 167 * <tr> 168 * <td>SSL_RSA_WITH_RC4_128_MD5</td> 169 * <td>9+</td> 170 * <td>9–19</td> 171 * </tr> 172 * <tr> 173 * <td>SSL_RSA_WITH_RC4_128_SHA</td> 174 * <td>9+</td> 175 * <td>9+</td> 176 * </tr> 177 * <tr class="deprecated"> 178 * <td>TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA</td> 179 * <td>1–8</td> 180 * <td>1–8</td> 181 * </tr> 182 * <tr class="deprecated"> 183 * <td>TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA</td> 184 * <td>1–8</td> 185 * <td>1–8</td> 186 * </tr> 187 * <tr class="deprecated"> 188 * <td>TLS_DHE_DSS_WITH_AES_128_CBC_SHA</td> 189 * <td>9–22</td> 190 * <td>9–22</td> 191 * </tr> 192 * <tr class="deprecated"> 193 * <td>TLS_DHE_DSS_WITH_AES_128_CBC_SHA256</td> 194 * <td>20–22</td> 195 * <td></td> 196 * </tr> 197 * <tr class="deprecated"> 198 * <td>TLS_DHE_DSS_WITH_AES_128_GCM_SHA256</td> 199 * <td>20–22</td> 200 * <td></td> 201 * </tr> 202 * <tr class="deprecated"> 203 * <td>TLS_DHE_DSS_WITH_AES_256_CBC_SHA</td> 204 * <td>9–22</td> 205 * <td>20–22</td> 206 * </tr> 207 * <tr class="deprecated"> 208 * <td>TLS_DHE_DSS_WITH_AES_256_CBC_SHA256</td> 209 * <td>20–22</td> 210 * <td></td> 211 * </tr> 212 * <tr class="deprecated"> 213 * <td>TLS_DHE_DSS_WITH_AES_256_GCM_SHA384</td> 214 * <td>20–22</td> 215 * <td></td> 216 * </tr> 217 * <tr class="deprecated"> 218 * <td>TLS_DHE_DSS_WITH_DES_CBC_SHA</td> 219 * <td>1–8</td> 220 * <td>1–8</td> 221 * </tr> 222 * <tr class="deprecated"> 223 * <td>TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA</td> 224 * <td>1–8</td> 225 * <td>1–8</td> 226 * </tr> 227 * <tr class="deprecated"> 228 * <td>TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA</td> 229 * <td>1–8</td> 230 * <td>1–8</td> 231 * </tr> 232 * <tr> 233 * <td>TLS_DHE_RSA_WITH_AES_128_CBC_SHA</td> 234 * <td>9+</td> 235 * <td>9+</td> 236 * </tr> 237 * <tr> 238 * <td>TLS_DHE_RSA_WITH_AES_128_CBC_SHA256</td> 239 * <td>20+</td> 240 * <td></td> 241 * </tr> 242 * <tr> 243 * <td>TLS_DHE_RSA_WITH_AES_128_GCM_SHA256</td> 244 * <td>20+</td> 245 * <td>20+</td> 246 * </tr> 247 * <tr> 248 * <td>TLS_DHE_RSA_WITH_AES_256_CBC_SHA</td> 249 * <td>9+</td> 250 * <td>20+</td> 251 * </tr> 252 * <tr> 253 * <td>TLS_DHE_RSA_WITH_AES_256_CBC_SHA256</td> 254 * <td>20+</td> 255 * <td></td> 256 * </tr> 257 * <tr> 258 * <td>TLS_DHE_RSA_WITH_AES_256_GCM_SHA384</td> 259 * <td>20+</td> 260 * <td>20+</td> 261 * </tr> 262 * <tr class="deprecated"> 263 * <td>TLS_DHE_RSA_WITH_DES_CBC_SHA</td> 264 * <td>1–8</td> 265 * <td>1–8</td> 266 * </tr> 267 * <tr class="deprecated"> 268 * <td>TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA</td> 269 * <td>1–8</td> 270 * <td></td> 271 * </tr> 272 * <tr class="deprecated"> 273 * <td>TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA</td> 274 * <td>1–8</td> 275 * <td></td> 276 * </tr> 277 * <tr class="deprecated"> 278 * <td>TLS_DH_DSS_WITH_DES_CBC_SHA</td> 279 * <td>1–8</td> 280 * <td></td> 281 * </tr> 282 * <tr class="deprecated"> 283 * <td>TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA</td> 284 * <td>1–8</td> 285 * <td></td> 286 * </tr> 287 * <tr class="deprecated"> 288 * <td>TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA</td> 289 * <td>1–8</td> 290 * <td></td> 291 * </tr> 292 * <tr class="deprecated"> 293 * <td>TLS_DH_RSA_WITH_DES_CBC_SHA</td> 294 * <td>1–8</td> 295 * <td></td> 296 * </tr> 297 * <tr class="deprecated"> 298 * <td>TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA</td> 299 * <td>1–8</td> 300 * <td></td> 301 * </tr> 302 * <tr class="deprecated"> 303 * <td>TLS_DH_anon_WITH_3DES_EDE_CBC_SHA</td> 304 * <td>1–8</td> 305 * <td></td> 306 * </tr> 307 * <tr class="deprecated"> 308 * <td>TLS_DH_anon_WITH_AES_128_CBC_SHA</td> 309 * <td>9–22</td> 310 * <td></td> 311 * </tr> 312 * <tr class="deprecated"> 313 * <td>TLS_DH_anon_WITH_AES_128_CBC_SHA256</td> 314 * <td>20–22</td> 315 * <td></td> 316 * </tr> 317 * <tr class="deprecated"> 318 * <td>TLS_DH_anon_WITH_AES_128_GCM_SHA256</td> 319 * <td>20–22</td> 320 * <td></td> 321 * </tr> 322 * <tr class="deprecated"> 323 * <td>TLS_DH_anon_WITH_AES_256_CBC_SHA</td> 324 * <td>9–22</td> 325 * <td></td> 326 * </tr> 327 * <tr class="deprecated"> 328 * <td>TLS_DH_anon_WITH_AES_256_CBC_SHA256</td> 329 * <td>20–22</td> 330 * <td></td> 331 * </tr> 332 * <tr class="deprecated"> 333 * <td>TLS_DH_anon_WITH_AES_256_GCM_SHA384</td> 334 * <td>20–22</td> 335 * <td></td> 336 * </tr> 337 * <tr class="deprecated"> 338 * <td>TLS_DH_anon_WITH_DES_CBC_SHA</td> 339 * <td>1–8</td> 340 * <td></td> 341 * </tr> 342 * <tr class="deprecated"> 343 * <td>TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA</td> 344 * <td>20–22</td> 345 * <td></td> 346 * </tr> 347 * <tr> 348 * <td>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</td> 349 * <td>20+</td> 350 * <td>20+</td> 351 * </tr> 352 * <tr> 353 * <td>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256</td> 354 * <td>20+</td> 355 * <td></td> 356 * </tr> 357 * <tr> 358 * <td>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</td> 359 * <td>20+</td> 360 * <td>20+</td> 361 * </tr> 362 * <tr> 363 * <td>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</td> 364 * <td>20+</td> 365 * <td>20+</td> 366 * </tr> 367 * <tr> 368 * <td>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384</td> 369 * <td>20+</td> 370 * <td></td> 371 * </tr> 372 * <tr> 373 * <td>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</td> 374 * <td>20+</td> 375 * <td>20+</td> 376 * </tr> 377 * <tr class="deprecated"> 378 * <td>TLS_ECDHE_ECDSA_WITH_NULL_SHA</td> 379 * <td>20–22</td> 380 * <td></td> 381 * </tr> 382 * <tr> 383 * <td>TLS_ECDHE_ECDSA_WITH_RC4_128_SHA</td> 384 * <td>20+</td> 385 * <td>20+</td> 386 * </tr> 387 * <tr class="deprecated"> 388 * <td>TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA</td> 389 * <td>20–22</td> 390 * <td></td> 391 * </tr> 392 * <tr> 393 * <td>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</td> 394 * <td>20+</td> 395 * <td>20+</td> 396 * </tr> 397 * <tr> 398 * <td>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</td> 399 * <td>20+</td> 400 * <td></td> 401 * </tr> 402 * <tr> 403 * <td>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</td> 404 * <td>20+</td> 405 * <td>20+</td> 406 * </tr> 407 * <tr> 408 * <td>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</td> 409 * <td>20+</td> 410 * <td>20+</td> 411 * </tr> 412 * <tr> 413 * <td>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384</td> 414 * <td>20+</td> 415 * <td></td> 416 * </tr> 417 * <tr> 418 * <td>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</td> 419 * <td>20+</td> 420 * <td>20+</td> 421 * </tr> 422 * <tr class="deprecated"> 423 * <td>TLS_ECDHE_RSA_WITH_NULL_SHA</td> 424 * <td>20–22</td> 425 * <td></td> 426 * </tr> 427 * <tr> 428 * <td>TLS_ECDHE_RSA_WITH_RC4_128_SHA</td> 429 * <td>20+</td> 430 * <td>20+</td> 431 * </tr> 432 * <tr class="deprecated"> 433 * <td>TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA</td> 434 * <td>20–22</td> 435 * <td></td> 436 * </tr> 437 * <tr class="deprecated"> 438 * <td>TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA</td> 439 * <td>20–22</td> 440 * <td></td> 441 * </tr> 442 * <tr class="deprecated"> 443 * <td>TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256</td> 444 * <td>20–22</td> 445 * <td></td> 446 * </tr> 447 * <tr class="deprecated"> 448 * <td>TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256</td> 449 * <td>20–22</td> 450 * <td></td> 451 * </tr> 452 * <tr class="deprecated"> 453 * <td>TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA</td> 454 * <td>20–22</td> 455 * <td></td> 456 * </tr> 457 * <tr class="deprecated"> 458 * <td>TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384</td> 459 * <td>20–22</td> 460 * <td></td> 461 * </tr> 462 * <tr class="deprecated"> 463 * <td>TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384</td> 464 * <td>20–22</td> 465 * <td></td> 466 * </tr> 467 * <tr class="deprecated"> 468 * <td>TLS_ECDH_ECDSA_WITH_NULL_SHA</td> 469 * <td>20–22</td> 470 * <td></td> 471 * </tr> 472 * <tr class="deprecated"> 473 * <td>TLS_ECDH_ECDSA_WITH_RC4_128_SHA</td> 474 * <td>20–22</td> 475 * <td></td> 476 * </tr> 477 * <tr class="deprecated"> 478 * <td>TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA</td> 479 * <td>20–22</td> 480 * <td></td> 481 * </tr> 482 * <tr class="deprecated"> 483 * <td>TLS_ECDH_RSA_WITH_AES_128_CBC_SHA</td> 484 * <td>20–22</td> 485 * <td></td> 486 * </tr> 487 * <tr class="deprecated"> 488 * <td>TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256</td> 489 * <td>20–22</td> 490 * <td></td> 491 * </tr> 492 * <tr class="deprecated"> 493 * <td>TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256</td> 494 * <td>20–22</td> 495 * <td></td> 496 * </tr> 497 * <tr class="deprecated"> 498 * <td>TLS_ECDH_RSA_WITH_AES_256_CBC_SHA</td> 499 * <td>20–22</td> 500 * <td></td> 501 * </tr> 502 * <tr class="deprecated"> 503 * <td>TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384</td> 504 * <td>20–22</td> 505 * <td></td> 506 * </tr> 507 * <tr class="deprecated"> 508 * <td>TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384</td> 509 * <td>20–22</td> 510 * <td></td> 511 * </tr> 512 * <tr class="deprecated"> 513 * <td>TLS_ECDH_RSA_WITH_NULL_SHA</td> 514 * <td>20–22</td> 515 * <td></td> 516 * </tr> 517 * <tr class="deprecated"> 518 * <td>TLS_ECDH_RSA_WITH_RC4_128_SHA</td> 519 * <td>20–22</td> 520 * <td></td> 521 * </tr> 522 * <tr class="deprecated"> 523 * <td>TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA</td> 524 * <td>20–22</td> 525 * <td></td> 526 * </tr> 527 * <tr class="deprecated"> 528 * <td>TLS_ECDH_anon_WITH_AES_128_CBC_SHA</td> 529 * <td>20–22</td> 530 * <td></td> 531 * </tr> 532 * <tr class="deprecated"> 533 * <td>TLS_ECDH_anon_WITH_AES_256_CBC_SHA</td> 534 * <td>20–22</td> 535 * <td></td> 536 * </tr> 537 * <tr class="deprecated"> 538 * <td>TLS_ECDH_anon_WITH_NULL_SHA</td> 539 * <td>20–22</td> 540 * <td></td> 541 * </tr> 542 * <tr class="deprecated"> 543 * <td>TLS_ECDH_anon_WITH_RC4_128_SHA</td> 544 * <td>20–22</td> 545 * <td></td> 546 * </tr> 547 * <tr> 548 * <td>TLS_EMPTY_RENEGOTIATION_INFO_SCSV</td> 549 * <td>20+</td> 550 * <td>20+</td> 551 * </tr> 552 * <tr> 553 * <td>TLS_FALLBACK_SCSV</td> 554 * <td>21+</td> 555 * <td></td> 556 * </tr> 557 * <tr> 558 * <td>TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA</td> 559 * <td>21+</td> 560 * <td>21+</td> 561 * </tr> 562 * <tr> 563 * <td>TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA</td> 564 * <td>21+</td> 565 * <td>21+</td> 566 * </tr> 567 * <tr class="deprecated"> 568 * <td>TLS_NULL_WITH_NULL_NULL</td> 569 * <td>1–8</td> 570 * <td></td> 571 * </tr> 572 * <tr class="deprecated"> 573 * <td>TLS_PSK_WITH_3DES_EDE_CBC_SHA</td> 574 * <td>21–22</td> 575 * <td></td> 576 * </tr> 577 * <tr> 578 * <td>TLS_PSK_WITH_AES_128_CBC_SHA</td> 579 * <td>21+</td> 580 * <td>21+</td> 581 * </tr> 582 * <tr> 583 * <td>TLS_PSK_WITH_AES_256_CBC_SHA</td> 584 * <td>21+</td> 585 * <td>21+</td> 586 * </tr> 587 * <tr> 588 * <td>TLS_PSK_WITH_RC4_128_SHA</td> 589 * <td>21+</td> 590 * <td></td> 591 * </tr> 592 * <tr class="deprecated"> 593 * <td>TLS_RSA_EXPORT_WITH_DES40_CBC_SHA</td> 594 * <td>1–8</td> 595 * <td>1–8</td> 596 * </tr> 597 * <tr class="deprecated"> 598 * <td>TLS_RSA_WITH_3DES_EDE_CBC_SHA</td> 599 * <td>1–8</td> 600 * <td>1–8</td> 601 * </tr> 602 * <tr> 603 * <td>TLS_RSA_WITH_AES_128_CBC_SHA</td> 604 * <td>9+</td> 605 * <td>9+</td> 606 * </tr> 607 * <tr> 608 * <td>TLS_RSA_WITH_AES_128_CBC_SHA256</td> 609 * <td>20+</td> 610 * <td></td> 611 * </tr> 612 * <tr> 613 * <td>TLS_RSA_WITH_AES_128_GCM_SHA256</td> 614 * <td>20+</td> 615 * <td>20+</td> 616 * </tr> 617 * <tr> 618 * <td>TLS_RSA_WITH_AES_256_CBC_SHA</td> 619 * <td>9+</td> 620 * <td>20+</td> 621 * </tr> 622 * <tr> 623 * <td>TLS_RSA_WITH_AES_256_CBC_SHA256</td> 624 * <td>20+</td> 625 * <td></td> 626 * </tr> 627 * <tr> 628 * <td>TLS_RSA_WITH_AES_256_GCM_SHA384</td> 629 * <td>20+</td> 630 * <td>20+</td> 631 * </tr> 632 * <tr class="deprecated"> 633 * <td>TLS_RSA_WITH_DES_CBC_SHA</td> 634 * <td>1–8</td> 635 * <td>1–8</td> 636 * </tr> 637 * <tr class="deprecated"> 638 * <td>TLS_RSA_WITH_NULL_MD5</td> 639 * <td>1–8</td> 640 * <td></td> 641 * </tr> 642 * <tr class="deprecated"> 643 * <td>TLS_RSA_WITH_NULL_SHA</td> 644 * <td>1–8</td> 645 * <td></td> 646 * </tr> 647 * <tr class="deprecated"> 648 * <td>TLS_RSA_WITH_NULL_SHA256</td> 649 * <td>20–22</td> 650 * <td></td> 651 * </tr> 652 * </tbody> 653 * </table> 654 * 655 * <p><em>NOTE</em>: PSK cipher suites are enabled by default only if the {@code SSLContext} through 656 * which the engine was created has been initialized with a {@code PSKKeyManager}. 657 * 658 * @since 1.5 659 */ 660 public abstract class SSLEngine { 661 private final String peerHost; 662 private final int peerPort; 663 664 /** 665 * Creates a new {@code SSLEngine} instance. 666 */ 667 protected SSLEngine() { 668 peerHost = null; 669 peerPort = -1; 670 } 671 672 /** 673 * Creates a new {@code SSLEngine} instance with the specified host and 674 * port. 675 * 676 * @param host 677 * the name of the host. 678 * @param port 679 * the port of the host. 680 */ 681 protected SSLEngine(String host, int port) { 682 this.peerHost = host; 683 this.peerPort = port; 684 } 685 686 /** 687 * Returns the name of the peer host. 688 * 689 * @return the name of the peer host, or {@code null} if none is available. 690 */ 691 public String getPeerHost() { 692 return peerHost; 693 } 694 695 /** 696 * Returns the port number of the peer host. 697 * 698 * @return the port number of the peer host, or {@code -1} is none is 699 * available. 700 */ 701 public int getPeerPort() { 702 return peerPort; 703 } 704 705 /** 706 * Initiates a handshake on this engine. 707 * <p> 708 * Calling this method is not needed for the initial handshake: it will be 709 * called by {@code wrap} or {@code unwrap} if the initial handshake has not 710 * been started yet. 711 * 712 * @throws SSLException 713 * if starting the handshake fails. 714 * @throws IllegalStateException 715 * if the engine does not have all the needed settings (e.g. 716 * client/server mode not set). 717 */ 718 public abstract void beginHandshake() throws SSLException; 719 720 /** 721 * Notifies this engine instance that no more inbound network data will be 722 * sent to this engine. 723 * 724 * @throws SSLException 725 * if this engine did not receive a needed protocol specific 726 * close notification message from the peer. 727 */ 728 public abstract void closeInbound() throws SSLException; 729 730 /** 731 * Notifies this engine instance that no more outbound application data will 732 * be sent to this engine. 733 */ 734 public abstract void closeOutbound(); 735 736 /** 737 * Returns a delegate task for this engine instance. Some engine operations 738 * may require the results of blocking or long running operations, and the 739 * {@code SSLEngineResult} instances returned by this engine may indicate 740 * that a delegated task result is needed. In this case the 741 * {@link Runnable#run() run} method of the returned {@code Runnable} 742 * delegated task must be called. 743 * 744 * @return a delegate task, or {@code null} if none are available. 745 */ 746 public abstract Runnable getDelegatedTask(); 747 748 /** 749 * Returns the SSL cipher suite names that are enabled in this engine 750 * instance. 751 * 752 * @return the SSL cipher suite names that are enabled in this engine 753 * instance. 754 */ 755 public abstract String[] getEnabledCipherSuites(); 756 757 /** 758 * Returns the protocol version names that are enabled in this engine 759 * instance. 760 * 761 * @return the protocol version names that are enabled in this engine 762 * instance. 763 */ 764 public abstract String[] getEnabledProtocols(); 765 766 /** 767 * Returns whether new SSL sessions may be established by this engine. 768 * 769 * @return {@code true} if new session may be established, {@code false} if 770 * existing sessions must be reused. 771 */ 772 public abstract boolean getEnableSessionCreation(); 773 774 /** 775 * Returns the status of the handshake of this engine instance. 776 * 777 * @return the status of the handshake of this engine instance. 778 */ 779 public abstract SSLEngineResult.HandshakeStatus getHandshakeStatus(); 780 781 /** 782 * Returns whether this engine instance will require client authentication. 783 * 784 * @return {@code true} if this engine will require client authentication, 785 * {@code false} if no client authentication is needed. 786 */ 787 public abstract boolean getNeedClientAuth(); 788 789 /** 790 * Returns the SSL session for this engine instance. 791 * 792 * @return the SSL session for this engine instance. 793 */ 794 public abstract SSLSession getSession(); 795 796 /** 797 * Returns the SSL cipher suite names that are supported by this engine. 798 * These cipher suites can be enabled using 799 * {@link #setEnabledCipherSuites(String[])}. 800 * 801 * @return the SSL cipher suite names that are supported by this engine. 802 */ 803 public abstract String[] getSupportedCipherSuites(); 804 805 /** 806 * Returns the protocol names that are supported by this engine. These 807 * protocols can be enables using {@link #setEnabledProtocols(String[])}. 808 * 809 * @return the protocol names that are supported by this engine. 810 */ 811 public abstract String[] getSupportedProtocols(); 812 813 /** 814 * Returns whether this engine is set to act in client mode when 815 * handshaking. 816 * 817 * @return {@code true} if the engine is set to do handshaking in client 818 * mode. 819 */ 820 public abstract boolean getUseClientMode(); 821 822 /** 823 * Returns whether this engine will request client authentication. 824 * 825 * @return {@code true} if client authentication will be requested, 826 * {@code false} otherwise. 827 */ 828 public abstract boolean getWantClientAuth(); 829 830 /** 831 * Returns whether no more inbound data will be accepted by this engine. 832 * 833 * @return {@code true} if no more inbound data will be accepted by this 834 * engine, {@code false} otherwise. 835 */ 836 public abstract boolean isInboundDone(); 837 838 /** 839 * Returns whether no more outbound data will be produced by this engine. 840 * 841 * @return {@code true} if no more outbound data will be producted by this 842 * engine, {@code otherwise} false. 843 */ 844 public abstract boolean isOutboundDone(); 845 846 /** 847 * Sets the SSL cipher suite names that should be enabled in this engine 848 * instance. Only cipher suites listed by {@code getSupportedCipherSuites()} 849 * are allowed. 850 * 851 * @param suites 852 * the SSL cipher suite names to be enabled. 853 * @throws IllegalArgumentException 854 * if one of the specified cipher suites is not supported, or if 855 * {@code suites} is {@code null}. 856 */ 857 public abstract void setEnabledCipherSuites(String[] suites); 858 859 /** 860 * Sets the protocol version names that should be enabled in this engine 861 * instance. Only protocols listed by {@code getSupportedProtocols()} are 862 * allowed. 863 * 864 * @param protocols 865 * the protocol version names to be enabled. 866 * @throws IllegalArgumentException 867 * if one of the protocol version names is not supported, or if 868 * {@code protocols} is {@code null}. 869 */ 870 public abstract void setEnabledProtocols(String[] protocols); 871 872 /** 873 * Sets whether new SSL sessions may be established by this engine instance. 874 * 875 * @param flag 876 * {@code true} if new SSL sessions may be established, 877 * {@code false} if existing SSL sessions must be reused. 878 */ 879 public abstract void setEnableSessionCreation(boolean flag); 880 881 /** 882 * Sets whether this engine must require client authentication. The client 883 * authentication is one of: 884 * <ul> 885 * <li>authentication required</li> 886 * <li>authentication requested</li> 887 * <li>no authentication needed</li> 888 * </ul> 889 * This method overrides the setting of {@link #setWantClientAuth(boolean)}. 890 * 891 * @param need 892 * {@code true} if client authentication is required, 893 * {@code false} if no authentication is needed. 894 */ 895 public abstract void setNeedClientAuth(boolean need); 896 897 /** 898 * Sets whether this engine should act in client (or server) mode when 899 * handshaking. 900 * 901 * @param mode 902 * {@code true} if this engine should act in client mode, 903 * {@code false} if not. 904 * @throws IllegalArgumentException 905 * if this method is called after starting the initial 906 * handshake. 907 */ 908 public abstract void setUseClientMode(boolean mode); 909 910 /** 911 * Sets whether this engine should request client authentication. The client 912 * authentication is one of the following: 913 * <ul> 914 * <li>authentication required</li> 915 * <li>authentication requested</li> 916 * <li>no authentication needed</li> 917 * </ul> 918 * This method overrides the setting of {@link #setNeedClientAuth(boolean)}. 919 * 920 * @param want 921 * {@code true} if client authentication should be requested, 922 * {@code false} if no authentication is needed. 923 */ 924 public abstract void setWantClientAuth(boolean want); 925 926 /** 927 * Decodes the incoming network data buffer into application data buffers. 928 * If a handshake has not been started yet, it will automatically be 929 * started. 930 * 931 * @param src 932 * the buffer with incoming network data 933 * @param dsts 934 * the array of destination buffers for incoming application 935 * data. 936 * @param offset 937 * the offset in the array of destination buffers to which data 938 * is to be transferred. 939 * @param length 940 * the maximum number of destination buffers to be used. 941 * @return the result object of this operation. 942 * @throws SSLException 943 * if a problem occurred while processing the data. 944 * @throws IndexOutOfBoundsException 945 * if {@code length} is greater than 946 * {@code dsts.length - offset}. 947 * @throws java.nio.ReadOnlyBufferException 948 * if one of the destination buffers is read-only. 949 * @throws IllegalArgumentException 950 * if {@code src}, {@code dsts}, or one of the entries in 951 * {@code dsts} is {@code null}. 952 * @throws IllegalStateException 953 * if the engine does not have all the needed settings (e.g. 954 * client/server mode not set). 955 */ 956 public abstract SSLEngineResult unwrap(ByteBuffer src, 957 ByteBuffer[] dsts, 958 int offset, 959 int length) throws SSLException; 960 961 /** 962 * Encodes the outgoing application data buffers into the network data 963 * buffer. If a handshake has not been started yet, it will automatically be 964 * started. 965 * 966 * @param srcs 967 * the array of source buffers of outgoing application data. 968 * @param offset 969 * the offset in the array of source buffers from which data is 970 * to be retrieved. 971 * @param length 972 * the maximum number of source buffers to be used. 973 * @param dst 974 * the destination buffer for network data. 975 * @return the result object of this operation. 976 * @throws SSLException 977 * if a problem occurred while processing the data. 978 * @throws IndexOutOfBoundsException 979 * if {@code length} is greater than 980 * {@code srcs.length - offset}. 981 * @throws java.nio.ReadOnlyBufferException 982 * if the destination buffer is readonly. 983 * @throws IllegalArgumentException 984 * if {@code srcs}, {@code dst}, or one the entries in 985 * {@code srcs} is {@code null}. 986 * @throws IllegalStateException 987 * if the engine does not have all the needed settings (e.g. 988 * client/server mode not set). 989 */ 990 public abstract SSLEngineResult wrap(ByteBuffer[] srcs, int offset, int length, ByteBuffer dst) 991 throws SSLException; 992 993 /** 994 * Decodes the incoming network data buffer into the application data 995 * buffer. If a handshake has not been started yet, it will automatically be 996 * started. 997 * 998 * @param src 999 * the buffer with incoming network data 1000 * @param dst 1001 * the destination buffer for incoming application data. 1002 * @return the result object of this operation. 1003 * @throws SSLException 1004 * if a problem occurred while processing the data. 1005 * @throws java.nio.ReadOnlyBufferException 1006 * if one of the destination buffers is read-only. 1007 * @throws IllegalArgumentException 1008 * if {@code src} or {@code dst} is {@code null}. 1009 * @throws IllegalStateException 1010 * if the engine does not have all the needed settings (e.g. 1011 * client/server mode not set). 1012 */ 1013 public SSLEngineResult unwrap(ByteBuffer src, ByteBuffer dst) throws SSLException { 1014 return unwrap(src, new ByteBuffer[] { dst }, 0, 1); 1015 } 1016 1017 /** 1018 * Decodes the incoming network data buffer into the application data 1019 * buffers. If a handshake has not been started yet, it will automatically 1020 * be started. 1021 * 1022 * @param src 1023 * the buffer with incoming network data 1024 * @param dsts 1025 * the array of destination buffers for incoming application 1026 * data. 1027 * @return the result object of this operation. 1028 * @throws SSLException 1029 * if a problem occurred while processing the data. 1030 * @throws java.nio.ReadOnlyBufferException 1031 * if one of the destination buffers is read-only. 1032 * @throws IllegalArgumentException 1033 * if {@code src} or {@code dsts} is {@code null}. 1034 * @throws IllegalStateException 1035 * if the engine does not have all the needed settings (e.g. 1036 * client/server mode not set). 1037 */ 1038 public SSLEngineResult unwrap(ByteBuffer src, ByteBuffer[] dsts) throws SSLException { 1039 if (dsts == null) { 1040 throw new IllegalArgumentException("Byte buffer array dsts is null"); 1041 } 1042 return unwrap(src, dsts, 0, dsts.length); 1043 } 1044 1045 /** 1046 * Encodes the outgoing application data buffers into the network data 1047 * buffer. If a handshake has not been started yet, it will automatically be 1048 * started. 1049 * 1050 * @param srcs 1051 * the array of source buffers of outgoing application data. 1052 * @param dst 1053 * the destination buffer for network data. 1054 * @return the result object of this operation. 1055 * @throws SSLException 1056 * if a problem occurred while processing the data. 1057 * @throws java.nio.ReadOnlyBufferException 1058 * if the destination buffer is readonly. 1059 * @throws IllegalArgumentException 1060 * if {@code srcs} or {@code dst} is {@code null}. 1061 * @throws IllegalStateException 1062 * if the engine does not have all the needed settings (e.g. 1063 * client/server mode not set). 1064 */ 1065 public SSLEngineResult wrap(ByteBuffer[] srcs, ByteBuffer dst) throws SSLException { 1066 if (srcs == null) { 1067 throw new IllegalArgumentException("Byte buffer array srcs is null"); 1068 } 1069 return wrap(srcs, 0, srcs.length, dst); 1070 } 1071 1072 /** 1073 * Encodes the outgoing application data buffer into the network data 1074 * buffer. If a handshake has not been started yet, it will automatically be 1075 * started. 1076 * 1077 * @param src 1078 * the source buffers of outgoing application data. 1079 * @param dst 1080 * the destination buffer for network data. 1081 * @return the result object of this operation. 1082 * @throws SSLException 1083 * if a problem occurred while processing the data. 1084 * @throws java.nio.ReadOnlyBufferException 1085 * if the destination buffer is readonly. 1086 * @throws IllegalArgumentException 1087 * if {@code src} or {@code dst} is {@code null}. 1088 * @throws IllegalStateException 1089 * if the engine does not have all the needed settings (e.g. 1090 * client/server mode not set). 1091 */ 1092 public SSLEngineResult wrap(ByteBuffer src, ByteBuffer dst) throws SSLException { 1093 return wrap(new ByteBuffer[] { src }, 0, 1, dst); 1094 } 1095 1096 /** 1097 * Returns a new SSLParameters based on this SSLSocket's current 1098 * cipher suites, protocols, and client authentication settings. 1099 * 1100 * @since 1.6 1101 */ 1102 public SSLParameters getSSLParameters() { 1103 SSLParameters p = new SSLParameters(); 1104 p.setCipherSuites(getEnabledCipherSuites()); 1105 p.setProtocols(getEnabledProtocols()); 1106 p.setNeedClientAuth(getNeedClientAuth()); 1107 p.setWantClientAuth(getWantClientAuth()); 1108 return p; 1109 } 1110 1111 /** 1112 * Sets various SSL handshake parameters based on the SSLParameter 1113 * argument. Specifically, sets the SSLEngine's enabled cipher 1114 * suites if the parameter's cipher suites are non-null. Similarly 1115 * sets the enabled protocols. If the parameters specify the want 1116 * or need for client authentication, those requirements are set 1117 * on the SSLEngine, otherwise both are set to false. 1118 * @since 1.6 1119 */ 1120 public void setSSLParameters(SSLParameters p) { 1121 String[] cipherSuites = p.getCipherSuites(); 1122 if (cipherSuites != null) { 1123 setEnabledCipherSuites(cipherSuites); 1124 } 1125 String[] protocols = p.getProtocols(); 1126 if (protocols != null) { 1127 setEnabledProtocols(protocols); 1128 } 1129 if (p.getNeedClientAuth()) { 1130 setNeedClientAuth(true); 1131 } else if (p.getWantClientAuth()) { 1132 setWantClientAuth(true); 1133 } else { 1134 setWantClientAuth(false); 1135 } 1136 } 1137 } 1138
