/* -*- Mode: C; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
/*
 *     Copyright 2014 Couchbase, Inc.
 *
 *   Licensed 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.
 */

#ifndef LCB_SSL_H
#define LCB_SSL_H
#include <lcbio/connect.h>
#ifdef __cplusplus
extern "C" {
#endif

/**
 * @file
 * @brief SSL Socket Routines
 */

/**
 * @ingroup lcbio
 * @defgroup lcbio-ssl SSL Routines
 *
 * @details
 * This file contains the higher level API interfacing with _LCBIO_. It provides
 * APIs to "patch" a socket with SSL as well as establish settings for SSL
 * encryption.
 *
 * @addtogroup lcbio-ssl
 * @{
 */


/** @brief Wrapper around OpenSSL's `SSL_CTX` */
typedef struct lcbio_SSLCTX *lcbio_pSSLCTX;

/**
 * @brief Determine if SSL is supported in the current build
 * @return true if supported, false otherwise
 */
int
lcbio_ssl_supported(void);

lcbio_pSSLCTX
lcbio_ssl_new__fallback(const char *, int, lcb_error_t *, lcb_settings *);

#ifndef LCB_NO_SSL
/**
 * Create a new SSL context to be used to establish SSL policy.
 * @param cafile Optional path to CA file
 * @param noverify To not attempt to verify server's certificate
 * @param errp a pointer to contain the error code if initialization failed
 * @param settings settings structure, used for logging.
 *
 * @return A new SSL context, or NULL on error.
 */
lcbio_pSSLCTX
lcbio_ssl_new(const char *cafile, int noverify, lcb_error_t *errp,
    lcb_settings *settings);
#else
#define lcbio_ssl_new lcbio_ssl_new__fallback
#endif


/**
 * Free the SSL context. This should be done when libcouchbase has nothing else
 * to do with the certificate
 * @param ctx
 */
void
lcbio_ssl_free(lcbio_pSSLCTX ctx);

/**
 * Apply the SSL settings to a given socket.
 *
 * The socket must be newly connected and must not have already been initialized
 * with SSL (i.e. lcbio_ssl_check() returns false).
 *
 * @param sock The socket to which SSL should be applied
 * @param sctx The context returned by lcbio_ssl_new()
 * @return
 */
lcb_error_t
lcbio_ssl_apply(lcbio_SOCKET *sock, lcbio_pSSLCTX sctx);

/**
 * Checks whether the given socket is using SSL
 * @param sock The socket to check
 * @return true if using SSL, false if plain (or not yet applied)
 */
LCB_INTERNAL_API
int
lcbio_ssl_check(lcbio_SOCKET *sock);

/**
 * Retrieves the internal error code from the SSL object within the socket.
 * Should only be called if lcbio_ssl_check() is true.
 *
 * @param sock
 * @return An error code (if present), or LCB_SUCCESS if there is no internal
 * error code.
 */
LCB_INTERNAL_API
lcb_error_t
lcbio_ssl_get_error(lcbio_SOCKET *sock);

/**
 * @brief
 * Initialize any application-level globals needed for SSL support
 * @todo There is currently nothing checking if this hasn't been called more
 * than once.
 */
void
lcbio_ssl_global_init(void);

struct lcb_settings_st;

/**
 * Apply SSL to the socket if the socket should use SSL and is not already
 * an SSL socket. This is a convenience function that:
 *
 * 1. Checks the settings to see if SSL is enabled
 * 2. Checks to see if the socket already has SSL (lcbio_ssl_check())
 * 3. Calls lcbio_ssl_apply if (1) and (2) are true.
 *
 * @param sock The socket to SSLify
 * @param settings The settings structure from whence the context and policy are
 * derived.
 * @return
 */
lcb_error_t
lcbio_sslify_if_needed(lcbio_SOCKET *sock, struct lcb_settings_st *settings);

/**@}*/

#ifdef __cplusplus
}
#endif
#endif
