/*
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You under the Apache License, Version 2.0
 *  (the "License"); you may not use this file except in compliance with
 *  the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

 package javax.net.ssl;

import java.nio.ByteBuffer;
import java.nio.ReadOnlyBufferException;

/**
 * The abstract implementation of secure communications using SSL, TLS, or other
 * protocols. It includes the setup, handshake, and encrypt/decrypt functionality
 * needed to create a secure connection.
 * 
 * @since Android 1.0
 */
public abstract class SSLEngine {
    // Store host value
    private final String host;

    // Store port value
    private final int port;

    /**
     * Creates a new {@code SSLEngine} instance.
     * 
     * @since Android 1.0
     */
    protected SSLEngine() {
        host = null;
        port = -1;
    }

    /**
     * Creates a new {@code SSLEngine} instance with the specified host and
     * port.
     * 
     * @param host
     *            the name of the host.
     * @param port
     *            the port of the host.
     * @since Android 1.0
     */
    protected SSLEngine(String host, int port) {
        this.host = host;
        this.port = port;
    }

    /**
     * Initiates a handshake on this engine.
     * <p>
     * Calling this method is not needed for the initial handshake: it will be
     * called by {@code wrap} or {@code unwrap} if the initial handshake has not
     * been started yet.
     * </p>
     * 
     * @throws SSLException
     *             if starting the handshake fails.
     * @throws IllegalStateException
     *             if the engine does not have all the needed settings (e.g.
     *             client/server mode not set).
     * @since Android 1.0
     */
    public abstract void beginHandshake() throws SSLException;

    /**
     * Notifies this engine instance that no more inbound network data will be
     * sent to this engine.
     * 
     * @throws SSLException
     *             if this engine did not receive a needed protocol specific
     *             close notification message from the peer.
     * @since Android 1.0
     */
    public abstract void closeInbound() throws SSLException;

    /**
     * Notifies this engine instance that no more outbound application data will
     * be sent to this engine.
     * 
     * @since Android 1.0
     */
    public abstract void closeOutbound();

    /**
     * Returns a delegate task for this engine instance. Some engine operations
     * may require the results of blocking or long running operations, and the
     * {@code SSLEngineResult} instances returned by this engine may indicate
     * that a delegated task result is needed. In this case the
     * {@link Runnable#run() run} method of the returned {@code Runnable}
     * delegated task must be called.
     * 
     * @return a delegate task, or {@code null} if none are available.
     * @since Android 1.0
     */
    public abstract Runnable getDelegatedTask();

    /**
     * Returns the SSL cipher suite names that are enabled in this engine
     * instance.
     * 
     * @return the SSL cipher suite names that are enabled in this engine
     *         instance.
     * @since Android 1.0
     */
    public abstract String[] getEnabledCipherSuites();

    /**
     * Returns the protocol version names that are enabled in this engine
     * instance.
     * 
     * @return the protocol version names that are enabled in this engine
     *         instance.
     * @since Android 1.0
     */
    public abstract String[] getEnabledProtocols();

    /**
     * Returns whether new SSL sessions may be established by this engine.
     * 
     * @return {@code true} if new session may be established, {@code false} if
     *         existing sessions must be reused.
     * @since Android 1.0
     */
    public abstract boolean getEnableSessionCreation();

    /**
     * Returns the status of the handshake of this engine instance.
     * 
     * @return the status of the handshake of this engine instance.
     * @since Android 1.0
     */
    public abstract SSLEngineResult.HandshakeStatus getHandshakeStatus();

    /**
     * Returns whether this engine instance will require client authentication.
     * 
     * @return {@code true} if this engine will require client authentication,
     *         {@code false} if no client authentication is needed.
     * @since Android 1.0
     */
    public abstract boolean getNeedClientAuth();

    /**
     * Returns the name of the peer host.
     * 
     * @return the name of the peer host, or {@code null} if none is available.
     * @since Android 1.0
     */
    public String getPeerHost() {
        return host;
    }

