OpenVPN
Data Structures | Macros | Functions
ssl_backend.h File Reference
#include "buffer.h"
#include "ssl_openssl.h"
#include "ssl_verify_openssl.h"
Include dependency graph for ssl_backend.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  tls_cipher_name_pair
 Get a tls_cipher_name_pair containing OpenSSL and IANA names for supplied TLS cipher name. More...
 

Macros

#define SSLAPI   SSLAPI_OPENSSL
 
#define TLS_VER_BAD   -1
 Parse a TLS version specifier. More...
 
#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
 

Functions

const tls_cipher_name_pairtls_get_cipher_name_pair (const char *cipher_name, size_t len)
 
int pem_password_callback (char *buf, int size, int rwflag, void *u)
 Callback to retrieve the user's password. More...
 
void tls_init_lib (void)
 Perform any static initialisation necessary by the library. More...
 
void tls_free_lib (void)
 Free any global SSL library-specific data structures. More...
 
void tls_clear_error (void)
 Clear the underlying SSL library's error state. More...
 
int tls_version_parse (const char *vstr, const char *extra)
 
int tls_version_max (void)
 Return the maximum TLS version (as a TLS_VER_x constant) supported by current SSL implementation. More...
 
void tls_ctx_server_new (struct tls_root_ctx *ctx)
 Initialise a library-specific TLS context for a server. More...
 
void tls_ctx_client_new (struct tls_root_ctx *ctx)
 Initialises a library-specific TLS context for a client. More...
 
void tls_ctx_free (struct tls_root_ctx *ctx)
 Frees the library-specific TLSv1 context. More...
 
bool tls_ctx_initialised (struct tls_root_ctx *ctx)
 Checks whether the given TLS context is initialised. More...
 
bool tls_ctx_set_options (struct tls_root_ctx *ctx, unsigned int ssl_flags)
 Set any library specific options. More...
 
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.2 and below. More...
 
void tls_ctx_restrict_ciphers_tls13 (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. More...
 
void tls_ctx_set_cert_profile (struct tls_root_ctx *ctx, const char *profile)
 Set the TLS certificate profile. More...
 
void tls_ctx_check_cert_time (const struct tls_root_ctx *ctx)
 Check our certificate notBefore and notAfter fields, and warn if the cert is either not yet valid or has expired. More...
 
void tls_ctx_load_dh_params (struct tls_root_ctx *ctx, const char *dh_file, const char *dh_file_inline)
 Load Diffie Hellman Parameters, and load them into the library-specific TLS context. More...
 
void tls_ctx_load_ecdh_params (struct tls_root_ctx *ctx, const char *curve_name)
 Load Elliptic Curve Parameters, and load them into the library-specific TLS context. More...
 
int tls_ctx_load_pkcs12 (struct tls_root_ctx *ctx, const char *pkcs12_file, const char *pkcs12_file_inline, bool load_ca_file)
 Load PKCS #12 file for key, cert and (optionally) CA certs, and add to library-specific TLS context. More...
 
void tls_ctx_load_cert_file (struct tls_root_ctx *ctx, const char *cert_file, const char *cert_file_inline)
 Use Windows cryptoapi for key and cert, and add to library-specific TLS context. More...
 
int tls_ctx_load_priv_file (struct tls_root_ctx *ctx, const char *priv_key_file, const char *priv_key_file_inline)
 Load private key file into the given TLS context. More...
 
int tls_ctx_use_management_external_key (struct tls_root_ctx *ctx)
 Tell the management interface to load the given certificate and the external private key matching the given certificate. More...
 
void tls_ctx_load_ca (struct tls_root_ctx *ctx, const char *ca_file, const char *ca_file_inline, const char *ca_path, bool tls_server)
 Load certificate authority certificates from the given file or path. More...
 
void tls_ctx_load_extra_certs (struct tls_root_ctx *ctx, const char *extra_certs_file, const char *extra_certs_file_inline)
 Load extra certificate authority certificates from the given file or path. More...
 
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)
 Initialise the SSL channel part of the given key state. More...
 
