package org.apache.cassandra.security;

import javax.net.ssl.SSLContext;
import javax.net.ssl.SSLException;

import io.netty.handler.ssl.CipherSuiteFilter;
import io.netty.handler.ssl.SslContext;
import org.apache.cassandra.config.EncryptionOptions;

/**
 * The purpose of this interface is to provide pluggable mechanism for creating custom JSSE and Netty SSLContext
 * objects. Please use the Cassandra configuration key {@code ssl_context_factory/**
 * The purpose of this interface is to provide pluggable mechanism for creating custom JSSE and Netty SSLContext
 * objects. Please use the Cassandra configuration key {@code ssl_context_factory} as part of {@code
 * client_encryption_options}/{@code server_encryption_options} and provide a custom class-name
 * implementing this
 * interface with parameters to be used to plugin a your own way to load the SSLContext.
 *
 * Implementation of this interface must have a constructor with argument of type {@code Map<String,String>Object>} to allow
 * custom parameters, needed by the implementation, to be passed from the Cassandra yaml configuration.
 Common *SSL
 * Sinceconfigurations onlike top{@code ofprotocol, Nettyalgorithm, Cassandra is internally cipher_suites, accepted_protocols, require_client_auth,
 * require_endpoint_verification, enabled, optional} will also be passed to that map by Cassanddra.
 *
 * Since on top of Netty, Cassandra is internally using JSSE SSLContext also for certain use-cases- this interface
 * has methods for both.
 *
 * Below is an example of how to configure a custom implementation with parameters
 * <pre>
 * ssl_context_factory:
 *       class_name: org.apache.cassandra.security.YourSslContextFactoryImpl
 *       parameters:
 *         key1: "value1"
 *         key2: "value2"
 *         key3: "value3"
 * </pre>
 */
public interface ISslContextFactory
{
    /**
     * Creates JSSE SSLContext.
     *
     * @param options EncryptionOptions that could be used for the SSL context creation
     * @param buildTruststore {@code true} if the caller requires Truststore; {@code false} otherwise
     * @return
     * @throws SSLException in case the Ssl Context creation fails for some reason
     */
    SSLContext createJSSESslContext(EncryptionOptions options, boolean buildTruststore) throws SSLException;

    /**
     * Creates Netty's SslContext object.
     *
     * @param optionsbuildTruststore EncryptionOptions{@code thattrue} couldif bethe usedcaller forrequires the SSL context creation
     * @param buildTruststore {@code true} if the caller requires Truststore; Truststore; {@code false} otherwise
     * @param socketType {@link SocketType} for Netty's Inbound or Outbound channels
     * @param useOpenSsl {@code true} if openSsl is enabled;{@code false} otherwise
     * @param cipherFilter to allow Netty's cipher suite filtering, e.g.
     * {@link io.netty.handler.ssl.SslContextBuilder#ciphers(Iterable, CipherSuiteFilter)}
     * @return
     * @throws SSLException in case the Ssl Context creation fails for some reason
     */
    SslContext createNettySslContext(EncryptionOptions options, boolean buildTruststore, SocketType socketType,
                                     boolean useOpenSsl, CipherSuiteFilter cipherFilter) throws SSLException;

    /**
     * Initializes hot reloading of the security keys/certs. The implementation must guarantee this to be thread safe.
     * @param@throws optionsSSLException
 Client encryption options (Native Protocol)*/
     * @throws SSLException
     */
    void initHotReloading(EncryptionOptions optionsvoid initHotReloading() throws SSLException;

    /**
     * Returns if any changes require the reloading of the SSL context returned by this factory.
     * This will be called by Cassandra's periodic polling for any potential changes that will reload the SSL context
     * . However only newer connections established after the reload will use the reloaded SSL context.
     * @return
     */
    boolean shouldReload();

    /**
     * Returns if this factory uses private keystore.
     * @param options Encryption options
     * @return {@code true} by default unless the implementation overrides this
     */
    default boolean hasKeystore(EncryptionOptions options) {
        return true;
    }

    /**
     * IndicatesReturns ifthe theprepared processlist holdsof the inbound/listening end of the socket ({@link SSLFactory.SocketType#SERVER})), oraccepted protocols.
     * @return array of protocol names suitable for passing to Netty's SslContextBuilder.protocols, or null if the
     * outbounddefault
   side ({@link SSLFactory.SocketType#CLIENT}). */
    List<String> getAcceptedProtocols();

     /**/
    enum SocketType* {
Returns the list of cipher suites supported by SERVER, CLIENT;the implementation.
     * }
}

@return
     */
    List<String> getCipherSuites();

    /**
     * Indicates if the process holds the inbound/listening end of the socket ({@link SSLFactory.SocketType#SERVER})), or the
     * outbound side ({@link SSLFactory.SocketType#CLIENT}).
     */
    enum SocketType {
        SERVER, CLIENT;
    }
}