1 /*
   2  * Copyright (c) 2003, 2017, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.net.ssl;
  27 
  28 import java.nio.ByteBuffer;
  29 import java.nio.ReadOnlyBufferException;
  30 import java.util.List;
  31 import java.util.function.BiFunction;
  32 
  33 
  34 /**
  35  * A class which enables secure communications using protocols such as
  36  * the Secure Sockets Layer (SSL) or
  37  * <A HREF="http://www.ietf.org/rfc/rfc2246.txt"> IETF RFC 2246 "Transport
  38  * Layer Security" (TLS) </A> protocols, but is transport independent.
  39  * <P>
  40  * The secure communications modes include: <UL>
  41  *
  42  *      <LI> <em>Integrity Protection</em>.  SSL/TLS/DTLS protects against
  43  *      modification of messages by an active wiretapper.
  44  *
  45  *      <LI> <em>Authentication</em>.  In most modes, SSL/TLS/DTLS provides
  46  *      peer authentication.  Servers are usually authenticated, and
  47  *      clients may be authenticated as requested by servers.
  48  *
  49  *      <LI> <em>Confidentiality (Privacy Protection)</em>.  In most
  50  *      modes, SSL/TLS/DTLS encrypts data being sent between client and
  51  *      server.  This protects the confidentiality of data, so that
  52  *      passive wiretappers won't see sensitive data such as financial
  53  *      information or personal information of many kinds.
  54  *
  55  *      </UL>
  56  *
  57  * These kinds of protection are specified by a "cipher suite", which
  58  * is a combination of cryptographic algorithms used by a given SSL
  59  * connection.  During the negotiation process, the two endpoints must
  60  * agree on a cipher suite that is available in both environments.  If
  61  * there is no such suite in common, no SSL connection can be
  62  * established, and no data can be exchanged.
  63  * <P>
  64  * The cipher suite used is established by a negotiation process called
  65  * "handshaking".  The goal of this process is to create or rejoin a
  66  * "session", which may protect many connections over time.  After
  67  * handshaking has completed, you can access session attributes by
  68  * using the {@link #getSession()} method.
  69  * <P>
  70  * The {@code SSLSocket} class provides much of the same security
  71  * functionality, but all of the inbound and outbound data is
  72  * automatically transported using the underlying {@link
  73  * java.net.Socket Socket}, which by design uses a blocking model.
  74  * While this is appropriate for many applications, this model does not
  75  * provide the scalability required by large servers.
  76  * <P>
  77  * The primary distinction of an {@code SSLEngine} is that it
  78  * operates on inbound and outbound byte streams, independent of the
  79  * transport mechanism.  It is the responsibility of the
  80  * {@code SSLEngine} user to arrange for reliable I/O transport to
  81  * the peer.  By separating the SSL/TLS/DTLS abstraction from the I/O
  82  * transport mechanism, the {@code SSLEngine} can be used for a
  83  * wide variety of I/O types, such as {@link
  84  * java.nio.channels.spi.AbstractSelectableChannel#configureBlocking(boolean)
  85  * non-blocking I/O (polling)}, {@link java.nio.channels.Selector
  86  * selectable non-blocking I/O}, {@link java.net.Socket Socket} and the
  87  * traditional Input/OutputStreams, local {@link java.nio.ByteBuffer
  88  * ByteBuffers} or byte arrays, <A
  89  * HREF="http://www.jcp.org/en/jsr/detail?id=203"> future asynchronous
  90  * I/O models </A>, and so on.
  91  * <P>
  92  * At a high level, the {@code SSLEngine} appears thus:
  93  *
  94  * <pre>
  95  *                   app data
  96  *
  97  *                |           ^
  98  *                |     |     |
  99  *                v     |     |
 100  *           +----+-----|-----+----+
 101  *           |          |          |
 102  *           |       SSL|Engine    |
 103  *   wrap()  |          |          |  unwrap()
 104  *           | OUTBOUND | INBOUND  |
 105  *           |          |          |
 106  *           +----+-----|-----+----+
 107  *                |     |     ^
 108  *                |     |     |
 109  *                v           |
 110  *
 111  *                   net data
 112  * </pre>
 113  * Application data (also known as plaintext or cleartext) is data which
 114  * is produced or consumed by an application.  Its counterpart is
 115  * network data, which consists of either handshaking and/or ciphertext
 116  * (encrypted) data, and destined to be transported via an I/O
 117  * mechanism.  Inbound data is data which has been received from the
 118  * peer, and outbound data is destined for the peer.
 119  * <P>
 120  * (In the context of an {@code SSLEngine}, the term "handshake
 121  * data" is taken to mean any data exchanged to establish and control a
 122  * secure connection.  Handshake data includes the SSL/TLS/DTLS messages
 123  * "alert", "change_cipher_spec," and "handshake.")
 124  * <P>
 125  * There are five distinct phases to an {@code SSLEngine}.
 126  *
 127  * <OL>
 128  *     <li> Creation - The {@code SSLEngine} has been created and
 129  *     initialized, but has not yet been used.  During this phase, an
 130  *     application may set any {@code SSLEngine}-specific settings
 131  *     (enabled cipher suites, whether the {@code SSLEngine} should
 132  *     handshake in client or server mode, and so on).  Once
 133  *     handshaking has begun, though, any new settings (except
 134  *     client/server mode, see below) will be used for
 135  *     the next handshake.
 136  *
 137  *     <li> Initial Handshake - The initial handshake is a procedure by
 138  *     which the two peers exchange communication parameters until an
 139  *     SSLSession is established.  Application data can not be sent during
 140  *     this phase.
 141  *
 142  *     <li> Application Data - Once the communication parameters have
 143  *     been established and the handshake is complete, application data
 144  *     may flow through the {@code SSLEngine}.  Outbound
 145  *     application messages are encrypted and integrity protected,
 146  *     and inbound messages reverse the process.
 147  *
 148  *     <li>  Rehandshaking - Either side may request a renegotiation of
 149  *     the session at any time during the Application Data phase.  New
 150  *     handshaking data can be intermixed among the application data.
 151  *     Before starting the rehandshake phase, the application may
 152  *     reset the SSL/TLS/DTLS communication parameters such as the list of
 153  *     enabled ciphersuites and whether to use client authentication,
 154  *     but can not change between client/server modes.  As before, once
 155  *     handshaking has begun, any new {@code SSLEngine}
 156  *     configuration settings will not be used until the next
 157  *     handshake.
 158  *
 159  *     <li>  Closure - When the connection is no longer needed, the
 160  *     application should close the {@code SSLEngine} and should
 161  *     send/receive any remaining messages to the peer before
 162  *     closing the underlying transport mechanism.  Once an engine is
 163  *     closed, it is not reusable:  a new {@code SSLEngine} must
 164  *     be created.
 165  * </OL>
 166  * An {@code SSLEngine} is created by calling {@link
 167  * SSLContext#createSSLEngine()} from an initialized
 168  * {@code SSLContext}.  Any configuration
 169  * parameters should be set before making the first call to
 170  * {@code wrap()}, {@code unwrap()}, or
 171  * {@code beginHandshake()}.  These methods all trigger the
 172  * initial handshake.
 173  * <P>
 174  * Data moves through the engine by calling {@link #wrap(ByteBuffer,
 175  * ByteBuffer) wrap()} or {@link #unwrap(ByteBuffer, ByteBuffer)
 176  * unwrap()} on outbound or inbound data, respectively.  Depending on
 177  * the state of the {@code SSLEngine}, a {@code wrap()} call
 178  * may consume application data from the source buffer and may produce
 179  * network data in the destination buffer.  The outbound data
 180  * may contain application and/or handshake data.  A call to
 181  * {@code unwrap()} will examine the source buffer and may
 182  * advance the handshake if the data is handshaking information, or
 183  * may place application data in the destination buffer if the data
 184  * is application.  The state of the underlying SSL/TLS/DTLS algorithm
 185  * will determine when data is consumed and produced.
 186  * <P>
 187  * Calls to {@code wrap()} and {@code unwrap()} return an
 188  * {@code SSLEngineResult} which indicates the status of the
 189  * operation, and (optionally) how to interact with the engine to make
 190  * progress.
 191  * <P>
 192  * The {@code SSLEngine} produces/consumes complete SSL/TLS/DTLS
 193  * packets only, and does not store application data internally between
 194  * calls to {@code wrap()/unwrap()}.  Thus input and output
 195  * {@code ByteBuffer}s must be sized appropriately to hold the
 196  * maximum record that can be produced.  Calls to {@link
 197  * SSLSession#getPacketBufferSize()} and {@link
 198  * SSLSession#getApplicationBufferSize()} should be used to determine
 199  * the appropriate buffer sizes.  The size of the outbound application
 200  * data buffer generally does not matter.  If buffer conditions do not
 201  * allow for the proper consumption/production of data, the application
 202  * must determine (via {@link SSLEngineResult}) and correct the
 203  * problem, and then try the call again.
 204  * <P>
 205  * For example, {@code unwrap()} will return a {@link
 206  * SSLEngineResult.Status#BUFFER_OVERFLOW} result if the engine
 207  * determines that there is not enough destination buffer space available.
 208  * Applications should call {@link SSLSession#getApplicationBufferSize()}
 209  * and compare that value with the space available in the destination buffer,
 210  * enlarging the buffer if necessary.  Similarly, if {@code unwrap()}
 211  * were to return a {@link SSLEngineResult.Status#BUFFER_UNDERFLOW}, the
 212  * application should call {@link SSLSession#getPacketBufferSize()} to ensure
 213  * that the source buffer has enough room to hold a record (enlarging if
 214  * necessary), and then obtain more inbound data.
 215  *
 216  * <pre>{@code
 217  *   SSLEngineResult r = engine.unwrap(src, dst);
 218  *   switch (r.getStatus()) {
 219  *   BUFFER_OVERFLOW:
 220  *       // Could attempt to drain the dst buffer of any already obtained
 221  *       // data, but we'll just increase it to the size needed.
 222  *       int appSize = engine.getSession().getApplicationBufferSize();
 223  *       ByteBuffer b = ByteBuffer.allocate(appSize + dst.position());
 224  *       dst.flip();
 225  *       b.put(dst);
 226  *       dst = b;
 227  *       // retry the operation.
 228  *       break;
 229  *   BUFFER_UNDERFLOW:
 230  *       int netSize = engine.getSession().getPacketBufferSize();
 231  *       // Resize buffer if needed.
 232  *       if (netSize > dst.capacity()) {
 233  *           ByteBuffer b = ByteBuffer.allocate(netSize);
 234  *           src.flip();
 235  *           b.put(src);
 236  *           src = b;
 237  *       }
 238  *       // Obtain more inbound network data for src,
 239  *       // then retry the operation.
 240  *       break;
 241  *   // other cases: CLOSED, OK.
 242  *   }
 243  * }</pre>
 244  *
 245  * <P>
 246  * Unlike {@code SSLSocket}, all methods of SSLEngine are
 247  * non-blocking.  {@code SSLEngine} implementations may
 248  * require the results of tasks that may take an extended period of
 249  * time to complete, or may even block.  For example, a TrustManager
 250  * may need to connect to a remote certificate validation service,
 251  * or a KeyManager might need to prompt a user to determine which
 252  * certificate to use as part of client authentication.  Additionally,
 253  * creating cryptographic signatures and verifying them can be slow,
 254  * seemingly blocking.
 255  * <P>
 256  * For any operation which may potentially block, the
 257  * {@code SSLEngine} will create a {@link java.lang.Runnable}
 258  * delegated task.  When {@code SSLEngineResult} indicates that a
 259  * delegated task result is needed, the application must call {@link
 260  * #getDelegatedTask()} to obtain an outstanding delegated task and
 261  * call its {@link java.lang.Runnable#run() run()} method (possibly using
 262  * a different thread depending on the compute strategy).  The
 263  * application should continue obtaining delegated tasks until no more
 264  * exist, and try the original operation again.
 265  * <P>
 266  * At the end of a communication session, applications should properly
 267  * close the SSL/TLS/DTLS link.  The SSL/TLS/DTLS protocols have closure
 268  * handshake messages, and these messages should be communicated to the
 269  * peer before releasing the {@code SSLEngine} and closing the
 270  * underlying transport mechanism.  A close can be initiated by one of:
 271  * an SSLException, an inbound closure handshake message, or one of the
 272  * close methods.  In all cases, closure handshake messages are
 273  * generated by the engine, and {@code wrap()} should be repeatedly
 274  * called until the resulting {@code SSLEngineResult}'s status
 275  * returns "CLOSED", or {@link #isOutboundDone()} returns true.  All
 276  * data obtained from the {@code wrap()} method should be sent to the
 277  * peer.
 278  * <P>
 279  * {@link #closeOutbound()} is used to signal the engine that the
 280  * application will not be sending any more data.
 281  * <P>
 282  * A peer will signal its intent to close by sending its own closure
 283  * handshake message.  After this message has been received and
 284  * processed by the local {@code SSLEngine}'s {@code unwrap()}
 285  * call, the application can detect the close by calling
 286  * {@code unwrap()} and looking for a {@code SSLEngineResult}
 287  * with status "CLOSED", or if {@link #isInboundDone()} returns true.
 288  * If for some reason the peer closes the communication link without
 289  * sending the proper SSL/TLS/DTLS closure message, the application can
 290  * detect the end-of-stream and can signal the engine via {@link
 291  * #closeInbound()} that there will no more inbound messages to
 292  * process.  Some applications might choose to require orderly shutdown
 293  * messages from a peer, in which case they can check that the closure
 294  * was generated by a handshake message and not by an end-of-stream
 295  * condition.
 296  * <P>
 297  * There are two groups of cipher suites which you will need to know
 298  * about when managing cipher suites:
 299  *
 300  * <UL>
 301  *      <LI> <em>Supported</em> cipher suites:  all the suites which are
 302  *      supported by the SSL implementation.  This list is reported
 303  *      using {@link #getSupportedCipherSuites()}.
 304  *
 305  *      <LI> <em>Enabled</em> cipher suites, which may be fewer than
 306  *      the full set of supported suites.  This group is set using the
 307  *      {@link #setEnabledCipherSuites(String [])} method, and
 308  *      queried using the {@link #getEnabledCipherSuites()} method.
 309  *      Initially, a default set of cipher suites will be enabled on a
 310  *      new engine that represents the minimum suggested
 311  *      configuration.
 312  * </UL>
 313  *
 314  * Implementation defaults require that only cipher suites which
 315  * authenticate servers and provide confidentiality be enabled by
 316  * default.  Only if both sides explicitly agree to unauthenticated
 317  * and/or non-private (unencrypted) communications will such a
 318  * cipher suite be selected.
 319  * <P>
 320  * Each SSL/TLS/DTLS connection must have one client and one server, thus
 321  * each endpoint must decide which role to assume.  This choice determines
 322  * who begins the handshaking process as well as which type of messages
 323  * should be sent by each party.  The method {@link
 324  * #setUseClientMode(boolean)} configures the mode.  Once the initial
 325  * handshaking has started, an {@code SSLEngine} can not switch
 326  * between client and server modes, even when performing renegotiations.
 327  * <P>
 328  * Applications might choose to process delegated tasks in different
 329  * threads.  When an {@code SSLEngine}
 330  * is created, the current {@link java.security.AccessControlContext}
 331  * is saved.  All future delegated tasks will be processed using this
 332  * context:  that is, all access control decisions will be made using the
 333  * context captured at engine creation.
 334  *
 335  * <HR>
 336  *
 337  * <B>Concurrency Notes</B>:
 338  * There are two concurrency issues to be aware of:
 339  *
 340  * <OL>
 341  *      <li>The {@code wrap()} and {@code unwrap()} methods
 342  *      may execute concurrently of each other.
 343  *
 344  *      <li> The SSL/TLS/DTLS protocols employ ordered packets.
 345  *      Applications must take care to ensure that generated packets
 346  *      are delivered in sequence.  If packets arrive
 347  *      out-of-order, unexpected or fatal results may occur.
 348  * <P>
 349  *      For example:
 350  *
 351  *      <pre>
 352  *              synchronized (outboundLock) {
 353  *                  sslEngine.wrap(src, dst);
 354  *                  outboundQueue.put(dst);
 355  *              }
 356  *      </pre>
 357  *
 358  *      As a corollary, two threads must not attempt to call the same method
 359  *      (either {@code wrap()} or {@code unwrap()}) concurrently,
 360  *      because there is no way to guarantee the eventual packet ordering.
 361  * </OL>
 362  *
 363  * @see SSLContext
 364  * @see SSLSocket
 365  * @see SSLServerSocket
 366  * @see SSLSession
 367  * @see java.net.Socket
 368  *
 369  * @since 1.5
 370  * @author Brad R. Wetmore
 371  */
 372 
 373 public abstract class SSLEngine {
 374 
 375     private String peerHost = null;
 376     private int peerPort = -1;
 377 
 378     /**
 379      * Constructor for an {@code SSLEngine} providing no hints
 380      * for an internal session reuse strategy.
 381      *
 382      * @see     SSLContext#createSSLEngine()
 383      * @see     SSLSessionContext
 384      */
 385     protected SSLEngine() {
 386     }
 387 
 388     /**
 389      * Constructor for an {@code SSLEngine}.
 390      * <P>
 391      * {@code SSLEngine} implementations may use the
 392      * {@code peerHost} and {@code peerPort} parameters as hints
 393      * for their internal session reuse strategy.
 394      * <P>
 395      * Some cipher suites (such as Kerberos) require remote hostname
 396      * information. Implementations of this class should use this
 397      * constructor to use Kerberos.
 398      * <P>
 399      * The parameters are not authenticated by the
 400      * {@code SSLEngine}.
 401      *
 402      * @param   peerHost the name of the peer host
 403      * @param   peerPort the port number of the peer
 404      * @see     SSLContext#createSSLEngine(String, int)
 405      * @see     SSLSessionContext
 406      */
 407     protected SSLEngine(String peerHost, int peerPort) {
 408         this.peerHost = peerHost;
 409         this.peerPort = peerPort;
 410     }
 411 
 412     /**
 413      * Returns the host name of the peer.
 414      * <P>
 415      * Note that the value is not authenticated, and should not be
 416      * relied upon.
 417      *
 418      * @return  the host name of the peer, or null if nothing is
 419      *          available.
 420      */
 421     public String getPeerHost() {
 422         return peerHost;
 423     }
 424 
 425     /**
 426      * Returns the port number of the peer.
 427      * <P>
 428      * Note that the value is not authenticated, and should not be
 429      * relied upon.
 430      *
 431      * @return  the port number of the peer, or -1 if nothing is
 432      *          available.
 433      */
 434     public int getPeerPort() {
 435         return peerPort;
 436     }
 437 
 438     /**
 439      * Attempts to encode a buffer of plaintext application data into
 440      * SSL/TLS/DTLS network data.
 441      * <P>
 442      * An invocation of this method behaves in exactly the same manner
 443      * as the invocation:
 444      * <blockquote><pre>
 445      * {@link #wrap(ByteBuffer [], int, int, ByteBuffer)
 446      *     engine.wrap(new ByteBuffer [] { src }, 0, 1, dst);}
 447      * </pre></blockquote>
 448      *
 449      * @param   src
 450      *          a {@code ByteBuffer} containing outbound application data
 451      * @param   dst
 452      *          a {@code ByteBuffer} to hold outbound network data
 453      * @return  an {@code SSLEngineResult} describing the result
 454      *          of this operation.
 455      * @throws  SSLException
 456      *          A problem was encountered while processing the
 457      *          data that caused the {@code SSLEngine} to abort.
 458      *          See the class description for more information on
 459      *          engine closure.
 460      * @throws  ReadOnlyBufferException
 461      *          if the {@code dst} buffer is read-only.
 462      * @throws  IllegalArgumentException
 463      *          if either {@code src} or {@code dst}
 464      *          is null.
 465      * @throws  IllegalStateException if the client/server mode
 466      *          has not yet been set.
 467      * @see     #wrap(ByteBuffer [], int, int, ByteBuffer)
 468      */
 469     public SSLEngineResult wrap(ByteBuffer src,
 470             ByteBuffer dst) throws SSLException {
 471         return wrap(new ByteBuffer [] { src }, 0, 1, dst);
 472     }
 473 
 474     /**
 475      * Attempts to encode plaintext bytes from a sequence of data
 476      * buffers into SSL/TLS/DTLS network data.
 477      * <P>
 478      * An invocation of this method behaves in exactly the same manner
 479      * as the invocation:
 480      * <blockquote><pre>
 481      * {@link #wrap(ByteBuffer [], int, int, ByteBuffer)
 482      *     engine.wrap(srcs, 0, srcs.length, dst);}
 483      * </pre></blockquote>
 484      *
 485      * @param   srcs
 486      *          an array of {@code ByteBuffers} containing the
 487      *          outbound application data
 488      * @param   dst
 489      *          a {@code ByteBuffer} to hold outbound network data
 490      * @return  an {@code SSLEngineResult} describing the result
 491      *          of this operation.
 492      * @throws  SSLException
 493      *          A problem was encountered while processing the
 494      *          data that caused the {@code SSLEngine} to abort.
 495      *          See the class description for more information on
 496      *          engine closure.
 497      * @throws  ReadOnlyBufferException
 498      *          if the {@code dst} buffer is read-only.
 499      * @throws  IllegalArgumentException
 500      *          if either {@code srcs} or {@code dst}
 501      *          is null, or if any element in {@code srcs} is null.
 502      * @throws  IllegalStateException if the client/server mode
 503      *          has not yet been set.
 504      * @see     #wrap(ByteBuffer [], int, int, ByteBuffer)
 505      */
 506     public SSLEngineResult wrap(ByteBuffer [] srcs,
 507             ByteBuffer dst) throws SSLException {
 508         if (srcs == null) {
 509             throw new IllegalArgumentException("src == null");
 510         }
 511         return wrap(srcs, 0, srcs.length, dst);
 512     }
 513 
 514 
 515     /**
 516      * Attempts to encode plaintext bytes from a subsequence of data
 517      * buffers into SSL/TLS/DTLS network data.  This <i>"gathering"</i>
 518      * operation encodes, in a single invocation, a sequence of bytes
 519      * from one or more of a given sequence of buffers.  Gathering
 520      * wraps are often useful when implementing network protocols or
 521      * file formats that, for example, group data into segments
 522      * consisting of one or more fixed-length headers followed by a
 523      * variable-length body.  See
 524      * {@link java.nio.channels.GatheringByteChannel} for more
 525      * information on gathering, and {@link
 526      * java.nio.channels.GatheringByteChannel#write(ByteBuffer[],
 527      * int, int)} for more information on the subsequence
 528      * behavior.
 529      * <P>
 530      * Depending on the state of the SSLEngine, this method may produce
 531      * network data without consuming any application data (for example,
 532      * it may generate handshake data.)
 533      * <P>
 534      * The application is responsible for reliably transporting the
 535      * network data to the peer, and for ensuring that data created by
 536      * multiple calls to wrap() is transported in the same order in which
 537      * it was generated.  The application must properly synchronize
 538      * multiple calls to this method.
 539      * <P>
 540      * If this {@code SSLEngine} has not yet started its initial
 541      * handshake, this method will automatically start the handshake.
 542      * <P>
 543      * This method will attempt to produce SSL/TLS/DTLS records, and will
 544      * consume as much source data as possible, but will never consume
 545      * more than the sum of the bytes remaining in each buffer.  Each
 546      * {@code ByteBuffer}'s position is updated to reflect the
 547      * amount of data consumed or produced.  The limits remain the
 548      * same.
 549      * <P>
 550      * The underlying memory used by the {@code srcs} and
 551      * {@code dst ByteBuffer}s must not be the same.
 552      * <P>
 553      * See the class description for more information on engine closure.
 554      *
 555      * @param   srcs
 556      *          an array of {@code ByteBuffers} containing the
 557      *          outbound application data
 558      * @param   offset
 559      *          The offset within the buffer array of the first buffer from
 560      *          which bytes are to be retrieved; it must be non-negative
 561      *          and no larger than {@code srcs.length}
 562      * @param   length
 563      *          The maximum number of buffers to be accessed; it must be
 564      *          non-negative and no larger than
 565      *          {@code srcs.length}&nbsp;-&nbsp;{@code offset}
 566      * @param   dst
 567      *          a {@code ByteBuffer} to hold outbound network data
 568      * @return  an {@code SSLEngineResult} describing the result
 569      *          of this operation.
 570      * @throws  SSLException
 571      *          A problem was encountered while processing the
 572      *          data that caused the {@code SSLEngine} to abort.
 573      *          See the class description for more information on
 574      *          engine closure.
 575      * @throws  IndexOutOfBoundsException
 576      *          if the preconditions on the {@code offset} and
 577      *          {@code length} parameters do not hold.
 578      * @throws  ReadOnlyBufferException
 579      *          if the {@code dst} buffer is read-only.
 580      * @throws  IllegalArgumentException
 581      *          if either {@code srcs} or {@code dst}
 582      *          is null, or if any element in the {@code srcs}
 583      *          subsequence specified is null.
 584      * @throws  IllegalStateException if the client/server mode
 585      *          has not yet been set.
 586      * @see     java.nio.channels.GatheringByteChannel
 587      * @see     java.nio.channels.GatheringByteChannel#write(
 588      *              ByteBuffer[], int, int)
 589      */
 590     public abstract SSLEngineResult wrap(ByteBuffer [] srcs, int offset,
 591             int length, ByteBuffer dst) throws SSLException;
 592 
 593     /**
 594      * Attempts to decode SSL/TLS/DTLS network data into a plaintext
 595      * application data buffer.
 596      * <P>
 597      * An invocation of this method behaves in exactly the same manner
 598      * as the invocation:
 599      * <blockquote><pre>
 600      * {@link #unwrap(ByteBuffer, ByteBuffer [], int, int)
 601      *     engine.unwrap(src, new ByteBuffer [] { dst }, 0, 1);}
 602      * </pre></blockquote>
 603      *
 604      * @param   src
 605      *          a {@code ByteBuffer} containing inbound network data.
 606      * @param   dst
 607      *          a {@code ByteBuffer} to hold inbound application data.
 608      * @return  an {@code SSLEngineResult} describing the result
 609      *          of this operation.
 610      * @throws  SSLException
 611      *          A problem was encountered while processing the
 612      *          data that caused the {@code SSLEngine} to abort.
 613      *          See the class description for more information on
 614      *          engine closure.
 615      * @throws  ReadOnlyBufferException
 616      *          if the {@code dst} buffer is read-only.
 617      * @throws  IllegalArgumentException
 618      *          if either {@code src} or {@code dst}
 619      *          is null.
 620      * @throws  IllegalStateException if the client/server mode
 621      *          has not yet been set.
 622      * @see     #unwrap(ByteBuffer, ByteBuffer [], int, int)
 623      */
 624     public SSLEngineResult unwrap(ByteBuffer src,
 625             ByteBuffer dst) throws SSLException {
 626         return unwrap(src, new ByteBuffer [] { dst }, 0, 1);
 627     }
 628 
 629     /**
 630      * Attempts to decode SSL/TLS/DTLS network data into a sequence of plaintext
 631      * application data buffers.
 632      * <P>
 633      * An invocation of this method behaves in exactly the same manner
 634      * as the invocation:
 635      * <blockquote><pre>
 636      * {@link #unwrap(ByteBuffer, ByteBuffer [], int, int)
 637      *     engine.unwrap(src, dsts, 0, dsts.length);}
 638      * </pre></blockquote>
 639      *
 640      * @param   src
 641      *          a {@code ByteBuffer} containing inbound network data.
 642      * @param   dsts
 643      *          an array of {@code ByteBuffer}s to hold inbound
 644      *          application data.
 645      * @return  an {@code SSLEngineResult} describing the result
 646      *          of this operation.
 647      * @throws  SSLException
 648      *          A problem was encountered while processing the
 649      *          data that caused the {@code SSLEngine} to abort.
 650      *          See the class description for more information on
 651      *          engine closure.
 652      * @throws  ReadOnlyBufferException
 653      *          if any of the {@code dst} buffers are read-only.
 654      * @throws  IllegalArgumentException
 655      *          if either {@code src} or {@code dsts}
 656      *          is null, or if any element in {@code dsts} is null.
 657      * @throws  IllegalStateException if the client/server mode
 658      *          has not yet been set.
 659      * @see     #unwrap(ByteBuffer, ByteBuffer [], int, int)
 660      */
 661     public SSLEngineResult unwrap(ByteBuffer src,
 662             ByteBuffer [] dsts) throws SSLException {
 663         if (dsts == null) {
 664             throw new IllegalArgumentException("dsts == null");
 665         }
 666         return unwrap(src, dsts, 0, dsts.length);
 667     }
 668 
 669     /**
 670      * Attempts to decode SSL/TLS/DTLS network data into a subsequence of
 671      * plaintext application data buffers.  This <i>"scattering"</i>
 672      * operation decodes, in a single invocation, a sequence of bytes
 673      * into one or more of a given sequence of buffers.  Scattering
 674      * unwraps are often useful when implementing network protocols or
 675      * file formats that, for example, group data into segments
 676      * consisting of one or more fixed-length headers followed by a
 677      * variable-length body.  See
 678      * {@link java.nio.channels.ScatteringByteChannel} for more
 679      * information on scattering, and {@link
 680      * java.nio.channels.ScatteringByteChannel#read(ByteBuffer[],
 681      * int, int)} for more information on the subsequence
 682      * behavior.
 683      * <P>
 684      * Depending on the state of the SSLEngine, this method may consume
 685      * network data without producing any application data (for example,
 686      * it may consume handshake data.)
 687      * <P>
 688      * The application is responsible for reliably obtaining the network
 689      * data from the peer, and for invoking unwrap() on the data in the
 690      * order it was received.  The application must properly synchronize
 691      * multiple calls to this method.
 692      * <P>
 693      * If this {@code SSLEngine} has not yet started its initial
 694      * handshake, this method will automatically start the handshake.
 695      * <P>
 696      * This method will attempt to consume one complete SSL/TLS/DTLS network
 697      * packet, but will never consume more than the sum of the bytes
 698      * remaining in the buffers.  Each {@code ByteBuffer}'s
 699      * position is updated to reflect the amount of data consumed or
 700      * produced.  The limits remain the same.
 701      * <P>
 702      * The underlying memory used by the {@code src} and
 703      * {@code dsts ByteBuffer}s must not be the same.
 704      * <P>
 705      * The inbound network buffer may be modified as a result of this
 706      * call:  therefore if the network data packet is required for some
 707      * secondary purpose, the data should be duplicated before calling this
 708      * method.  Note:  the network data will not be useful to a second
 709      * SSLEngine, as each SSLEngine contains unique random state which
 710      * influences the SSL/TLS/DTLS messages.
 711      * <P>
 712      * See the class description for more information on engine closure.
 713      *
 714      * @param   src
 715      *          a {@code ByteBuffer} containing inbound network data.
 716      * @param   dsts
 717      *          an array of {@code ByteBuffer}s to hold inbound
 718      *          application data.
 719      * @param   offset
 720      *          The offset within the buffer array of the first buffer from
 721      *          which bytes are to be transferred; it must be non-negative
 722      *          and no larger than {@code dsts.length}.
 723      * @param   length
 724      *          The maximum number of buffers to be accessed; it must be
 725      *          non-negative and no larger than
 726      *          {@code dsts.length}&nbsp;-&nbsp;{@code offset}.
 727      * @return  an {@code SSLEngineResult} describing the result
 728      *          of this operation.
 729      * @throws  SSLException
 730      *          A problem was encountered while processing the
 731      *          data that caused the {@code SSLEngine} to abort.
 732      *          See the class description for more information on
 733      *          engine closure.
 734      * @throws  IndexOutOfBoundsException
 735      *          If the preconditions on the {@code offset} and
 736      *          {@code length} parameters do not hold.
 737      * @throws  ReadOnlyBufferException
 738      *          if any of the {@code dst} buffers are read-only.
 739      * @throws  IllegalArgumentException
 740      *          if either {@code src} or {@code dsts}
 741      *          is null, or if any element in the {@code dsts}
 742      *          subsequence specified is null.
 743      * @throws  IllegalStateException if the client/server mode
 744      *          has not yet been set.
 745      * @see     java.nio.channels.ScatteringByteChannel
 746      * @see     java.nio.channels.ScatteringByteChannel#read(
 747      *              ByteBuffer[], int, int)
 748      */
 749     public abstract SSLEngineResult unwrap(ByteBuffer src,
 750             ByteBuffer [] dsts, int offset, int length) throws SSLException;
 751 
 752 
 753     /**
 754      * Returns a delegated {@code Runnable} task for
 755      * this {@code SSLEngine}.
 756      * <P>
 757      * {@code SSLEngine} operations may require the results of
 758      * operations that block, or may take an extended period of time to
 759      * complete.  This method is used to obtain an outstanding {@link
 760      * java.lang.Runnable} operation (task).  Each task must be assigned
 761      * a thread (possibly the current) to perform the {@link
 762      * java.lang.Runnable#run() run} operation.  Once the
 763      * {@code run} method returns, the {@code Runnable} object
 764      * is no longer needed and may be discarded.
 765      * <P>
 766      * Delegated tasks run in the {@code AccessControlContext}
 767      * in place when this object was created.
 768      * <P>
 769      * A call to this method will return each outstanding task
 770      * exactly once.
 771      * <P>
 772      * Multiple delegated tasks can be run in parallel.
 773      *
 774      * @return  a delegated {@code Runnable} task, or null
 775      *          if none are available.
 776      */
 777     public abstract Runnable getDelegatedTask();
 778 
 779 
 780     /**
 781      * Signals that no more inbound network data will be sent
 782      * to this {@code SSLEngine}.
 783      * <P>
 784      * If the application initiated the closing process by calling
 785      * {@link #closeOutbound()}, under some circumstances it is not
 786      * required that the initiator wait for the peer's corresponding
 787      * close message.  (See section 7.2.1 of the TLS specification (<A
 788      * HREF="http://www.ietf.org/rfc/rfc2246.txt">RFC 2246</A>) for more
 789      * information on waiting for closure alerts.)  In such cases, this
 790      * method need not be called.
 791      * <P>
 792      * But if the application did not initiate the closure process, or
 793      * if the circumstances above do not apply, this method should be
 794      * called whenever the end of the SSL/TLS/DTLS data stream is reached.
 795      * This ensures closure of the inbound side, and checks that the
 796      * peer followed the SSL/TLS/DTLS close procedure properly, thus
 797      * detecting possible truncation attacks.
 798      * <P>
 799      * This method is idempotent:  if the inbound side has already
 800      * been closed, this method does not do anything.
 801      * <P>
 802      * {@link #wrap(ByteBuffer, ByteBuffer) wrap()} should be
 803      * called to flush any remaining handshake data.
 804      *
 805      * @throws  SSLException
 806      *          if this engine has not received the proper SSL/TLS/DTLS close
 807      *          notification message from the peer.
 808      *
 809      * @see     #isInboundDone()
 810      * @see     #isOutboundDone()
 811      */
 812     public abstract void closeInbound() throws SSLException;
 813 
 814 
 815     /**
 816      * Returns whether {@link #unwrap(ByteBuffer, ByteBuffer)} will
 817      * accept any more inbound data messages.
 818      *
 819      * @return  true if the {@code SSLEngine} will not
 820      *          consume anymore network data (and by implication,
 821      *          will not produce any more application data.)
 822      * @see     #closeInbound()
 823      */
 824     public abstract boolean isInboundDone();
 825 
 826 
 827     /**
 828      * Signals that no more outbound application data will be sent
 829      * on this {@code SSLEngine}.
 830      * <P>
 831      * This method is idempotent:  if the outbound side has already
 832      * been closed, this method does not do anything.
 833      * <P>
 834      * {@link #wrap(ByteBuffer, ByteBuffer)} should be
 835      * called to flush any remaining handshake data.
 836      *
 837      * @see     #isOutboundDone()
 838      */
 839     public abstract void closeOutbound();
 840 
 841 
 842     /**
 843      * Returns whether {@link #wrap(ByteBuffer, ByteBuffer)} will
 844      * produce any more outbound data messages.
 845      * <P>
 846      * Note that during the closure phase, a {@code SSLEngine} may
 847      * generate handshake closure data that must be sent to the peer.
 848      * {@code wrap()} must be called to generate this data.  When
 849      * this method returns true, no more outbound data will be created.
 850      *
 851      * @return  true if the {@code SSLEngine} will not produce
 852      *          any more network data
 853      *
 854      * @see     #closeOutbound()
 855      * @see     #closeInbound()
 856      */
 857     public abstract boolean isOutboundDone();
 858 
 859 
 860     /**
 861      * Returns the names of the cipher suites which could be enabled for use
 862      * on this engine.  Normally, only a subset of these will actually
 863      * be enabled by default, since this list may include cipher suites which
 864      * do not meet quality of service requirements for those defaults.  Such
 865      * cipher suites might be useful in specialized applications.
 866      * <P>
 867      * The returned array includes cipher suites from the list of standard
 868      * cipher suite names in the <a href=
 869      * "{@docRoot}/../specs/security/standard-names.html#jsse-cipher-suite-names">
 870      * JSSE Cipher Suite Names</a> section of the Java Cryptography
 871      * Architecture Standard Algorithm Name Documentation, and may also
 872      * include other cipher suites that the provider supports.
 873      *
 874      * @return  an array of cipher suite names
 875      * @see     #getEnabledCipherSuites()
 876      * @see     #setEnabledCipherSuites(String [])
 877      */
 878     public abstract String [] getSupportedCipherSuites();
 879 
 880 
 881     /**
 882      * Returns the names of the SSL cipher suites which are currently
 883      * enabled for use on this engine.  When an SSLEngine is first
 884      * created, all enabled cipher suites support a minimum quality of
 885      * service.  Thus, in some environments this value might be empty.
 886      * <P>
 887      * Note that even if a suite is enabled, it may never be used. This
 888      * can occur if the peer does not support it, or its use is restricted,
 889      * or the requisite certificates (and private keys) for the suite are
 890      * not available, or an anonymous suite is enabled but authentication
 891      * is required.
 892      * <P>
 893      * The returned array includes cipher suites from the list of standard
 894      * cipher suite names in the <a href=
 895      * "{@docRoot}/../specs/security/standard-names.html#jsse-cipher-suite-names">
 896      * JSSE Cipher Suite Names</a> section of the Java Cryptography
 897      * Architecture Standard Algorithm Name Documentation, and may also
 898      * include other cipher suites that the provider supports.
 899      *
 900      * @return  an array of cipher suite names
 901      * @see     #getSupportedCipherSuites()
 902      * @see     #setEnabledCipherSuites(String [])
 903      */
 904     public abstract String [] getEnabledCipherSuites();
 905 
 906 
 907     /**
 908      * Sets the cipher suites enabled for use on this engine.
 909      * <P>
 910      * Each cipher suite in the {@code suites} parameter must have
 911      * been listed by getSupportedCipherSuites(), or the method will
 912      * fail.  Following a successful call to this method, only suites
 913      * listed in the {@code suites} parameter are enabled for use.
 914      * <P>
 915      * Note that the standard list of cipher suite names may be found in the
 916      * <a href=
 917      * "{@docRoot}/../specs/security/standard-names.html#jsse-cipher-suite-names">
 918      * JSSE Cipher Suite Names</a> section of the Java Cryptography
 919      * Architecture Standard Algorithm Name Documentation.  Providers
 920      * may support cipher suite names not found in this list or might not
 921      * use the recommended name for a certain cipher suite.
 922      * <P>
 923      * See {@link #getEnabledCipherSuites()} for more information
 924      * on why a specific cipher suite may never be used on a engine.
 925      *
 926      * @param   suites Names of all the cipher suites to enable
 927      * @throws  IllegalArgumentException when one or more of the ciphers
 928      *          named by the parameter is not supported, or when the
 929      *          parameter is null.
 930      * @see     #getSupportedCipherSuites()
 931      * @see     #getEnabledCipherSuites()
 932      */
 933     public abstract void setEnabledCipherSuites(String suites []);
 934 
 935 
 936     /**
 937      * Returns the names of the protocols which could be enabled for use
 938      * with this {@code SSLEngine}.
 939      *
 940      * @return  an array of protocols supported
 941      */
 942     public abstract String [] getSupportedProtocols();
 943 
 944 
 945     /**
 946      * Returns the names of the protocol versions which are currently
 947      * enabled for use with this {@code SSLEngine}.
 948      * <P>
 949      * Note that even if a protocol is enabled, it may never be used.
 950      * This can occur if the peer does not support the protocol, or its
 951      * use is restricted, or there are no enabled cipher suites supported
 952      * by the protocol.
 953      *
 954      * @return  an array of protocols
 955      * @see     #setEnabledProtocols(String [])
 956      */
 957     public abstract String [] getEnabledProtocols();
 958 
 959 
 960     /**
 961      * Set the protocol versions enabled for use on this engine.
 962      * <P>
 963      * The protocols must have been listed by getSupportedProtocols()
 964      * as being supported.  Following a successful call to this method,
 965      * only protocols listed in the {@code protocols} parameter
 966      * are enabled for use.
 967      *
 968      * @param   protocols Names of all the protocols to enable.
 969      * @throws  IllegalArgumentException when one or more of
 970      *          the protocols named by the parameter is not supported or
 971      *          when the protocols parameter is null.
 972      * @see     #getEnabledProtocols()
 973      */
 974     public abstract void setEnabledProtocols(String protocols[]);
 975 
 976 
 977     /**
 978      * Returns the {@code SSLSession} in use in this
 979      * {@code SSLEngine}.
 980      * <P>
 981      * These can be long lived, and frequently correspond to an entire
 982      * login session for some user.  The session specifies a particular
 983      * cipher suite which is being actively used by all connections in
 984      * that session, as well as the identities of the session's client
 985      * and server.
 986      * <P>
 987      * Unlike {@link SSLSocket#getSession()}
 988      * this method does not block until handshaking is complete.
 989      * <P>
 990      * Until the initial handshake has completed, this method returns
 991      * a session object which reports an invalid cipher suite of
 992      * "SSL_NULL_WITH_NULL_NULL".
 993      *
 994      * @return  the {@code SSLSession} for this {@code SSLEngine}
 995      * @see     SSLSession
 996      */
 997     public abstract SSLSession getSession();
 998 
 999 
1000     /**
1001      * Returns the {@code SSLSession} being constructed during a SSL/TLS/DTLS
1002      * handshake.
1003      * <p>
1004      * TLS/DTLS protocols may negotiate parameters that are needed when using
1005      * an instance of this class, but before the {@code SSLSession} has
1006      * been completely initialized and made available via {@code getSession}.
1007      * For example, the list of valid signature algorithms may restrict
1008      * the type of certificates that can used during TrustManager
1009      * decisions, or the maximum TLS/DTLS fragment packet sizes can be
1010      * resized to better support the network environment.
1011      * <p>
1012      * This method provides early access to the {@code SSLSession} being
1013      * constructed.  Depending on how far the handshake has progressed,
1014      * some data may not yet be available for use.  For example, if a
1015      * remote server will be sending a Certificate chain, but that chain
1016      * has yet not been processed, the {@code getPeerCertificates}
1017      * method of {@code SSLSession} will throw a
1018      * SSLPeerUnverifiedException.  Once that chain has been processed,
1019      * {@code getPeerCertificates} will return the proper value.
1020      *
1021      * @see SSLSocket
1022      * @see SSLSession
1023      * @see ExtendedSSLSession
1024      * @see X509ExtendedKeyManager
1025      * @see X509ExtendedTrustManager
1026      *
1027      * @return null if this instance is not currently handshaking, or
1028      *         if the current handshake has not progressed far enough to
1029      *         create a basic SSLSession.  Otherwise, this method returns the
1030      *         {@code SSLSession} currently being negotiated.
1031      * @throws UnsupportedOperationException if the underlying provider
1032      *         does not implement the operation.
1033      *
1034      * @since 1.7
1035      */
1036     public SSLSession getHandshakeSession() {
1037         throw new UnsupportedOperationException();
1038     }
1039 
1040 
1041     /**
1042      * Initiates handshaking (initial or renegotiation) on this SSLEngine.
1043      * <P>
1044      * This method is not needed for the initial handshake, as the
1045      * {@code wrap()} and {@code unwrap()} methods will
1046      * implicitly call this method if handshaking has not already begun.
1047      * <P>
1048      * Note that the peer may also request a session renegotiation with
1049      * this {@code SSLEngine} by sending the appropriate
1050      * session renegotiate handshake message.
1051      * <P>
1052      * Unlike the {@link SSLSocket#startHandshake()
1053      * SSLSocket#startHandshake()} method, this method does not block
1054      * until handshaking is completed.
1055      * <P>
1056      * To force a complete SSL/TLS/DTLS session renegotiation, the current
1057      * session should be invalidated prior to calling this method.
1058      * <P>
1059      * Some protocols may not support multiple handshakes on an existing
1060      * engine and may throw an {@code SSLException}.
1061      *
1062      * @throws  SSLException
1063      *          if a problem was encountered while signaling the
1064      *          {@code SSLEngine} to begin a new handshake.
1065      *          See the class description for more information on
1066      *          engine closure.
1067      * @throws  IllegalStateException if the client/server mode
1068      *          has not yet been set.
1069      * @see     SSLSession#invalidate()
1070      */
1071     public abstract void beginHandshake() throws SSLException;
1072 
1073 
1074     /**
1075      * Returns the current handshake status for this {@code SSLEngine}.
1076      *
1077      * @return  the current {@code SSLEngineResult.HandshakeStatus}.
1078      */
1079     public abstract SSLEngineResult.HandshakeStatus getHandshakeStatus();
1080 
1081 
1082     /**
1083      * Configures the engine to use client (or server) mode when
1084      * handshaking.
1085      * <P>
1086      * This method must be called before any handshaking occurs.
1087      * Once handshaking has begun, the mode can not be reset for the
1088      * life of this engine.
1089      * <P>
1090      * Servers normally authenticate themselves, and clients
1091      * are not required to do so.
1092      *
1093      * @param   mode true if the engine should start its handshaking
1094      *          in "client" mode
1095      * @throws  IllegalArgumentException if a mode change is attempted
1096      *          after the initial handshake has begun.
1097      * @see     #getUseClientMode()
1098      */
1099     public abstract void setUseClientMode(boolean mode);
1100 
1101 
1102     /**
1103      * Returns true if the engine is set to use client mode when
1104      * handshaking.
1105      *
1106      * @return  true if the engine should do handshaking
1107      *          in "client" mode
1108      * @see     #setUseClientMode(boolean)
1109      */
1110     public abstract boolean getUseClientMode();
1111 
1112 
1113     /**
1114      * Configures the engine to <i>require</i> client authentication.  This
1115      * option is only useful for engines in the server mode.
1116      * <P>
1117      * An engine's client authentication setting is one of the following:
1118      * <ul>
1119      * <li> client authentication required
1120      * <li> client authentication requested
1121      * <li> no client authentication desired
1122      * </ul>
1123      * <P>
1124      * Unlike {@link #setWantClientAuth(boolean)}, if this option is set and
1125      * the client chooses not to provide authentication information
1126      * about itself, <i>the negotiations will stop and the engine will
1127      * begin its closure procedure</i>.
1128      * <P>
1129      * Calling this method overrides any previous setting made by
1130      * this method or {@link #setWantClientAuth(boolean)}.
1131      *
1132      * @param   need set to true if client authentication is required,
1133      *          or false if no client authentication is desired.
1134      * @see     #getNeedClientAuth()
1135      * @see     #setWantClientAuth(boolean)
1136      * @see     #getWantClientAuth()
1137      * @see     #setUseClientMode(boolean)
1138      */
1139     public abstract void setNeedClientAuth(boolean need);
1140 
1141 
1142     /**
1143      * Returns true if the engine will <i>require</i> client authentication.
1144      * This option is only useful to engines in the server mode.
1145      *
1146      * @return  true if client authentication is required,
1147      *          or false if no client authentication is desired.
1148      * @see     #setNeedClientAuth(boolean)
1149      * @see     #setWantClientAuth(boolean)
1150      * @see     #getWantClientAuth()
1151      * @see     #setUseClientMode(boolean)
1152      */
1153     public abstract boolean getNeedClientAuth();
1154 
1155 
1156     /**
1157      * Configures the engine to <i>request</i> client authentication.
1158      * This option is only useful for engines in the server mode.
1159      * <P>
1160      * An engine's client authentication setting is one of the following:
1161      * <ul>
1162      * <li> client authentication required
1163      * <li> client authentication requested
1164      * <li> no client authentication desired
1165      * </ul>
1166      * <P>
1167      * Unlike {@link #setNeedClientAuth(boolean)}, if this option is set and
1168      * the client chooses not to provide authentication information
1169      * about itself, <i>the negotiations will continue</i>.
1170      * <P>
1171      * Calling this method overrides any previous setting made by
1172      * this method or {@link #setNeedClientAuth(boolean)}.
1173      *
1174      * @param   want set to true if client authentication is requested,
1175      *          or false if no client authentication is desired.
1176      * @see     #getWantClientAuth()
1177      * @see     #setNeedClientAuth(boolean)
1178      * @see     #getNeedClientAuth()
1179      * @see     #setUseClientMode(boolean)
1180      */
1181     public abstract void setWantClientAuth(boolean want);
1182 
1183 
1184     /**
1185      * Returns true if the engine will <i>request</i> client authentication.
1186      * This option is only useful for engines in the server mode.
1187      *
1188      * @return  true if client authentication is requested,
1189      *          or false if no client authentication is desired.
1190      * @see     #setNeedClientAuth(boolean)
1191      * @see     #getNeedClientAuth()
1192      * @see     #setWantClientAuth(boolean)
1193      * @see     #setUseClientMode(boolean)
1194      */
1195     public abstract boolean getWantClientAuth();
1196 
1197 
1198     /**
1199      * Controls whether new SSL sessions may be established by this engine.
1200      * If session creations are not allowed, and there are no
1201      * existing sessions to resume, there will be no successful
1202      * handshaking.
1203      *
1204      * @param   flag true indicates that sessions may be created; this
1205      *          is the default.  false indicates that an existing session
1206      *          must be resumed
1207      * @see     #getEnableSessionCreation()
1208      */
1209     public abstract void setEnableSessionCreation(boolean flag);
1210 
1211 
1212     /**
1213      * Returns true if new SSL sessions may be established by this engine.
1214      *
1215      * @return  true indicates that sessions may be created; this
1216      *          is the default.  false indicates that an existing session
1217      *          must be resumed
1218      * @see     #setEnableSessionCreation(boolean)
1219      */
1220     public abstract boolean getEnableSessionCreation();
1221 
1222     /**
1223      * Returns the SSLParameters in effect for this SSLEngine.
1224      * The ciphersuites and protocols of the returned SSLParameters
1225      * are always non-null.
1226      *
1227      * @return the SSLParameters in effect for this SSLEngine.
1228      * @since 1.6
1229      */
1230     public SSLParameters getSSLParameters() {
1231         SSLParameters params = new SSLParameters();
1232         params.setCipherSuites(getEnabledCipherSuites());
1233         params.setProtocols(getEnabledProtocols());
1234         if (getNeedClientAuth()) {
1235             params.setNeedClientAuth(true);
1236         } else if (getWantClientAuth()) {
1237             params.setWantClientAuth(true);
1238         }
1239         return params;
1240     }
1241 
1242     /**
1243      * Applies SSLParameters to this engine.
1244      *
1245      * <p>This means:
1246      * <ul>
1247      * <li>If {@code params.getCipherSuites()} is non-null,
1248      *   {@code setEnabledCipherSuites()} is called with that value.</li>
1249      * <li>If {@code params.getProtocols()} is non-null,
1250      *   {@code setEnabledProtocols()} is called with that value.</li>
1251      * <li>If {@code params.getNeedClientAuth()} or
1252      *   {@code params.getWantClientAuth()} return {@code true},
1253      *   {@code setNeedClientAuth(true)} and
1254      *   {@code setWantClientAuth(true)} are called, respectively;
1255      *   otherwise {@code setWantClientAuth(false)} is called.</li>
1256      * <li>If {@code params.getServerNames()} is non-null, the engine will
1257      *   configure its server names with that value.</li>
1258      * <li>If {@code params.getSNIMatchers()} is non-null, the engine will
1259      *   configure its SNI matchers with that value.</li>
1260      * </ul>
1261      *
1262      * @param params the parameters
1263      * @throws IllegalArgumentException if the setEnabledCipherSuites() or
1264      *    the setEnabledProtocols() call fails
1265      * @since 1.6
1266      */
1267     public void setSSLParameters(SSLParameters params) {
1268         String[] s;
1269         s = params.getCipherSuites();
1270         if (s != null) {
1271             setEnabledCipherSuites(s);
1272         }
1273         s = params.getProtocols();
1274         if (s != null) {
1275             setEnabledProtocols(s);
1276         }
1277         if (params.getNeedClientAuth()) {
1278             setNeedClientAuth(true);
1279         } else if (params.getWantClientAuth()) {
1280             setWantClientAuth(true);
1281         } else {
1282             setWantClientAuth(false);
1283         }
1284     }
1285 
1286     /**
1287      * Returns the most recent application protocol value negotiated for this
1288      * connection.
1289      * <p>
1290      * If supported by the underlying SSL/TLS/DTLS implementation,
1291      * application name negotiation mechanisms such as <a
1292      * href="http://www.ietf.org/rfc/rfc7301.txt"> RFC 7301 </a>, the
1293      * Application-Layer Protocol Negotiation (ALPN), can negotiate
1294      * application-level values between peers.
1295      * <p>
1296      * @implSpec
1297      * The implementation in this class throws
1298      * {@code UnsupportedOperationException} and performs no other action.
1299      *
1300      * @return null if it has not yet been determined if application
1301      *         protocols might be used for this connection, an empty
1302      *         {@code String} if application protocols values will not
1303      *         be used, or a non-empty application protocol {@code String}
1304      *         if a value was successfully negotiated.
1305      * @throws UnsupportedOperationException if the underlying provider
1306      *         does not implement the operation.
1307      * @since 9
1308      */
1309     public String getApplicationProtocol() {
1310         throw new UnsupportedOperationException();
1311     }
1312 
1313     /**
1314      * Returns the application protocol value negotiated on a SSL/TLS
1315      * handshake currently in progress.
1316      * <p>
1317      * Like {@link #getHandshakeSession()},
1318      * a connection may be in the middle of a handshake. The
1319      * application protocol may or may not yet be available.
1320      * <p>
1321      * @implSpec
1322      * The implementation in this class throws
1323      * {@code UnsupportedOperationException} and performs no other action.
1324      *
1325      * @return null if it has not yet been determined if application
1326      *         protocols might be used for this handshake, an empty
1327      *         {@code String} if application protocols values will not
1328      *         be used, or a non-empty application protocol {@code String}
1329      *         if a value was successfully negotiated.
1330      * @throws UnsupportedOperationException if the underlying provider
1331      *         does not implement the operation.
1332      * @since 9
1333      */
1334     public String getHandshakeApplicationProtocol() {
1335         throw new UnsupportedOperationException();
1336     }
1337 
1338     /**
1339      * Registers a callback function that selects an application protocol
1340      * value for a SSL/TLS/DTLS handshake.
1341      * The function overrides any values supplied using
1342      * {@link SSLParameters#setApplicationProtocols
1343      * SSLParameters.setApplicationProtocols} and it supports the following
1344      * type parameters:
1345      * <blockquote>
1346      * <dl>
1347      * <dt> {@code SSLEngine}
1348      * <dd> The function's first argument allows the current {@code SSLEngine}
1349      *      to be inspected, including the handshake session and configuration
1350      *      settings.
1351      * <dt> {@code List<String>}
1352      * <dd> The function's second argument lists the application protocol names
1353      *      advertised by the TLS peer.
1354      * <dt> {@code String}
1355      * <dd> The function's result is an application protocol name, or null to
1356      *      indicate that none of the advertised names are acceptable.
1357      *      If the return value is an empty {@code String} then application
1358      *      protocol indications will not be used.
1359      *      If the return value is null (no value chosen) or is a value that
1360      *      was not advertised by the peer, the underlying protocol will
1361      *      determine what action to take. (For example, ALPN will send a
1362      *      "no_application_protocol" alert and terminate the connection.)
1363      * </dl>
1364      * </blockquote>
1365      *
1366      * For example, the following call registers a callback function that
1367      * examines the TLS handshake parameters and selects an application protocol
1368      * name:
1369      * <pre>{@code
1370      *     serverEngine.setHandshakeApplicationProtocolSelector(
1371      *         (serverEngine, clientProtocols) -> {
1372      *             SSLSession session = serverEngine.getHandshakeSession();
1373      *             return chooseApplicationProtocol(
1374      *                 serverEngine,
1375      *                 clientProtocols,
1376      *                 session.getProtocol(),
1377      *                 session.getCipherSuite());
1378      *         });
1379      * }</pre>
1380      *
1381      * @apiNote
1382      * This method should be called by TLS server applications before the TLS
1383      * handshake begins. Also, this {@code SSLEngine} should be configured with
1384      * parameters that are compatible with the application protocol selected by
1385      * the callback function. For example, enabling a poor choice of cipher
1386      * suites could result in no suitable application protocol.
1387      * See {@link SSLParameters}.
1388      *
1389      * @implSpec
1390      * The implementation in this class throws
1391      * {@code UnsupportedOperationException} and performs no other action.
1392      *
1393      * @param selector the callback function, or null to disable the callback
1394      *         functionality.
1395      * @throws UnsupportedOperationException if the underlying provider
1396      *         does not implement the operation.
1397      * @since 9
1398      */
1399     public void setHandshakeApplicationProtocolSelector(
1400             BiFunction<SSLEngine, List<String>, String> selector) {
1401         throw new UnsupportedOperationException();
1402     }
1403 
1404     /**
1405      * Retrieves the callback function that selects an application protocol
1406      * value during a SSL/TLS/DTLS handshake.
1407      * See {@link #setHandshakeApplicationProtocolSelector
1408      * setHandshakeApplicationProtocolSelector}
1409      * for the function's type parameters.
1410      *
1411      * @implSpec
1412      * The implementation in this class throws
1413      * {@code UnsupportedOperationException} and performs no other action.
1414      *
1415      * @return the callback function, or null if none has been set.
1416      * @throws UnsupportedOperationException if the underlying provider
1417      *         does not implement the operation.
1418      * @since 9
1419      */
1420     public BiFunction<SSLEngine, List<String>, String>
1421             getHandshakeApplicationProtocolSelector() {
1422         throw new UnsupportedOperationException();
1423     }
1424 }