    /**
     * Returns the port number of the peer host.
     * 
     * @return the port number of the peer host, or {@code -1} is none is
     *         available.
     * @since Android 1.0
     */
    public int getPeerPort() {
        return port;
    }

    /**
     * Returns the SSL session for this engine instance.
     * 
     * @return the SSL session for this engine instance.
     * @since Android 1.0
     */
    public abstract SSLSession getSession();

    /**
     * Returns the SSL cipher suite names that are supported by this engine.
     * These cipher suites can be enabled using
     * {@link #setEnabledCipherSuites(String[])}.
     * 
     * @return the SSL cipher suite names that are supported by this engine.
     * @since Android 1.0
     */
    public abstract String[] getSupportedCipherSuites();

    /**
     * Returns the protocol names that are supported by this engine. These
     * protocols can be enables using {@link #setEnabledProtocols(String[])}.
     * 
     * @return the protocol names that are supported by this engine.
     * @since Android 1.0
     */
    public abstract String[] getSupportedProtocols();

    /**
     * Returns whether this engine is set to act in client mode when
     * handshaking.
     * 
     * @return {@code true} if the engine is set to do handshaking in client
     *         mode.
     * @since Android 1.0
     */
    public abstract boolean getUseClientMode();

    /**
     * Returns whether this engine will request client authentication.
     * 
     * @return {@code true} if client authentication will be requested,
     *         {@code false} otherwise.
     * @since Android 1.0
     */
    public abstract boolean getWantClientAuth();

    /**
     * Returns whether no more inbound data will be accepted by this engine.
     * 
     * @return {@code true} if no more inbound data will be accepted by this
     *         engine, {@code false} otherwise.
     * @since Android 1.0
     */
    public abstract boolean isInboundDone();

    /**
     * Returns whether no more outbound data will be produced by this engine.
     * 
     * @return {@code true} if no more outbound data will be producted by this
     *         engine, {@code otherwise} false.
     * @since Android 1.0
     */
    public abstract boolean isOutboundDone();

    /**
     * Sets the SSL cipher suite names that should be enabled in this engine
     * instance. Only cipher suites listed by {@code getSupportedCipherSuites()}
     * are allowed.
     * 
     * @param suites
     *            the SSL cipher suite names to be enabled.
     * @throws IllegalArgumentException
     *             if one of the specified cipher suites is not supported, or if
     *             {@code suites} is {@code null}.
     * @since Android 1.0
     */
    public abstract void setEnabledCipherSuites(String[] suites);

    /**
     * Sets the protocol version names that should be enabled in this engine
     * instance. Only protocols listed by {@code getSupportedProtocols()} are
     * allowed.
     * 
     * @param protocols
     *            the protocol version names to be enabled.
     * @throws IllegalArgumentException
     *             if one of the protocol version names is not supported, or if
     *             {@code protocols} is {@code null}.
     * @since Android 1.0
     */
    public abstract void setEnabledProtocols(String[] protocols);

    /**
     * Sets whether new SSL sessions may be established by this engine instance.
     * 
     * @param flag
     *            {@code true} if new SSL sessions may be established,
     *            {@code false} if existing SSL sessions must be reused.
     * @since Android 1.0
     */
    public abstract void setEnableSessionCreation(boolean flag);

    /**
     * Sets whether this engine must require client authentication. The client
     * authentication is one of:
     * <ul>
     * <li>authentication required</li>
     * <li>authentication requested</li>
     * <li>no authentication needed</li>
     * </ul>
     * This method overrides the setting of {@link #setWantClientAuth(boolean)}.
     * 
     * @param need
     *            {@code true} if client authentication is required,
     *            {@code false} if no authentication is needed.
     * @since Android 1.0
     */
    public abstract void setNeedClientAuth(boolean need);

    /**
     * Sets whether this engine should act in client (or server) mode when
     * handshaking.
     * 
     * @param mode
     *            {@code true} if this engine should act in client mode,
     *            {@code false} if not.
     * @throws IllegalArgumentException
     *             if this method is called after starting the initial
     *             handshake.
     * @since Android 1.0
     */
    public abstract void setUseClientMode(boolean mode);

