/*

 * Copyright (c) 2003, 2012, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package javax.net.ssl;

import java.nio.ByteBuffer;

import java.nio.ReadOnlyBufferException;

/**

 * A class which enables secure communications using protocols such as

 * the Secure Sockets Layer (SSL) or

 * <A HREF="http://www.ietf.org/rfc/rfc2246.txt"> IETF RFC 2246 "Transport

 * Layer Security" (TLS) </A> protocols, but is transport independent.

 * <P>

 * The secure communications modes include: <UL>

 *

 *      <LI> <em>Integrity Protection</em>.  SSL/TLS protects against

 *      modification of messages by an active wiretapper.

 *

 *      <LI> <em>Authentication</em>.  In most modes, SSL/TLS provides

 *      peer authentication.  Servers are usually authenticated, and

 *      clients may be authenticated as requested by servers.

 *

 *      <LI> <em>Confidentiality (Privacy Protection)</em>.  In most

 *      modes, SSL/TLS encrypts data being sent between client and

 *      server.  This protects the confidentiality of data, so that

 *      passive wiretappers won't see sensitive data such as financial

 *      information or personal information of many kinds.

 *

 *      </UL>

 *

 * These kinds of protection are specified by a "cipher suite", which

 * is a combination of cryptographic algorithms used by a given SSL

 * connection.  During the negotiation process, the two endpoints must

 * agree on a cipher suite that is available in both environments.  If

 * there is no such suite in common, no SSL connection can be

 * established, and no data can be exchanged.

 * <P>

 * The cipher suite used is established by a negotiation process called

 * "handshaking".  The goal of this process is to create or rejoin a

 * "session", which may protect many connections over time.  After

 * handshaking has completed, you can access session attributes by

 * using the {@link #getSession()} method.

 * <P>

 * The <code>SSLSocket</code> class provides much of the same security

 * functionality, but all of the inbound and outbound data is

 * automatically transported using the underlying {@link

 * java.net.Socket Socket}, which by design uses a blocking model.

 * While this is appropriate for many applications, this model does not

 * provide the scalability required by large servers.

 * <P>

 * The primary distinction of an <code>SSLEngine</code> is that it

 * operates on inbound and outbound byte streams, independent of the

 * transport mechanism.  It is the responsibility of the

 * <code>SSLEngine</code> user to arrange for reliable I/O transport to

 * the peer.  By separating the SSL/TLS abstraction from the I/O

 * transport mechanism, the <code>SSLEngine</code> can be used for a

 * wide variety of I/O types, such as {@link

 * java.nio.channels.spi.AbstractSelectableChannel#configureBlocking(boolean)

 * non-blocking I/O (polling)}, {@link java.nio.channels.Selector

 * selectable non-blocking I/O}, {@link java.net.Socket Socket} and the

 * traditional Input/OutputStreams, local {@link java.nio.ByteBuffer

 * ByteBuffers} or byte arrays, <A

 * HREF="http://www.jcp.org/en/jsr/detail?id=203"> future asynchronous

 * I/O models </A>, and so on.

 * <P>

 * At a high level, the <code>SSLEngine</code> appears thus:

 *

 * <pre>

 *                   app data

 *

 *                |           ^

 *                |     |     |

 *                v     |     |

 *           +----+-----|-----+----+

 *           |          |          |

 *           |       SSL|Engine    |

 *   wrap()  |          |          |  unwrap()

 *           | OUTBOUND | INBOUND  |

 *           |          |          |

 *           +----+-----|-----+----+

 *                |     |     ^

 *                |     |     |

 *                v           |

 *

 *                   net data

 * </pre>

 * Application data (also known as plaintext or cleartext) is data which

 * is produced or consumed by an application.  Its counterpart is

 * network data, which consists of either handshaking and/or ciphertext

 * (encrypted) data, and destined to be transported via an I/O

 * mechanism.  Inbound data is data which has been received from the

 * peer, and outbound data is destined for the peer.

 * <P>

 * (In the context of an <code>SSLEngine</code>, the term "handshake

 * data" is taken to mean any data exchanged to establish and control a

 * secure connection.  Handshake data includes the SSL/TLS messages

 * "alert", "change_cipher_spec," and "handshake.")

 * <P>

 * There are five distinct phases to an <code>SSLEngine</code>.

 *

 * <OL>

 *     <li> Creation - The <code>SSLEngine</code> has been created and

 *     initialized, but has not yet been used.  During this phase, an

 *     application may set any <code>SSLEngine</code>-specific settings

 *     (enabled cipher suites, whether the <code>SSLEngine</code> should

 *     handshake in client or server mode, and so on).  Once

 *     handshaking has begun, though, any new settings (except

 *     client/server mode, see below) will be used for

 *     the next handshake.

 *

 *     <li> Initial Handshake - The initial handshake is a procedure by

 *     which the two peers exchange communication parameters until an

 *     SSLSession is established.  Application data can not be sent during

 *     this phase.

 *

 *     <li> Application Data - Once the communication parameters have

 *     been established and the handshake is complete, application data

 *     may flow through the <code>SSLEngine</code>.  Outbound

 *     application messages are encrypted and integrity protected,

 *     and inbound messages reverse the process.

 *

 *     <li>  Rehandshaking - Either side may request a renegotiation of

 *     the session at any time during the Application Data phase.  New

 *     handshaking data can be intermixed among the application data.

 *     Before starting the rehandshake phase, the application may

 *     reset the SSL/TLS communication parameters such as the list of

 *     enabled ciphersuites and whether to use client authentication,

 *     but can not change between client/server modes.  As before, once

 *     handshaking has begun, any new <code>SSLEngine</code>

 *     configuration settings will not be used until the next

 *     handshake.

 *

 *     <li>  Closure - When the connection is no longer needed, the

 *     application should close the <code>SSLEngine</code> and should

 *     send/receive any remaining messages to the peer before

 *     closing the underlying transport mechanism.  Once an engine is

 *     closed, it is not reusable:  a new <code>SSLEngine</code> must

 *     be created.

 * </OL>

 * An <code>SSLEngine</code> is created by calling {@link

 * SSLContext#createSSLEngine()} from an initialized

 * <code>SSLContext</code>.  Any configuration

 * parameters should be set before making the first call to

 * <code>wrap()</code>, <code>unwrap()</code>, or

 * <code>beginHandshake()</code>.  These methods all trigger the

 * initial handshake.

 * <P>

 * Data moves through the engine by calling {@link #wrap(ByteBuffer,

 * ByteBuffer) wrap()} or {@link #unwrap(ByteBuffer, ByteBuffer)

 * unwrap()} on outbound or inbound data, respectively.  Depending on

 * the state of the <code>SSLEngine</code>, a <code>wrap()</code> call

 * may consume application data from the source buffer and may produce

 * network data in the destination buffer.  The outbound data

 * may contain application and/or handshake data.  A call to

 * <code>unwrap()</code> will examine the source buffer and may

 * advance the handshake if the data is handshaking information, or

 * may place application data in the destination buffer if the data

 * is application.  The state of the underlying SSL/TLS algorithm

 * will determine when data is consumed and produced.

 * <P>

 * Calls to <code>wrap()</code> and <code>unwrap()</code> return an

 * <code>SSLEngineResult</code> which indicates the status of the

 * operation, and (optionally) how to interact with the engine to make

 * progress.

 * <P>

 * The <code>SSLEngine</code> produces/consumes complete SSL/TLS

 * packets only, and does not store application data internally between

 * calls to <code>wrap()/unwrap()</code>.  Thus input and output

 * <code>ByteBuffer</code>s must be sized appropriately to hold the

 * maximum record that can be produced.  Calls to {@link

 * SSLSession#getPacketBufferSize()} and {@link

 * SSLSession#getApplicationBufferSize()} should be used to determine

 * the appropriate buffer sizes.  The size of the outbound application

 * data buffer generally does not matter.  If buffer conditions do not

 * allow for the proper consumption/production of data, the application

 * must determine (via {@link SSLEngineResult}) and correct the

 * problem, and then try the call again.

 * <P>

 * For example, <code>unwrap()</code> will return a {@link

 * SSLEngineResult.Status#BUFFER_OVERFLOW} result if the engine

 * determines that there is not enough destination buffer space available.

 * Applications should call {@link SSLSession#getApplicationBufferSize()}

 * and compare that value with the space available in the destination buffer,

 * enlarging the buffer if necessary.  Similarly, if <code>unwrap()</code>

 * were to return a {@link SSLEngineResult.Status#BUFFER_UNDERFLOW}, the

 * application should call {@link SSLSession#getPacketBufferSize()} to ensure

 * that the source buffer has enough room to hold a record (enlarging if

 * necessary), and then obtain more inbound data.

 *

 *   SSLEngineResult r = engine.unwrap(src, dst);

 *   switch (r.getStatus()) {

 *   BUFFER_OVERFLOW:

 *       // Could attempt to drain the dst buffer of any already obtained

 *       // data, but we'll just increase it to the size needed.

 *       int appSize = engine.getSession().getApplicationBufferSize();

 *       ByteBuffer b = ByteBuffer.allocate(appSize + dst.position());

 *       dst.flip();

 *       b.put(dst);

 *       dst = b;

 *       // retry the operation.

 *       break;

 *   BUFFER_UNDERFLOW:

 *       int netSize = engine.getSession().getPacketBufferSize();

 *       // Resize buffer if needed.

 *       if (netSize > dst.capacity()) {

 *           ByteBuffer b = ByteBuffer.allocate(netSize);

 *           src.flip();

 *           b.put(src);

 *           src = b;

 *       }

 *       // Obtain more inbound network data for src,

 *       // then retry the operation.

 *       break;

 *   // other cases: CLOSED, OK.

 *   }

 *

 * <P>

 * Unlike <code>SSLSocket</code>, all methods of SSLEngine are

 * non-blocking.  <code>SSLEngine</code> implementations may

 * require the results of tasks that may take an extended period of

 * time to complete, or may even block.  For example, a TrustManager

 * may need to connect to a remote certificate validation service,

 * or a KeyManager might need to prompt a user to determine which

 * certificate to use as part of client authentication.  Additionally,

 * creating cryptographic signatures and verifying them can be slow,

 * seemingly blocking.

 * <P>

 * For any operation which may potentially block, the

 * <code>SSLEngine</code> will create a {@link java.lang.Runnable}

 * delegated task.  When <code>SSLEngineResult</code> indicates that a

 * delegated task result is needed, the application must call {@link

 * #getDelegatedTask()} to obtain an outstanding delegated task and

 * call its {@link java.lang.Runnable#run() run()} method (possibly using

 * a different thread depending on the compute strategy).  The

 * application should continue obtaining delegated tasks until no more

 * exist, and try the original operation again.

 * <P>

 * At the end of a communication session, applications should properly

 * close the SSL/TLS link.  The SSL/TLS protocols have closure handshake

 * messages, and these messages should be communicated to the peer

 * before releasing the <code>SSLEngine</code> and closing the

 * underlying transport mechanism.  A close can be initiated by one of:

 * an SSLException, an inbound closure handshake message, or one of the

 * close methods.  In all cases, closure handshake messages are

 * generated by the engine, and <code>wrap()</code> should be repeatedly

 * called until the resulting <code>SSLEngineResult</code>'s status

 * returns "CLOSED", or {@link #isOutboundDone()} returns true.  All

 * data obtained from the <code>wrap()</code> method should be sent to the

 * peer.

 * <P>

 * {@link #closeOutbound()} is used to signal the engine that the

 * application will not be sending any more data.

 * <P>

 * A peer will signal its intent to close by sending its own closure

 * handshake message.  After this message has been received and

 * processed by the local <code>SSLEngine</code>'s <code>unwrap()</code>

 * call, the application can detect the close by calling

 * <code>unwrap()</code> and looking for a <code>SSLEngineResult</code>

 * with status "CLOSED", or if {@link #isInboundDone()} returns true.

 * If for some reason the peer closes the communication link without

 * sending the proper SSL/TLS closure message, the application can

 * detect the end-of-stream and can signal the engine via {@link

 * #closeInbound()} that there will no more inbound messages to

 * process.  Some applications might choose to require orderly shutdown

 * messages from a peer, in which case they can check that the closure

 * was generated by a handshake message and not by an end-of-stream

 * condition.

 * <P>

 * There are two groups of cipher suites which you will need to know

 * about when managing cipher suites:

 *

 * <UL>

 *      <LI> <em>Supported</em> cipher suites:  all the suites which are

 *      supported by the SSL implementation.  This list is reported

 *      using {@link #getSupportedCipherSuites()}.

 *

 *      <LI> <em>Enabled</em> cipher suites, which may be fewer than

 *      the full set of supported suites.  This group is set using the

 *      {@link #setEnabledCipherSuites(String [])} method, and

 *      queried using the {@link #getEnabledCipherSuites()} method.

 *      Initially, a default set of cipher suites will be enabled on a

 *      new engine that represents the minimum suggested

 *      configuration.

 * </UL>

 *

 * Implementation defaults require that only cipher suites which

 * authenticate servers and provide confidentiality be enabled by

 * default.  Only if both sides explicitly agree to unauthenticated

 * and/or non-private (unencrypted) communications will such a

 * cipher suite be selected.

 * <P>

 * Each SSL/TLS connection must have one client and one server, thus

 * each endpoint must decide which role to assume.  This choice determines

 * who begins the handshaking process as well as which type of messages

 * should be sent by each party.  The method {@link

 * #setUseClientMode(boolean)} configures the mode.  Once the initial

 * handshaking has started, an <code>SSLEngine</code> can not switch

 * between client and server modes, even when performing renegotiations.

 * <P>

 * Applications might choose to process delegated tasks in different

 * threads.  When an <code>SSLEngine</code>

 * is created, the current {@link java.security.AccessControlContext}

 * is saved.  All future delegated tasks will be processed using this

 * context:  that is, all access control decisions will be made using the

 * context captured at engine creation.

 * <P>

 * <HR>

 *

 * <B>Concurrency Notes</B>:

 * There are two concurrency issues to be aware of:

 *

 * <OL>

 *      <li>The <code>wrap()</code> and <code>unwrap()</code> methods

 *      may execute concurrently of each other.

 *

 *      <li> The SSL/TLS protocols employ ordered packets.

 *      Applications must take care to ensure that generated packets

 *      are delivered in sequence.  If packets arrive

 *      out-of-order, unexpected or fatal results may occur.

 * <P>

 *      For example:

 * <P>

 *      <pre>

 *              synchronized (outboundLock) {

 *                  sslEngine.wrap(src, dst);

 *                  outboundQueue.put(dst);

 *              }

 *      </pre>

 *

 *      As a corollary, two threads must not attempt to call the same method

 *      (either <code>wrap()</code> or <code>unwrap()</code>) concurrently,

 *      because there is no way to guarantee the eventual packet ordering.

 * </OL>

 *

 * @see SSLContext

 * @see SSLSocket

 * @see SSLServerSocket

 * @see SSLSession

 * @see java.net.Socket

 *

 * @since 1.5

 * @author Brad R. Wetmore

 */