void key_state_ssl_free (struct key_state_ssl *ks_ssl)
 Free the SSL channel part of the given key state. More...
 
void backend_tls_ctx_reload_crl (struct tls_root_ctx *ssl_ctx, const char *crl_file, const char *crl_inline)
 Reload the Certificate Revocation List for the SSL channel. More...
 
void key_state_export_keying_material (struct key_state_ssl *ks_ssl, struct tls_session *session) __attribute__((nonnull))
 Keying Material Exporters [RFC 5705] allows additional keying material to be derived from existing TLS channel. More...
 
void print_details (struct key_state_ssl *ks_ssl, const char *prefix)
 
void show_available_tls_ciphers_list (const char *cipher_list, const char *tls_cert_profile, bool tls13)
 
void show_available_curves (void)
 
void get_highest_preference_tls_cipher (char *buf, int size)
 
const char * get_ssl_library_version (void)
 return a pointer to a static memory area containing the name and version number of the SSL library in use More...
 
Functions for packets to be sent to a remote OpenVPN peer
int key_state_write_plaintext (struct key_state_ssl *ks_ssl, struct buffer *buf)
 Insert a plaintext buffer into the TLS module. More...
 
int key_state_write_plaintext_const (struct key_state_ssl *ks_ssl, const uint8_t *data, int len)
 Insert plaintext data into the TLS module. More...
 
int key_state_read_ciphertext (struct key_state_ssl *ks_ssl, struct buffer *buf, int maxlen)
 Extract ciphertext data from the TLS module. More...
 
Functions for packets received from a remote OpenVPN peer
int key_state_write_ciphertext (struct key_state_ssl *ks_ssl, struct buffer *buf)
 Insert a ciphertext buffer into the TLS module. More...
 
int key_state_read_plaintext (struct key_state_ssl *ks_ssl, struct buffer *buf, int maxlen)
 Extract plaintext data from the TLS module. More...
 

Macro Definition Documentation

◆ SSLAPI

#define SSLAPI   SSLAPI_OPENSSL

Definition at line 38 of file ssl_backend.h.

Referenced by plugin_open_item().

◆ TLS_VER_1_0

#define TLS_VER_1_0   1

Definition at line 114 of file ssl_backend.h.

Referenced by openssl_tls_version(), tls_version_max(), and tls_version_parse().

◆ TLS_VER_1_1

#define TLS_VER_1_1   2

Definition at line 115 of file ssl_backend.h.

Referenced by openssl_tls_version(), tls_version_max(), and tls_version_parse().

◆ TLS_VER_1_2

#define TLS_VER_1_2   3

Definition at line 116 of file ssl_backend.h.

Referenced by openssl_tls_version(), tls_version_max(), and tls_version_parse().

◆ TLS_VER_1_3

#define TLS_VER_1_3   4

Definition at line 117 of file ssl_backend.h.

Referenced by openssl_tls_version(), tls_version_max(), and tls_version_parse().

◆ TLS_VER_BAD

#define TLS_VER_BAD   -1

Parse a TLS version specifier.

Parameters
vstrThe TLS version string
extraAn optional extra parameter, may be NULL
Returns
One of the TLS_VER_x constants or TLS_VER_BAD if a parse error should be flagged.

Definition at line 112 of file ssl_backend.h.

Referenced by add_option(), and tls_version_parse().

◆ TLS_VER_UNSPEC

#define TLS_VER_UNSPEC   0 /* default */

Definition at line 113 of file ssl_backend.h.

Function Documentation

◆ backend_tls_ctx_reload_crl()

void backend_tls_ctx_reload_crl ( struct tls_root_ctx ssl_ctx,
const char *  crl_file,
const char *  crl_inline 
)

Reload the Certificate Revocation List for the SSL channel.

Parameters
ssl_ctxThe TLS context to use when reloading the CRL
crl_fileThe file name to load the CRL from, or "[[INLINE]]" in the case of inline files.
crl_inlineA string containing the CRL

