OpenVPN
ssl_backend.h
Go to the documentation of this file.
1 /*
2  * OpenVPN -- An application to securely tunnel IP networks
3  * over a single TCP/UDP port, with support for SSL/TLS-based
4  * session authentication and key exchange,
5  * packet encryption, packet authentication, and
6  * packet compression.
7  *
8  * Copyright (C) 2002-2024 OpenVPN Inc <sales@openvpn.net>
9  * Copyright (C) 2010-2021 Fox Crypto B.V. <openvpn@foxcrypto.com>
10  *
11  * This program is free software; you can redistribute it and/or modify
12  * it under the terms of the GNU General Public License version 2
13  * as published by the Free Software Foundation.
14  *
15  * This program is distributed in the hope that it will be useful,
16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18  * GNU General Public License for more details.
19  *
20  * You should have received a copy of the GNU General Public License along
21  * with this program; if not, write to the Free Software Foundation, Inc.,
22  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
23  */
24 
30 #ifndef SSL_BACKEND_H_
31 #define SSL_BACKEND_H_
32 
33 #include "buffer.h"
34 
35 #ifdef ENABLE_CRYPTO_OPENSSL
36 #include "ssl_openssl.h"
37 #include "ssl_verify_openssl.h"
38 #define SSLAPI SSLAPI_OPENSSL
39 #endif
40 #ifdef ENABLE_CRYPTO_MBEDTLS
41 #include "ssl_mbedtls.h"
42 #include "ssl_verify_mbedtls.h"
43 #define SSLAPI SSLAPI_MBEDTLS
44 #endif
45 
46 /* Ensure that SSLAPI got a sane value if SSL is disabled or unknown */
47 #ifndef SSLAPI
48 #define SSLAPI SSLAPI_NONE
49 #endif
50 
54 struct tls_session;
55 
56 /*
57  *
58  * Functions implemented in ssl.c for use by the backend SSL library
59  *
60  */
61 
70 int pem_password_callback(char *buf, int size, int rwflag, void *u);
71 
72 /*
73  *
74  * Functions used in ssl.c which must be implemented by the backend SSL library
75  *
76  */
77 
82 void tls_init_lib(void);
83 
87 void tls_free_lib(void);
88 
92 void tls_clear_error(void);
93 
103 #define TLS_VER_BAD -1
104 #define TLS_VER_UNSPEC 0 /* default */
105 #define TLS_VER_1_0 1
106 #define TLS_VER_1_1 2
107 #define TLS_VER_1_2 3
108 #define TLS_VER_1_3 4
109 int tls_version_parse(const char *vstr, const char *extra);
110 
117 int tls_version_max(void);
118 
124 void tls_ctx_server_new(struct tls_root_ctx *ctx);
125 
131 void tls_ctx_client_new(struct tls_root_ctx *ctx);
132 
138 void tls_ctx_free(struct tls_root_ctx *ctx);
139 
147 bool tls_ctx_initialised(struct tls_root_ctx *ctx);
148 
160 bool tls_ctx_set_options(struct tls_root_ctx *ctx, unsigned int ssl_flags);
161 
170 void tls_ctx_restrict_ciphers(struct tls_root_ctx *ctx, const char *ciphers);
171 
180 void tls_ctx_restrict_ciphers_tls13(struct tls_root_ctx *ctx, const char *ciphers);
181 
190 void tls_ctx_set_cert_profile(struct tls_root_ctx *ctx, const char *profile);
191 
200 void tls_ctx_set_tls_groups(struct tls_root_ctx *ctx, const char *groups);
201 
209 void tls_ctx_check_cert_time(const struct tls_root_ctx *ctx);
210 
221 void tls_ctx_load_dh_params(struct tls_root_ctx *ctx, const char *dh_file,
222  bool dh_file_inline);
223 
231 void tls_ctx_load_ecdh_params(struct tls_root_ctx *ctx, const char *curve_name
232  );
233 
247 int tls_ctx_load_pkcs12(struct tls_root_ctx *ctx, const char *pkcs12_file,
248  bool pkcs12_file_inline, bool load_ca_file);
249 
257 #ifdef ENABLE_CRYPTOAPI
258 void tls_ctx_load_cryptoapi(struct tls_root_ctx *ctx, const char *cryptoapi_cert);
259 
260 #endif /* _WIN32 */
261 
272 void tls_ctx_load_cert_file(struct tls_root_ctx *ctx, const char *cert_file,
273  bool cert_file_inline);
274 
287 int tls_ctx_load_priv_file(struct tls_root_ctx *ctx, const char *priv_key_file,
288  bool priv_key_file_inline);
289 
290 #ifdef ENABLE_MANAGEMENT
291 
301 
302 #endif /* ENABLE_MANAGEMENT */
303 
316 void tls_ctx_load_ca(struct tls_root_ctx *ctx, const char *ca_file,
317  bool ca_file_inline, const char *ca_path, bool tls_server);
318 
332 void tls_ctx_load_extra_certs(struct tls_root_ctx *ctx,
333  const char *extra_certs_file,
334  bool extra_certs_file_inline);
335 
336 #ifdef ENABLE_CRYPTO_MBEDTLS
337 
343 void tls_ctx_personalise_random(struct tls_root_ctx *ctx);
344 
345 #endif
346 
347 /* **************************************
348  *
349  * Key-state specific functions
350  *
351  ***************************************/
352 
362 void key_state_ssl_init(struct key_state_ssl *ks_ssl,
363  const struct tls_root_ctx *ssl_ctx, bool is_server, struct tls_session *session);
364 
369 void
370 key_state_ssl_shutdown(struct key_state_ssl *ks_ssl);
371 
377 void key_state_ssl_free(struct key_state_ssl *ks_ssl);
378 
387 void backend_tls_ctx_reload_crl(struct tls_root_ctx *ssl_ctx,
388  const char *crl_file, bool crl_inline);
389 
390 #define EXPORT_KEY_DATA_LABEL "EXPORTER-OpenVPN-datakeys"
391 #define EXPORT_P2P_PEERID_LABEL "EXPORTER-OpenVPN-p2p-peerid"
392 #define EXPORT_DYNAMIC_TLS_CRYPT_LABEL "EXPORTER-OpenVPN-dynamic-tls-crypt"
393 
405 bool
407  const char *label, size_t label_size,
408  void *ekm, size_t ekm_size);
409 
410 /**************************************************************************/
434 int key_state_write_plaintext(struct key_state_ssl *ks_ssl, struct buffer *buf);
435 
452  const uint8_t *data, int len);
453 
471 int key_state_read_ciphertext(struct key_state_ssl *ks_ssl, struct buffer *buf);
472 
473 
497 int key_state_write_ciphertext(struct key_state_ssl *ks_ssl,
498  struct buffer *buf);
499 
518 int key_state_read_plaintext(struct key_state_ssl *ks_ssl, struct buffer *buf);
519 
524 /* **************************************
525  *
526  * Information functions
527  *
528  * Print information for the end user.
529  *
530  ***************************************/
531 
532 /*
533  * Print a one line summary of SSL/TLS session handshake.
534  */
535 void print_details(struct key_state_ssl *ks_ssl, const char *prefix);
536 
537 /*
538  * Show the TLS ciphers that are available for us to use in the
539  * library depending on the TLS version. This function prints
540  * a list of ciphers without headers/footers.
541  *
542  * @param cipher_list list of allowed TLS cipher, or NULL.
543  * @param tls_cert_profile TLS certificate crypto profile name.
544  * @param tls13 Select if <=TLS1.2 or TLS1.3+ ciphers
545  * should be shown
546  */
547 void
548 show_available_tls_ciphers_list(const char *cipher_list,
549  const char *tls_cert_profile,
550  bool tls13);
551 
552 /*
553  * Show the available elliptic curves in the crypto library
554  */
555 void show_available_curves(void);
556 
557 /*
558  * The OpenSSL library has a notion of preference in TLS ciphers. Higher
559  * preference == more secure. Return the highest preference cipher.
560  */
561 void get_highest_preference_tls_cipher(char *buf, int size);
562 
567 const char *get_ssl_library_version(void);
568 
569 #endif /* SSL_BACKEND_H_ */
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.
Definition: ssl_openssl.c:1950
tls_ctx_load_cert_file
void tls_ctx_load_cert_file(struct tls_root_ctx *ctx, const char *cert_file, bool cert_file_inline)
Load certificate file into the given TLS context.
Definition: ssl_openssl.c:949
key_state_ssl
Definition: ssl_mbedtls.h:127
tls_init_lib
void tls_init_lib(void)
Perform any static initialisation necessary by the library.
Definition: ssl_openssl.c:85
tls_ctx_load_priv_file
int tls_ctx_load_priv_file(struct tls_root_ctx *ctx, const char *priv_key_file, bool priv_key_file_inline)
Load private key file into the given TLS context.
Definition: ssl_openssl.c:1011
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.
Definition: ssl_openssl.c:710
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...
Definition: ssl_openssl.c:2409
print_details
void print_details(struct key_state_ssl *ks_ssl, const char *prefix)
Definition: ssl_openssl.c:2240
tls_ctx_load_extra_certs
void tls_ctx_load_extra_certs(struct tls_root_ctx *ctx, const char *extra_certs_file, bool extra_certs_file_inline)
Load extra certificate authority certificates from the given file or path.
Definition: ssl_openssl.c:1685
tls_ctx_client_new
void tls_ctx_client_new(struct tls_root_ctx *ctx)
Initialises a library-specific TLS context for a client.
Definition: ssl_openssl.c:115
tls_ctx_server_new
void tls_ctx_server_new(struct tls_root_ctx *ctx)
Initialise a library-specific TLS context for a server.
Definition: ssl_openssl.c:97
show_available_tls_ciphers_list
void show_available_tls_ciphers_list(const char *cipher_list, const char *tls_cert_profile, bool tls13)
Definition: ssl_openssl.c:2269
tls_ctx_set_options
bool tls_ctx_set_options(struct tls_root_ctx *ctx, unsigned int ssl_flags)
Set any library specific options.
Definition: ssl_openssl.c:303
ssl_verify_openssl.h
tls_ctx_load_cryptoapi
void tls_ctx_load_cryptoapi(struct tls_root_ctx *ctx, const char *cryptoapi_cert)
Use Windows cryptoapi for key and cert, and add to library-specific TLS context.
Definition: ssl_openssl.c:902
tls_free_lib
void tls_free_lib(void)
Free any global SSL library-specific data structures.
Definition: ssl_openssl.c:92
ssl_verify_mbedtls.h
backend_tls_ctx_reload_crl
void backend_tls_ctx_reload_crl(struct tls_root_ctx *ssl_ctx, const char *crl_file, bool crl_inline)
Reload the Certificate Revocation List for the SSL channel.
Definition: ssl_openssl.c:1068
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...
Definition: ssl_openssl.c:1456
key_state_write_ciphertext
int key_state_write_ciphertext(struct key_state_ssl *ks_ssl, struct buffer *buf)
Insert a ciphertext buffer into the TLS module.
Definition: ssl_openssl.c:2009
key_state_read_plaintext
int key_state_read_plaintext(struct key_state_ssl *ks_ssl, struct buffer *buf)
Extract plaintext data from the TLS module.
Definition: ssl_openssl.c:2024
tls_ctx_initialised
bool tls_ctx_initialised(struct tls_root_ctx *ctx)
Checks whether the given TLS context is initialised.
Definition: ssl_openssl.c:142
tls_version_max
int tls_version_max(void)
Return the maximum TLS version (as a TLS_VER_x constant) supported by current SSL implementation.
Definition: ssl_openssl.c:200
tls_ctx_free
void tls_ctx_free(struct tls_root_ctx *ctx)
Frees the library-specific TLSv1 context.
Definition: ssl_openssl.c:133
tls_ctx_set_cert_profile
void tls_ctx_set_cert_profile(struct tls_root_ctx *ctx, const char *profile)
Set the TLS certificate profile.
Definition: ssl_openssl.c:514
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.
Definition: ssl_openssl.c:1904
key_state_export_keying_material
bool key_state_export_keying_material(struct tls_session *session, const char *label, size_t label_size, void *ekm, size_t ekm_size)
Keying Material Exporters [RFC 5705] allows additional keying material to be derived from existing TL...
Definition: ssl_openssl.c:149
buffer
Wrapper structure for dynamically allocated memory.
Definition: buffer.h:60
key_state_write_plaintext
int key_state_write_plaintext(struct key_state_ssl *ks_ssl, struct buffer *buf)
Insert a plaintext buffer into the TLS module.
Definition: ssl_openssl.c:1965
get_highest_preference_tls_cipher
void get_highest_preference_tls_cipher(char *buf, int size)
Definition: ssl_openssl.c:2384
tls_ctx_set_tls_groups
void tls_ctx_set_tls_groups(struct tls_root_ctx *ctx, const char *groups)
Set the (elliptic curve) group allowed for signatures and key exchange.
Definition: ssl_openssl.c:553
tls_session
Security parameter state of a single session within a VPN tunnel.
Definition: ssl_common.h:471
buffer.h
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.
Definition: ssl_openssl.c:485
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 ...
Definition: ssl_openssl.c:613
pem_password_callback
int pem_password_callback(char *buf, int size, int rwflag, void *u)
Callback to retrieve the user's password.
Definition: ssl.c:253
tls_ctx_load_ca
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 certificate authority certificates from the given file or path.
Definition: ssl_openssl.c:1536
tls_root_ctx
Structure that wraps the TLS context.
Definition: ssl_mbedtls.h:106
show_available_curves
void show_available_curves(void)
Definition: ssl_openssl.c:2344
session
Definition: keyingmaterialexporter.c:56
key_state_write_plaintext_const
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.
Definition: ssl_openssl.c:1981
ssl_mbedtls.h
tls_ctx_load_pkcs12
int tls_ctx_load_pkcs12(struct tls_root_ctx *ctx, const char *pkcs12_file, bool 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.
Definition: ssl_openssl.c:772
tls_version_parse
int tls_version_parse(const char *vstr, const char *extra)
Definition: ssl.c:415
tls_clear_error
void tls_clear_error(void)
Clear the underlying SSL library's error state.
tls_ctx_load_dh_params
void tls_ctx_load_dh_params(struct tls_root_ctx *ctx, const char *dh_file, bool dh_file_inline)
Load Diffie Hellman Parameters, and load them into the library-specific TLS context.
Definition: ssl_openssl.c:649
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.
Definition: ssl_openssl.c:423
key_state_read_ciphertext
int key_state_read_ciphertext(struct key_state_ssl *ks_ssl, struct buffer *buf)
Extract ciphertext data from the TLS module.
Definition: ssl_openssl.c:1995
key_state_ssl_shutdown
void key_state_ssl_shutdown(struct key_state_ssl *ks_ssl)
Sets a TLS session to be shutdown state, so the TLS library will generate a shutdown alert.
Definition: ssl_openssl.c:1944
ssl_openssl.h