public abstract class SSLEngine {

    private String peerHost = null;

    private int peerPort = -1;

    /**

     * Constructor for an <code>SSLEngine</code> providing no hints

     * for an internal session reuse strategy.

     *

     * @see     SSLContext#createSSLEngine()

     * @see     SSLSessionContext

     */

    protected SSLEngine() {

    }

    /**

     * Constructor for an <code>SSLEngine</code>.

     * <P>

     * <code>SSLEngine</code> implementations may use the

     * <code>peerHost</code> and <code>peerPort</code> parameters as hints

     * for their internal session reuse strategy.

     * <P>

     * Some cipher suites (such as Kerberos) require remote hostname

     * information. Implementations of this class should use this

     * constructor to use Kerberos.

     * <P>

     * The parameters are not authenticated by the

     * <code>SSLEngine</code>.

     *

     * @param   peerHost the name of the peer host

     * @param   peerPort the port number of the peer

     * @see     SSLContext#createSSLEngine(String, int)

     * @see     SSLSessionContext

     */

    protected SSLEngine(String peerHost, int peerPort) {

        this.peerHost = peerHost;

        this.peerPort = peerPort;

    }

    /**

     * Returns the host name of the peer.

     * <P>

     * Note that the value is not authenticated, and should not be

     * relied upon.

     *

     * @return  the host name of the peer, or null if nothing is

     *          available.

     */