Definition at line 995 of file ssl_openssl.c.

References ASSERT, crypto_msg, tls_root_ctx::ctx, INLINE_FILE_TAG, M_FATAL, M_WARN, msg, STACK_OF(), X509_OBJECT_free(), and X509_OBJECT_get_type().

Referenced by tls_ctx_reload_crl().

◆ get_highest_preference_tls_cipher()

void get_highest_preference_tls_cipher ( char *  buf,
int  size 
)

Definition at line 2099 of file ssl_openssl.c.

References crypto_msg, tls_root_ctx::ctx, M_FATAL, and strncpynt().

◆ get_ssl_library_version()

const char* get_ssl_library_version ( void  )

return a pointer to a static memory area containing the name and version number of the SSL library in use

Definition at line 2124 of file ssl_openssl.c.

References OPENSSL_VERSION, and OpenSSL_version.

Referenced by push_peer_info(), and show_library_versions().

◆ key_state_export_keying_material()

void key_state_export_keying_material ( struct key_state_ssl ks_ssl,
struct tls_session session 
)

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.

Parameters
ks_sslThe SSL channel's state info
sessionThe session associated with the given key_state

Definition at line 149 of file ssl_openssl.c.

References D_TLS_DEBUG_MED, dmsg, tls_options::ekm_label, tls_options::ekm_label_size, tls_options::ekm_size, tls_options::es, format_hex_ex(), gc_free(), gc_malloc(), gc_new(), M_WARN, msg, tls_session::opt, setenv_del(), setenv_str(), and key_state_ssl::ssl.

Referenced by key_method_2_read().

◆ key_state_ssl_free()

void key_state_ssl_free ( struct key_state_ssl ks_ssl)

Free the SSL channel part of the given key state.

Parameters
ks_sslThe SSL channel's state info to free

Definition at line 1830 of file ssl_openssl.c.

References key_state_ssl::ct_in, key_state_ssl::ct_out, key_state_ssl::ssl, and key_state_ssl::ssl_bio.

Referenced by key_state_free().

◆ key_state_ssl_init()

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 
)

Initialise the SSL channel part of the given key state.

Settings will be loaded from a previously initialised TLS context.

Parameters
ks_sslThe SSL channel's state info to initialise
ssl_ctxThe TLS context to use when initialising the channel.
is_serverInitialise a server?
sessionThe session associated with the given key_state

Definition at line 1790 of file ssl_openssl.c.

References ASSERT, CLEAR, crypto_msg, key_state_ssl::ct_in, key_state_ssl::ct_out, tls_root_ctx::ctx, M_FATAL, mydata_index, key_state_ssl::ssl, and key_state_ssl::ssl_bio.

Referenced by key_state_init().

◆ pem_password_callback()

int pem_password_callback ( char *  buf,
int  size,
int  rwflag,
void *  u 
)

Callback to retrieve the user's password.

Parameters
bufBuffer to return the password in
sizeSize of the buffer
rwflagUnused, needed for OpenSSL compatibility
uUnused, needed for OpenSSL compatibility

Definition at line 381 of file ssl.c.

References passbuf, user_pass::password, pem_password_setup(), purge_user_pass(), and strncpynt().

Referenced by tls_ctx_load_pkcs12(), and tls_ctx_set_options().

◆ print_details()

void print_details ( struct key_state_ssl ks_ssl,
const char *  prefix 
)

◆ show_available_curves()

void show_available_curves ( void  )

Definition at line 2063 of file ssl_openssl.c.

References ALLOC_ARRAY, crypto_msg, free, M_FATAL, M_WARN, and msg.

Referenced by print_openssl_info().

◆ show_available_tls_ciphers_list()

void show_available_tls_ciphers_list ( const char *  cipher_list,
const char *  tls_cert_profile,
bool  tls13 
)

◆ tls_clear_error()

void tls_clear_error ( void  )

Clear the underlying SSL library's error state.

Definition at line 99 of file ssl_openssl.c.