    /**
     * Sets whether this engine should request client authentication. The client
     * authentication is one of the following:
     * <ul>
     * <li>authentication required</li>
     * <li>authentication requested</li>
     * <li>no authentication needed</li>
     * </ul>
     * This method overrides the setting of {@link #setNeedClientAuth(boolean)}.
     * 
     * @param want
     *            {@code true} if client authentication should be requested,
     *            {@code false} if no authentication is needed.
     * @since Android 1.0
     */
    public abstract void setWantClientAuth(boolean want);

    /**
     * Decodes the incoming network data buffer into application data buffers.
     * If a handshake has not been started yet, it will automatically be
     * started.
     * 
     * @param src
     *            the buffer with incoming network data
     * @param dsts
     *            the array of destination buffers for incoming application
     *            data.
     * @param offset
     *            the offset in the array of destination buffers to which data
     *            is to be transferred.
     * @param length
     *            the maximum number of destination buffers to be used. 
     * @return the result object of this operation.
     * @throws SSLException
     *             if a problem occurred while processing the data.
     * @throws IndexOutOfBoundsException
     *             if {@code length} is greater than
     *             {@code dsts.length - offset}.
     * @throws ReadOnlyBufferException
     *             if one of the destination buffers is read-only.
     * @throws IllegalArgumentException
     *             if {@code src}, {@code dsts}, or one of the entries in
     *             {@code dsts} is {@code null}.
     * @throws IllegalStateException
     *             if the engine does not have all the needed settings (e.g.
     *             client/server mode not set).
     * @since Android 1.0
     */
    public abstract SSLEngineResult unwrap(ByteBuffer src, ByteBuffer[] dsts,
            int offset, int length) throws SSLException;

    /**
     * Encodes the outgoing application data buffers into the network data
     * buffer. If a handshake has not been started yet, it will automatically be
     * started.
     * 
     * @param srcs
     *            the array of source buffers of outgoing application data.
     * @param offset
     *            the offset in the array of source buffers from which data is
     *            to be retrieved.
     * @param length
     *            the maximum number of source buffers to be used.
     * @param dst
     *            the destination buffer for network data.
     * @return the result object of this operation.
     * @throws SSLException
     *             if a problem occurred while processing the data.
     * @throws IndexOutOfBoundsException
     *             if {@code length} is greater than
     *             {@code srcs.length - offset}.
     * @throws ReadOnlyBufferException
     *             if the destination buffer is readonly.
     * @throws IllegalArgumentException
     *             if {@code srcs}, {@code dst}, or one the entries in
     *             {@code srcs} is {@code null}.
     * @throws IllegalStateException
     *             if the engine does not have all the needed settings (e.g.
     *             client/server mode not set).
     * @since Android 1.0
     */
    public abstract SSLEngineResult wrap(ByteBuffer[] srcs, int offset,
            int length, ByteBuffer dst) throws SSLException;

    /**
     * Decodes the incoming network data buffer into the application data
     * buffer. If a handshake has not been started yet, it will automatically be
     * started.
     * 
     * @param src
     *            the buffer with incoming network data
     * @param dst
     *            the destination buffer for incoming application data.
     * @return the result object of this operation.
     * @throws SSLException
     *             if a problem occurred while processing the data.
     * @throws ReadOnlyBufferException
     *             if one of the destination buffers is read-only.
     * @throws IllegalArgumentException
     *             if {@code src} or {@code dst} is {@code null}.
     * @throws IllegalStateException
     *             if the engine does not have all the needed settings (e.g.
     *             client/server mode not set).
     * @since Android 1.0
     */
    public SSLEngineResult unwrap(ByteBuffer src, ByteBuffer dst)
            throws SSLException {
//        if (src == null) {
//            throw new IllegalArgumentException("Byte buffer src is null");
//        }
//        if (dst == null) {
//            throw new IllegalArgumentException("Byte buffer dst is null");
//        }
//        if (dst.isReadOnly()) {
//            throw new ReadOnlyBufferException();
//        }
        return unwrap(src, new ByteBuffer[] { dst }, 0, 1);
    }

