path: root/src/openvpn/ssl_backend.h

/*
 *  OpenVPN -- An application to securely tunnel IP networks
 *             over a single TCP/UDP port, with support for SSL/TLS-based
 *             session authentication and key exchange,
 *             packet encryption, packet authentication, and
 *             packet compression.
 *
 *  Copyright (C) 2002-2021 OpenVPN Inc <sales@openvpn.net>
 *  Copyright (C) 2010-2021 Fox Crypto B.V. <openvpn@foxcrypto.com>
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License version 2
 *  as published by the Free Software Foundation.
 *
 *  This program 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 for more details.
 *
 *  You should have received a copy of the GNU General Public License along
 *  with this program; if not, write to the Free Software Foundation, Inc.,
 *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 */

/**
 * @file Control Channel SSL library backend module
 */


#ifndef SSL_BACKEND_H_
#define SSL_BACKEND_H_

#include "buffer.h"

#ifdef ENABLE_CRYPTO_OPENSSL
#include "ssl_openssl.h"
#include "ssl_verify_openssl.h"
#define SSLAPI SSLAPI_OPENSSL
#endif
#ifdef ENABLE_CRYPTO_MBEDTLS
#include "ssl_mbedtls.h"
#include "ssl_verify_mbedtls.h"
#define SSLAPI SSLAPI_MBEDTLS
#endif

/* Ensure that SSLAPI got a sane value if SSL is disabled or unknown */
#ifndef SSLAPI
#define SSLAPI SSLAPI_NONE
#endif

/**
 *  prototype for struct tls_session from ssl_common.h
 */
struct tls_session;

/**
 * Get a tls_cipher_name_pair containing OpenSSL and IANA names for supplied TLS cipher name
 *
 * @param cipher_name   Can be either OpenSSL or IANA cipher name
 * @return              tls_cipher_name_pair* if found, NULL otherwise
 */
typedef struct { const char *openssl_name; const char *iana_name; } tls_cipher_name_pair;
const tls_cipher_name_pair *tls_get_cipher_name_pair(const char *cipher_name, size_t len);

/*
 *
 * Functions implemented in ssl.c for use by the backend SSL library
 *
 */

/**
 * Callback to retrieve the user's password
 *
 * @param buf           Buffer to return the password in
 * @param size          Size of the buffer
 * @param rwflag        Unused, needed for OpenSSL compatibility
 * @param u             Unused, needed for OpenSSL compatibility
 */
int pem_password_callback(char *buf, int size, int rwflag, void *u);

/*
 *
 * Functions used in ssl.c which must be implemented by the backend SSL library
 *
 */

/**
 * Perform any static initialisation necessary by the library.
 * Called on OpenVPN initialisation
 */
void tls_init_lib(void);

/**
 * Free any global SSL library-specific data structures.
 */
void tls_free_lib(void);

/**
 * Clear the underlying SSL library's error state.
 */
void tls_clear_error(void);

/**
 * Parse a TLS version specifier
 *
 * @param vstr          The TLS version string
 * @param extra         An optional extra parameter, may be NULL
 *
 * @return              One of the TLS_VER_x constants or TLS_VER_BAD
 *                      if a parse error should be flagged.
 */
#define TLS_VER_BAD    -1
#define TLS_VER_UNSPEC  0 /* default */
#define TLS_VER_1_0     1
#define TLS_VER_1_1     2
#define TLS_VER_1_2     3
#define TLS_VER_1_3     4
int tls_version_parse(const char *vstr, const char *extra);

/**
 * Return the maximum TLS version (as a TLS_VER_x constant)
 * supported by current SSL implementation
 *
 * @return              One of the TLS_VER_x constants (but not TLS_VER_BAD).
 */
int tls_version_max(void);

/**
 * Initialise a library-specific TLS context for a server.
 *
 * @param ctx           TLS context to initialise
 */
void tls_ctx_server_new(struct tls_root_ctx *ctx);

/**
 * Initialises a library-specific TLS context for a client.
 *
 * @param ctx           TLS context to initialise
 */
void tls_ctx_client_new(struct tls_root_ctx *ctx);

/**
 * Frees the library-specific TLSv1 context
 *
 * @param ctx           TLS context to free
 */
void tls_ctx_free(struct tls_root_ctx *ctx);

/**
 * Checks whether the given TLS context is initialised
 *
 * @param ctx           TLS context to check
 *
 * @return      true if the context is initialised, false if not.
 */
bool tls_ctx_initialised(struct tls_root_ctx *ctx);