Referenced by init_ssl(), tls_multi_process(), tls_pre_decrypt(), tls_pre_decrypt_lite(), tls_process(), tls_rec_payload(), tls_send_payload(), and verify_cert().

◆ tls_ctx_check_cert_time()

void tls_ctx_check_cert_time ( const struct tls_root_ctx ctx)

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.

Parameters
ctxTLS context to get our certificate from.

Definition at line 522 of file ssl_openssl.c.

References ASSERT, tls_root_ctx::ctx, D_TLS_DEBUG_MED, M_WARN, and msg.

Referenced by init_ssl().

◆ tls_ctx_client_new()

void tls_ctx_client_new ( struct tls_root_ctx ctx)

Initialises a library-specific TLS context for a client.

Parameters
ctxTLS context to initialise

Definition at line 118 of file ssl_openssl.c.

References ASSERT, crypto_msg, tls_root_ctx::ctx, and M_FATAL.

Referenced by init_ssl().

◆ tls_ctx_free()

void tls_ctx_free ( struct tls_root_ctx ctx)

Frees the library-specific TLSv1 context.

Parameters
ctxTLS context to free

Definition at line 131 of file ssl_openssl.c.

References ASSERT, and tls_root_ctx::ctx.

Referenced by init_ssl(), and key_schedule_free().

◆ tls_ctx_initialised()

bool tls_ctx_initialised ( struct tls_root_ctx ctx)

Checks whether the given TLS context is initialised.

Parameters
ctxTLS context to check
Returns
true if the context is initialised, false if not.

Definition at line 142 of file ssl_openssl.c.

References ASSERT, and tls_root_ctx::ctx.

Referenced by do_init_crypto_tls_c1(), and key_schedule_free().

◆ tls_ctx_load_ca()

void tls_ctx_load_ca ( struct tls_root_ctx ctx,
const char *  ca_file,
const char *  ca_file_inline,
const char *  ca_path,
bool  tls_server 
)

Load certificate authority certificates from the given file or path.

Note that not all SSL libraries support loading from a path.

Parameters
ctxTLS context to use
ca_fileThe file name to load the CAs from, or "[[INLINE]]" in the case of inline files.
ca_file_inlineA string containing the CAs
ca_pathThe path to load the CAs from

Definition at line 1410 of file ssl_openssl.c.

References ASSERT, crypto_msg, tls_root_ctx::ctx, INLINE_FILE_TAG, M_FATAL, M_WARN, msg, np(), sk_x509_name_cmp(), and STACK_OF().

Referenced by init_ssl().

◆ tls_ctx_load_cert_file()

void tls_ctx_load_cert_file ( struct tls_root_ctx ctx,
const char *  cert_file,
const char *  cert_file_inline 
)

Use Windows cryptoapi for key and cert, and add to library-specific TLS context.

Parameters
ctxTLS context to use
crypto_api_certString representing the certificate to load. Load certificate file into the given TLS context. If the given certificate file contains a certificate chain, load the whole chain.
ctxTLS context to use
cert_fileThe file name to load the certificate from, or "[[INLINE]]" in the case of inline files.
cert_file_inlineA string containing the certificate

Definition at line 862 of file ssl_openssl.c.

References ASSERT, crypto_msg, tls_root_ctx::ctx, INLINE_FILE_TAG, M_FATAL, SSL_CTX_get_default_passwd_cb(), SSL_CTX_get_default_passwd_cb_userdata(), and tls_ctx_add_extra_certs().

Referenced by init_ssl().

◆ tls_ctx_load_dh_params()

void tls_ctx_load_dh_params ( struct tls_root_ctx ctx,
const char *  dh_file,
const char *  dh_file_inline 
)

Load Diffie Hellman Parameters, and load them into the library-specific TLS context.

Parameters
ctxTLS context to use
dh_fileThe file name to load the parameters from, or "[[INLINE]]" in the case of inline files.
dh_file_inlineA string containing the parameters

Definition at line 571 of file ssl_openssl.c.