    /**
     * Decodes the incoming network data buffer into the application data
     * buffers. If a handshake has not been started yet, it will automatically
     * be started.
     * 
     * @param src
     *            the buffer with incoming network data
     * @param dsts
     *            the array of destination buffers for incoming application
     *            data.
     * @return the result object of this operation.
     * @throws SSLException
     *             if a problem occurred while processing the data.
     * @throws ReadOnlyBufferException
     *             if one of the destination buffers is read-only.
     * @throws IllegalArgumentException
     *             if {@code src} or {@code dsts} is {@code null}.
     * @throws IllegalStateException
     *             if the engine does not have all the needed settings (e.g.
     *             client/server mode not set).
     * @since Android 1.0
     */
    public SSLEngineResult unwrap(ByteBuffer src, ByteBuffer[] dsts)
            throws SSLException {
//        if (src == null) {
//            throw new IllegalArgumentException("Byte buffer src is null");
//        }
        if (dsts == null) {
            throw new IllegalArgumentException("Byte buffer array dsts is null");
        }
//        for (int i = 0; i < dsts.length; i++) {
//            if (dsts[i] == null) {
//                throw new IllegalArgumentException("Byte buffer dsts[" + i
//                        + "]  is null");
//            }
//            if (dsts[i].isReadOnly()) {
//                throw new ReadOnlyBufferException();
//            }
//        }
        return unwrap(src, dsts, 0, dsts.length);
    }

    /**
     * Encodes the outgoing application data buffers into the network data
     * buffer. If a handshake has not been started yet, it will automatically be
     * started.
     * 
     * @param srcs
     *            the array of source buffers of outgoing application data.
     * @param dst
     *            the destination buffer for network data.
     * @return the result object of this operation.
     * @throws SSLException
     *             if a problem occurred while processing the data.
     * @throws ReadOnlyBufferException
     *             if the destination buffer is readonly.
     * @throws IllegalArgumentException
     *             if {@code srcs} or {@code dst} is {@code null}.
     * @throws IllegalStateException
     *             if the engine does not have all the needed settings (e.g.
     *             client/server mode not set).
     * @since Android 1.0
     */
    public SSLEngineResult wrap(ByteBuffer[] srcs, ByteBuffer dst)
            throws SSLException {
        if (srcs == null) {
            throw new IllegalArgumentException("Byte buffer array srcs is null");
        }
//        for (int i = 0; i < srcs.length; i++) {
//            if (srcs[i] == null) {
//                throw new IllegalArgumentException("Byte buffer srcs[" + i
//                        + "]  is null");
//            }
//        }
//        if (dst == null) {
//            throw new IllegalArgumentException("Byte buffer array dst is null");
//        }
//        if (dst.isReadOnly()) {
//            throw new ReadOnlyBufferException();
//        }
        return wrap(srcs, 0, srcs.length, dst);
    }

    /**
     * Encodes the outgoing application data buffer into the network data
     * buffer. If a handshake has not been started yet, it will automatically be
     * started.
     * 
     * @param src
     *            the source buffers of outgoing application data.
     * @param dst
     *            the destination buffer for network data.
     * @return the result object of this operation.
     * @throws SSLException
     *             if a problem occurred while processing the data.
     * @throws ReadOnlyBufferException
     *             if the destination buffer is readonly.
     * @throws IllegalArgumentException
     *             if {@code src} or {@code dst} is {@code null}.
     * @throws IllegalStateException
     *             if the engine does not have all the needed settings (e.g.
     *             client/server mode not set).
     * @since Android 1.0
     */
    public SSLEngineResult wrap(ByteBuffer src, ByteBuffer dst)
            throws SSLException {
//        if (src == null) {
//            throw new IllegalArgumentException("Byte buffer src is null");
//        }
//        if (dst == null) {
//            throw new IllegalArgumentException("Byte buffer dst is null");
//        }
//        if (dst.isReadOnly()) {
//            throw new ReadOnlyBufferException();
//        }
        return wrap(new ByteBuffer[] { src }, 0, 1, dst);
    }
}