/**
 * Set any library specific options.
 *
 * Examples include disabling session caching, the password callback to use,
 * and session verification parameters.
 *
 * @param ctx           TLS context to set options on
 * @param ssl_flags     SSL flags to set
 *
 * @return true on success, false otherwise.
 */
bool tls_ctx_set_options(struct tls_root_ctx *ctx, unsigned int ssl_flags);

/**
 * Restrict the list of ciphers that can be used within the TLS context for TLS 1.2
 * and below
 *
 * @param ctx           TLS context to restrict, must be valid.
 * @param ciphers       String containing : delimited cipher names, or NULL to use
 *                                      sane defaults.
 */
void tls_ctx_restrict_ciphers(struct tls_root_ctx *ctx, const char *ciphers);

/**
 * Restrict the list of ciphers that can be used within the TLS context for TLS 1.3
 * and higher
 *
 * @param ctx           TLS context to restrict, must be valid.
 * @param ciphers       String containing : delimited cipher names, or NULL to use
 *                                      sane defaults.
 */
void tls_ctx_restrict_ciphers_tls13(struct tls_root_ctx *ctx, const char *ciphers);

/**
 * Set the TLS certificate profile.  The profile defines which crypto
 * algorithms may be used in the supplied certificate.
 *
 * @param ctx           TLS context to restrict, must be valid.
 * @param profile       The profile name ('preferred', 'legacy' or 'suiteb').
 *                      Defaults to 'preferred' if NULL.
 */
void tls_ctx_set_cert_profile(struct tls_root_ctx *ctx, const char *profile);

/**
 * Set the (elliptic curve) group allowed for signatures and
 * key exchange.
 *
 * @param ctx       TLS context to restrict, must be valid.
 * @param groups    List of groups that will be allowed, in priority,
 *                  separated by :
 */
void tls_ctx_set_tls_groups(struct tls_root_ctx *ctx, const char *groups);

/**
 * Check our certificate notBefore and notAfter fields, and warn if the cert is
 * either not yet valid or has expired.  Note that this is a non-fatal error,
 * since we compare against the system time, which might be incorrect.
 *
 * @param ctx           TLS context to get our certificate from.
 */
void tls_ctx_check_cert_time(const struct tls_root_ctx *ctx);

/**
 * Load Diffie Hellman Parameters, and load them into the library-specific
 * TLS context.
 *
 * @param ctx                   TLS context to use
 * @param dh_file               The file name to load the parameters from, or
 *                              a string containing the parameters in the case
 *                              of inline files.
 * @param dh_file_inline        True if dh_file is an inline file.
 */
void tls_ctx_load_dh_params(struct tls_root_ctx *ctx, const char *dh_file,
                            bool dh_file_inline);

/**
 * Load Elliptic Curve Parameters, and load them into the library-specific
 * TLS context.
 *
 * @param ctx          TLS context to use
 * @param curve_name   The name of the elliptic curve to load.
 */
void tls_ctx_load_ecdh_params(struct tls_root_ctx *ctx, const char *curve_name
                              );

/**
 * Load PKCS #12 file for key, cert and (optionally) CA certs, and add to
 * library-specific TLS context.
 *
 * @param ctx                   TLS context to use
 * @param pkcs12_file           The file name to load the information from, or
 *                              a string containing the information in the case
 *                              of inline files.
 * @param pkcs12_file_inline    True if pkcs12_file is an inline file.
 *
 * @return                      1 if an error occurred, 0 if parsing was
 *                              successful.
 */
int tls_ctx_load_pkcs12(struct tls_root_ctx *ctx, const char *pkcs12_file,
                        bool pkcs12_file_inline, bool load_ca_file);

/**
 * Use Windows cryptoapi for key and cert, and add to library-specific TLS
 * context.
 *
 * @param ctx                   TLS context to use
 * @param crypto_api_cert       String representing the certificate to load.
 */
#ifdef ENABLE_CRYPTOAPI
void tls_ctx_load_cryptoapi(struct tls_root_ctx *ctx, const char *cryptoapi_cert);

#endif /* _WIN32 */

/**
 * Load certificate file into the given TLS context. If the given certificate
 * file contains a certificate chain, load the whole chain.
 *
 * @param ctx                   TLS context to use
 * @param cert_file             The file name to load the certificate from, or
 *                              a string containing the certificate in the case
 *                              of inline files.
 * @param cert_file_inline      True if cert_file is an inline file.
 */
void tls_ctx_load_cert_file(struct tls_root_ctx *ctx, const char *cert_file,
                            bool cert_file_inline);

