ssl_backend.h

Go to the documentation of this file.

/*
 *  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-2023 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.
 */
 
#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
 
struct tls_session;
 
/*
 *
 * Functions implemented in ssl.c for use by the backend SSL library
 *
 */
 
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
 *
 */
 
void tls_init_lib(void);
 
void tls_free_lib(void);
 
void tls_clear_error(void);
 
#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);
 
int tls_version_max(void);
 
void tls_ctx_server_new(struct tls_root_ctx *ctx);
 
void tls_ctx_client_new(struct tls_root_ctx *ctx);
 
void tls_ctx_free(struct tls_root_ctx *ctx);
 
bool tls_ctx_initialised(struct tls_root_ctx *ctx);
 
bool tls_ctx_set_options(struct tls_root_ctx *ctx, unsigned int ssl_flags);
 
void tls_ctx_restrict_ciphers(struct tls_root_ctx *ctx, const char *ciphers);
 
void tls_ctx_restrict_ciphers_tls13(struct tls_root_ctx *ctx, const char *ciphers);
 
void tls_ctx_set_cert_profile(struct tls_root_ctx *ctx, const char *profile);
 
void tls_ctx_set_tls_groups(struct tls_root_ctx *ctx, const char *groups);
 
void tls_ctx_check_cert_time(const struct tls_root_ctx *ctx);
 
void tls_ctx_load_dh_params(struct tls_root_ctx *ctx, const char *dh_file,
                            bool dh_file_inline);
 
void tls_ctx_load_ecdh_params(struct tls_root_ctx *ctx, const char *curve_name
                              );
 
int tls_ctx_load_pkcs12(struct tls_root_ctx *ctx, const char *pkcs12_file,
                        bool pkcs12_file_inline, bool load_ca_file);
 
#ifdef ENABLE_CRYPTOAPI
void tls_ctx_load_cryptoapi(struct tls_root_ctx *ctx, const char *cryptoapi_cert);
 
#endif /* _WIN32 */
 
void tls_ctx_load_cert_file(struct tls_root_ctx *ctx, const char *cert_file,
                            bool cert_file_inline);
 
int tls_ctx_load_priv_file(struct tls_root_ctx *ctx, const char *priv_key_file,
                           bool priv_key_file_inline);
 
#ifdef ENABLE_MANAGEMENT
 
int tls_ctx_use_management_external_key(struct tls_root_ctx *ctx);
 
#endif /* ENABLE_MANAGEMENT */
 
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);
 
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
 
void tls_ctx_personalise_random(struct tls_root_ctx *ctx);
 
#endif
 
/* **************************************
 *
 * Key-state specific functions
 *
 ***************************************/
 
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);
 
void key_state_ssl_free(struct key_state_ssl *ks_ssl);
 
void backend_tls_ctx_reload_crl(struct tls_root_ctx *ssl_ctx,
                                const char *crl_file, bool crl_inline);
 
#define EXPORT_KEY_DATA_LABEL       "EXPORTER-OpenVPN-datakeys"
#define EXPORT_P2P_PEERID_LABEL     "EXPORTER-OpenVPN-p2p-peerid"
#define EXPORT_DYNAMIC_TLS_CRYPT_LABEL  "EXPORTER-OpenVPN-dynamic-tls-crypt"
 
bool
key_state_export_keying_material(struct tls_session *session,
                                 const char *label, size_t label_size,
                                 void *ekm, size_t ekm_size);
 
/**************************************************************************/
int key_state_write_plaintext(struct key_state_ssl *ks_ssl, struct buffer *buf);
 
int key_state_write_plaintext_const(struct key_state_ssl *ks_ssl,
                                    const uint8_t *data, int len);
 
int key_state_read_ciphertext(struct key_state_ssl *ks_ssl, struct buffer *buf);
 
 
int key_state_write_ciphertext(struct key_state_ssl *ks_ssl,
                               struct buffer *buf);
 
int key_state_read_plaintext(struct key_state_ssl *ks_ssl, struct buffer *buf);
 
/* **************************************
 *
 * 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);
 
const char *get_ssl_library_version(void);
 
#endif /* SSL_BACKEND_H_ */