    public String getPeerHost() {

        return peerHost;

    }

    /**

     * Returns the port number of the peer.

     * <P>

     * Note that the value is not authenticated, and should not be

     * relied upon.

     *

     * @return  the port number of the peer, or -1 if nothing is

     *          available.

     */

    public int getPeerPort() {

        return peerPort;

    }

    /**

     * Attempts to encode a buffer of plaintext application data into

     * SSL/TLS network data.

     * <P>

     * An invocation of this method behaves in exactly the same manner

     * as the invocation:

     * <blockquote><pre>

     * {@link #wrap(ByteBuffer [], int, int, ByteBuffer)

     *     engine.wrap(new ByteBuffer [] { src }, 0, 1, dst);}

     *

     * @param   src

     *          a <code>ByteBuffer</code> containing outbound application data

     * @param   dst

     *          a <code>ByteBuffer</code> to hold outbound network data

     * @return  an <code>SSLEngineResult</code> describing the result

     *          of this operation.

     * @throws  SSLException

     *          A problem was encountered while processing the

     *          data that caused the <code>SSLEngine</code> to abort.

     *          See the class description for more information on

     *          engine closure.

     * @throws  ReadOnlyBufferException

     *          if the <code>dst</code> buffer is read-only.

     * @throws  IllegalArgumentException

     *          if either <code>src</code> or <code>dst</code>

     *          is null.

     * @throws  IllegalStateException if the client/server mode

     *          has not yet been set.

     * @see     #wrap(ByteBuffer [], int, int, ByteBuffer)

     */

