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