References ASSERT, crypto_msg, tls_root_ctx::ctx, D_TLS_DEBUG_LOW, INLINE_FILE_TAG, M_FATAL, and msg.

Referenced by init_ssl().

◆ tls_ctx_load_ecdh_params()

void tls_ctx_load_ecdh_params ( struct tls_root_ctx ctx,
const char *  curve_name 
)

Load Elliptic Curve Parameters, and load them into the library-specific TLS context.

Parameters
ctxTLS context to use
curve_nameThe name of the elliptic curve to load.

Definition at line 615 of file ssl_openssl.c.

References crypto_msg, tls_root_ctx::ctx, D_LOW, D_TLS_DEBUG, D_TLS_DEBUG_LOW, M_FATAL, msg, and source.

Referenced by init_ssl().

◆ tls_ctx_load_extra_certs()

void tls_ctx_load_extra_certs ( struct tls_root_ctx ctx,
const char *  extra_certs_file,
const char *  extra_certs_file_inline 
)

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.

Parameters
ctxTLS context to use
extra_certs_fileThe file name to load the certs from, or "[[INLINE]]" in the case of inline files.
extra_certs_file_inlineA string containing the certs

Definition at line 1563 of file ssl_openssl.c.

References ASSERT, crypto_msg, format_hex(), gc_free(), gc_new(), INLINE_FILE_TAG, M_FATAL, openvpn_snprintf(), ptr_format, and tls_ctx_add_extra_certs().

Referenced by init_ssl().

◆ tls_ctx_load_pkcs12()

int tls_ctx_load_pkcs12 ( struct tls_root_ctx ctx,
const char *  pkcs12_file,
const char *  pkcs12_file_inline,
bool  load_ca_file 
)

Load PKCS #12 file for key, cert and (optionally) CA certs, and add to library-specific TLS context.

Parameters
ctxTLS context to use
pkcs12_fileThe file name to load the information from, or "[[INLINE]]" in the case of inline files.
pkcs12_file_inlineA string containing the information
Returns
1 if an error occurred, 0 if parsing was successful.

Definition at line 698 of file ssl_openssl.c.

References ASSERT, crypto_msg, tls_root_ctx::ctx, INLINE_FILE_TAG, M_FATAL, management_auth_failure(), pem_password_callback(), platform_fopen(), STACK_OF(), and UP_TYPE_PRIVATE_KEY.

Referenced by init_ssl().

◆ tls_ctx_load_priv_file()

int tls_ctx_load_priv_file ( struct tls_root_ctx ctx,
const char *  priv_key_file,
const char *  priv_key_file_inline 
)

Load private key file into the given TLS context.

Parameters
ctxTLS context to use
priv_key_fileThe file name to load the private key from, or "[[INLINE]]" in the case of inline files.
priv_key_file_inlineA string containing the private key
Returns
1 if an error occurred, 0 if parsing was successful.

Definition at line 928 of file ssl_openssl.c.

References ASSERT, crypto_msg, tls_root_ctx::ctx, INLINE_FILE_TAG, M_FATAL, M_WARN, management_auth_failure(), SSL_CTX_get_default_passwd_cb(), SSL_CTX_get_default_passwd_cb_userdata(), and UP_TYPE_PRIVATE_KEY.

Referenced by init_ssl().

◆ tls_ctx_restrict_ciphers()

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.2 and below.

Parameters
ctxTLS context to restrict, must be valid.
ciphersString containing : delimited cipher names, or NULL to use sane defaults.

Definition at line 397 of file ssl_openssl.c.

References ASSERT, convert_tls_list_to_openssl(), crypto_msg, tls_root_ctx::ctx, and M_FATAL.

Referenced by init_ssl(), and show_available_tls_ciphers_list().

◆ tls_ctx_restrict_ciphers_tls13()