/**
 * Load private key file into the given TLS context.
 *
 * @param ctx                   TLS context to use
 * @param priv_key_file         The file name to load the private key from, or
 *                              a string containing the private key in the case
 *                              of inline files.
 * @param priv_key_file_inline  True if priv_key_file is an inline file
 *
 * @return                      1 if an error occurred, 0 if parsing was
 *                              successful.
 */
int tls_ctx_load_priv_file(struct tls_root_ctx *ctx, const char *priv_key_file,
                           bool priv_key_file_inline);

#ifdef ENABLE_MANAGEMENT

/**
 * Tell the management interface to load the given certificate and the external
 * private key matching the given certificate.
 *
 * @param ctx                   TLS context to use
 *
 * @return                      1 if an error occurred, 0 if successful.
 */
int tls_ctx_use_management_external_key(struct tls_root_ctx *ctx);

#endif /* ENABLE_MANAGEMENT */

/**
 * Load certificate authority certificates from the given file or path.
 *
 * Note that not all SSL libraries support loading from a path.
 *
 * @param ctx                   TLS context to use
 * @param ca_file               The file name to load the CAs from, or
 *                              a string containing the CAs in the case of
 *                              inline files.
 * @param ca_file_inline        True if ca_file is an inline file
 * @param ca_path               The path to load the CAs from
 */
void tls_ctx_load_ca(struct tls_root_ctx *ctx, const char *ca_file,
                     bool ca_file_inline, const char *ca_path, bool tls_server);

/**
 * Load extra certificate authority certificates from the given file or path.
 * These Load extra certificates that are part of our own certificate
 * chain but shouldn't be included in the verify chain.
 *
 *
 * @param ctx                           TLS context to use
 * @param extra_certs_file              The file name to load the certs from, or
 *                                      a string containing the certs in the
 *                                      case of inline files.
 * @param extra_certs_file_inline       True if extra_certs_file is an inline
 *                                      file.
 */
void tls_ctx_load_extra_certs(struct tls_root_ctx *ctx,
                              const char *extra_certs_file,
                              bool extra_certs_file_inline);

#ifdef ENABLE_CRYPTO_MBEDTLS
/**
 * Add a personalisation string to the mbed TLS RNG, based on the certificate
 * loaded into the given context.
 *
 * @param ctx                   TLS context to use
 */
void tls_ctx_personalise_random(struct tls_root_ctx *ctx);

#endif

/* **************************************
 *
 * Key-state specific functions
 *
 ***************************************/

/**
 * Initialise the SSL channel part of the given key state. Settings will be
 * loaded from a previously initialised TLS context.
 *
 * @param ks_ssl        The SSL channel's state info to initialise
 * @param ssl_ctx       The TLS context to use when initialising the channel.
 * @param is_server     Initialise a server?
 * @param session       The session associated with the given key_state
 */
void key_state_ssl_init(struct key_state_ssl *ks_ssl,
                        const struct tls_root_ctx *ssl_ctx, bool is_server, struct tls_session *session);

/**
 * Free the SSL channel part of the given key state.
 *
 * @param ks_ssl        The SSL channel's state info to free
 */
void key_state_ssl_free(struct key_state_ssl *ks_ssl);

/**
 * Reload the Certificate Revocation List for the SSL channel
 *
 * @param ssl_ctx       The TLS context to use when reloading the CRL
 * @param crl_file      The file name to load the CRL from, or
 *                      an array containing the inline CRL.
 * @param crl_inline    True if crl_file is an inline CRL.
 */
void backend_tls_ctx_reload_crl(struct tls_root_ctx *ssl_ctx,
                                const char *crl_file, bool crl_inline);

/**
 * Keying Material Exporters [RFC 5705] allows additional keying material to be
 * derived from existing TLS channel. This exported keying material can then be
 * used for a variety of purposes.
 *
 * @param ks_ssl       The SSL channel's state info
 * @param session      The session associated with the given key_state
 */

void
key_state_export_keying_material(struct key_state_ssl *ks_ssl,
                                 struct tls_session *session) __attribute__((nonnull));

/**************************************************************************/
/** @addtogroup control_tls
 *  @{ */

/** @name Functions for packets to be sent to a remote OpenVPN peer
 *  @{ */

/**
 * Insert a plaintext buffer into the TLS module.
 *
 * After successfully processing the data, the data in \a buf is zeroized,
 * its length set to zero, and a value of \c 1 is returned.
 *
 * @param ks_ssl       - The security parameter state for this %key
 *                       session.
 * @param buf          - The plaintext message to process.
 *
 * @return The return value indicates whether the data was successfully
 *     processed:
 * - \c 1: All the data was processed successfully.
 * - \c 0: The data was not processed, this function should be called
 *   again later to retry.
 * - \c -1: An error occurred.
 */