    public SSLEngineResult wrap(ByteBuffer src,

            ByteBuffer dst) throws SSLException {

        return wrap(new ByteBuffer [] { src }, 0, 1, dst);

    }

    /**

     * Attempts to encode plaintext bytes from a sequence of data

     * buffers into SSL/TLS network data.

     * <P>

     * An invocation of this method behaves in exactly the same manner

     * as the invocation:

     * <blockquote><pre>

     * {@link #wrap(ByteBuffer [], int, int, ByteBuffer)

     *     engine.wrap(srcs, 0, srcs.length, dst);}

     *

     * @param   srcs

     *          an array of <code>ByteBuffers</code> containing the

     *          outbound application data

     * @param   dst

     *          a <code>ByteBuffer</code> to hold outbound network data

     * @return  an <code>SSLEngineResult</code> describing the result

     *          of this operation.

     * @throws  SSLException

     *          A problem was encountered while processing the

     *          data that caused the <code>SSLEngine</code> to abort.

     *          See the class description for more information on

     *          engine closure.

     * @throws  ReadOnlyBufferException

     *          if the <code>dst</code> buffer is read-only.

     * @throws  IllegalArgumentException

     *          if either <code>srcs</code> or <code>dst</code>

     *          is null, or if any element in <code>srcs</code> is null.

     * @throws  IllegalStateException if the client/server mode

     *          has not yet been set.

     * @see     #wrap(ByteBuffer [], int, int, ByteBuffer)

     */

    public SSLEngineResult wrap(ByteBuffer [] srcs,

            ByteBuffer dst) throws SSLException {

        if (srcs == null) {

            throw new IllegalArgumentException("src == null");

        }

        return wrap(srcs, 0, srcs.length, dst);

    }

    /**

     * Attempts to encode plaintext bytes from a subsequence of data

     * buffers into SSL/TLS network data.  This <i>"gathering"</i>

     * operation encodes, in a single invocation, a sequence of bytes

     * from one or more of a given sequence of buffers.  Gathering

     * wraps are often useful when implementing network protocols or

     * file formats that, for example, group data into segments

     * consisting of one or more fixed-length headers followed by a

     * variable-length body.  See

     * {@link java.nio.channels.GatheringByteChannel} for more

     * information on gathering, and {@link

     * java.nio.channels.GatheringByteChannel#write(ByteBuffer[],

     * int, int)} for more information on the subsequence

     * behavior.

     * <P>