void tls_ctx_restrict_ciphers_tls13 ( 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.

Parameters
ctxTLS context to restrict, must be valid.
ciphersString containing : delimited cipher names, or NULL to use sane defaults.

Definition at line 459 of file ssl_openssl.c.

References ASSERT, convert_tls13_list_to_openssl(), crypto_msg, tls_root_ctx::ctx, M_FATAL, and M_WARN.

Referenced by init_ssl(), and show_available_tls_ciphers_list().

◆ tls_ctx_server_new()

void tls_ctx_server_new ( struct tls_root_ctx ctx)

Initialise a library-specific TLS context for a server.

Parameters
ctxTLS context to initialise

Definition at line 105 of file ssl_openssl.c.

References ASSERT, crypto_msg, tls_root_ctx::ctx, and M_FATAL.

Referenced by init_ssl().

◆ tls_ctx_set_cert_profile()

void tls_ctx_set_cert_profile ( struct tls_root_ctx ctx,
const char *  profile 
)

Set the TLS certificate profile.

The profile defines which crypto algorithms may be used in the supplied certificate.

Parameters
ctxTLS context to restrict, must be valid.
profileThe profile name ('preferred', 'legacy' or 'suiteb'). Defaults to 'preferred' if NULL.

Definition at line 488 of file ssl_openssl.c.

References tls_root_ctx::ctx, M_FATAL, M_WARN, and msg.

Referenced by init_ssl(), and show_available_tls_ciphers_list().

◆ tls_ctx_set_options()

bool tls_ctx_set_options ( struct tls_root_ctx ctx,
unsigned int  ssl_flags 
)

Set any library specific options.

Examples include disabling session caching, the password callback to use, and session verification parameters.

Parameters
ctxTLS context to set options on
ssl_flagsSSL flags to set
Returns
true on success, false otherwise.

Definition at line 281 of file ssl_openssl.c.

References ASSERT, tls_root_ctx::ctx, info_callback(), pem_password_callback(), SSLF_CLIENT_CERT_NOT_REQUIRED, SSLF_CLIENT_CERT_OPTIONAL, tls_ctx_set_tls_versions(), and verify_callback().

Referenced by init_ssl().

◆ tls_ctx_use_management_external_key()

int tls_ctx_use_management_external_key ( struct tls_root_ctx ctx)

Tell the management interface to load the given certificate and the external private key matching the given certificate.

Parameters
ctxTLS context to use
Returns
1 if an error occurred, 0 if successful.

Definition at line 1337 of file ssl_openssl.c.

References ASSERT, crypto_msg, tls_root_ctx::ctx, EVP_PKEY_id(), M_FATAL, M_WARN, tls_ctx_use_external_rsa_key(), and X509_get0_pubkey().

Referenced by init_ssl().

◆ tls_free_lib()

void tls_free_lib ( void  )

Free any global SSL library-specific data structures.

Definition at line 90 of file ssl_openssl.c.

Referenced by free_ssl_lib().

◆ tls_get_cipher_name_pair()

const tls_cipher_name_pair* tls_get_cipher_name_pair ( const char *  cipher_name,
size_t  len 
)

◆ tls_init_lib()

void tls_init_lib ( void  )

Perform any static initialisation necessary by the library.

Called on OpenVPN initialisation

Definition at line 77 of file ssl_openssl.c.

References ASSERT, and mydata_index.

Referenced by init_ssl_lib().

◆ tls_version_max()

int tls_version_max ( void  )

Return the maximum TLS version (as a TLS_VER_x constant) supported by current SSL implementation.

Returns
One of the TLS_VER_x constants (but not TLS_VER_BAD).

Definition at line 212 of file ssl_openssl.c.

References TLS_VER_1_0, TLS_VER_1_1, TLS_VER_1_2, and TLS_VER_1_3.

Referenced by options_postprocess_verify_ce(), and tls_version_parse().

◆ tls_version_parse()

int tls_version_parse ( const char *  vstr,
const char *  extra 
)

Definition at line 512 of file ssl.c.

References TLS_VER_1_0, TLS_VER_1_1, TLS_VER_1_2, TLS_VER_1_3, TLS_VER_BAD, and tls_version_max().

Referenced by add_option().