int key_state_write_plaintext(struct key_state_ssl *ks_ssl, struct buffer *buf);

/**
 * Insert plaintext data into the TLS module.
 *
 * @param ks_ssl       - The security parameter state for this %key
 *                       session.
 * @param data         - A pointer to the data to process.
 * @param len          - The length in bytes of the data to process.
 *
 * @return The return value indicates whether the data was successfully
 *     processed:
 * - \c 1: All the data was processed successfully.
 * - \c 0: The data was not processed, this function should be called
 *   again later to retry.
 * - \c -1: An error occurred.
 */
int key_state_write_plaintext_const(struct key_state_ssl *ks_ssl,
                                    const uint8_t *data, int len);

/**
 * Extract ciphertext data from the TLS module.
 *
 * If the \a buf buffer has a length other than zero, this function does
 * not perform any action and returns 0.
 *
 * @param ks_ssl       - The security parameter state for this %key
 *                       session.
 * @param buf          - A buffer in which to store the ciphertext.
 * @param maxlen       - The maximum number of bytes to extract.
 *
 * @return The return value indicates whether the data was successfully
 *     processed:
 * - \c 1: Data was extracted successfully.
 * - \c 0: No data was extracted, this function should be called again
 *   later to retry.
 * - \c -1: An error occurred.
 */
int key_state_read_ciphertext(struct key_state_ssl *ks_ssl, struct buffer *buf,
                              int maxlen);

/** @} name Functions for packets to be sent to a remote OpenVPN peer */


/** @name Functions for packets received from a remote OpenVPN peer
 *  @{ */

/**
 * Insert a ciphertext buffer into the TLS module.
 *
 * After successfully processing the data, the data in \a buf is zeroized,
 * its length set to zero, and a value of \c 1 is returned.
 *
 * @param ks_ssl       - The security parameter state for this %key
 *                       session.
 * @param buf          - The ciphertext message to process.
 *
 * @return The return value indicates whether the data was successfully
 *     processed:
 * - \c 1: All the data was processed successfully.
 * - \c 0: The data was not processed, this function should be called
 *   again later to retry.
 * - \c -1: An error occurred.
 */
int key_state_write_ciphertext(struct key_state_ssl *ks_ssl,
                               struct buffer *buf);

/**
 * Extract plaintext data from the TLS module.
 *
 * If the \a buf buffer has a length other than zero, this function does
 * not perform any action and returns 0.
 *
 * @param ks_ssl       - The security parameter state for this %key
 *                       session.
 * @param buf          - A buffer in which to store the plaintext.
 * @param maxlen       - The maximum number of bytes to extract.
 *
 * @return The return value indicates whether the data was successfully
 *     processed:
 * - \c 1: Data was extracted successfully.
 * - \c 0: No data was extracted, this function should be called again
 *   later to retry.
 * - \c -1: An error occurred.
 */
int key_state_read_plaintext(struct key_state_ssl *ks_ssl, struct buffer *buf,
                             int maxlen);

/** @} name Functions for packets received from a remote OpenVPN peer */

/** @} addtogroup control_tls */

/* **************************************
 *
 * Information functions
 *
 * Print information for the end user.
 *
 ***************************************/

/*
 * Print a one line summary of SSL/TLS session handshake.
 */
void print_details(struct key_state_ssl *ks_ssl, const char *prefix);

/*
 * Show the TLS ciphers that are available for us to use in the
 * library depending on the TLS version. This function prints
 * a list of ciphers without headers/footers.
 *
 * @param cipher_list       list of allowed TLS cipher, or NULL.
 * @param tls_cert_profile  TLS certificate crypto profile name.
 * @param tls13             Select if <=TLS1.2 or TLS1.3+ ciphers
 *                          should be shown
 */
void
show_available_tls_ciphers_list(const char *cipher_list,
                                const char *tls_cert_profile,
                                bool tls13);

/*
 * Show the available elliptic curves in the crypto library
 */
void show_available_curves(void);

/*
 * The OpenSSL library has a notion of preference in TLS ciphers.  Higher
 * preference == more secure. Return the highest preference cipher.
 */
void get_highest_preference_tls_cipher(char *buf, int size);

/**
 * return a pointer to a static memory area containing the
 * name and version number of the SSL library in use
 */
const char *get_ssl_library_version(void);

#endif /* SSL_BACKEND_H_ */