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-2022 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 
62 typedef struct { const char *openssl_name; const char *iana_name; } tls_cipher_name_pair;
63 const tls_cipher_name_pair *tls_get_cipher_name_pair(const char *cipher_name, size_t len);
64 
65 /*
66  *
67  * Functions implemented in ssl.c for use by the backend SSL library
68  *
69  */
70 
79 int pem_password_callback(char *buf, int size, int rwflag, void *u);
80 
81 /*
82  *
83  * Functions used in ssl.c which must be implemented by the backend SSL library
84  *
85  */
86 
91 void tls_init_lib(void);
92 
96 void tls_free_lib(void);
97 
101 void tls_clear_error(void);
102 
112 #define TLS_VER_BAD -1
113 #define TLS_VER_UNSPEC 0 /* default */
114 #define TLS_VER_1_0 1
115 #define TLS_VER_1_1 2
116 #define TLS_VER_1_2 3
117 #define TLS_VER_1_3 4
118 int tls_version_parse(const char *vstr, const char *extra);
119 
126 int tls_version_max(void);
127 
133 void tls_ctx_server_new(struct tls_root_ctx *ctx);
134 
140 void tls_ctx_client_new(struct tls_root_ctx *ctx);
141 
147 void tls_ctx_free(struct tls_root_ctx *ctx);
148 
156 bool tls_ctx_initialised(struct tls_root_ctx *ctx);
157 
169 bool tls_ctx_set_options(struct tls_root_ctx *ctx, unsigned int ssl_flags);
170 
179 void tls_ctx_restrict_ciphers(struct tls_root_ctx *ctx, const char *ciphers);
180 
189 void tls_ctx_restrict_ciphers_tls13(struct tls_root_ctx *ctx, const char *ciphers);
190 
199 void tls_ctx_set_cert_profile(struct tls_root_ctx *ctx, const char *profile);
200 
209 void tls_ctx_set_tls_groups(struct tls_root_ctx *ctx, const char *groups);
210 
218 void tls_ctx_check_cert_time(const struct tls_root_ctx *ctx);
219 
230 void tls_ctx_load_dh_params(struct tls_root_ctx *ctx, const char *dh_file,
231  bool dh_file_inline);
232 
240 void tls_ctx_load_ecdh_params(struct tls_root_ctx *ctx, const char *curve_name
241  );
242 
256 int tls_ctx_load_pkcs12(struct tls_root_ctx *ctx, const char *pkcs12_file,
257  bool pkcs12_file_inline, bool load_ca_file);
258 
266 #ifdef ENABLE_CRYPTOAPI
267 void tls_ctx_load_cryptoapi(struct tls_root_ctx *ctx, const char *cryptoapi_cert);
268 
269 #endif /* _WIN32 */
270 
281 void tls_ctx_load_cert_file(struct tls_root_ctx *ctx, const char *cert_file,
282  bool cert_file_inline);
283 
296 int tls_ctx_load_priv_file(struct tls_root_ctx *ctx, const char *priv_key_file,
297  bool priv_key_file_inline);
298 
299 #ifdef ENABLE_MANAGEMENT
300 
310 
311 #endif /* ENABLE_MANAGEMENT */
312 
325 void tls_ctx_load_ca(struct tls_root_ctx *ctx, const char *ca_file,
326  bool ca_file_inline, const char *ca_path, bool tls_server);
327 
341 void tls_ctx_load_extra_certs(struct tls_root_ctx *ctx,
342  const char *extra_certs_file,
343  bool extra_certs_file_inline);
344 
345 #ifdef ENABLE_CRYPTO_MBEDTLS
346 
352 void tls_ctx_personalise_random(struct tls_root_ctx *ctx);
353 
354 #endif
355 
356 /* **************************************
357  *
358  * Key-state specific functions
359  *
360  ***************************************/
361 
371 void key_state_ssl_init(struct key_state_ssl *ks_ssl,
372  const struct tls_root_ctx *ssl_ctx, bool is_server, struct tls_session *session);
373 
379 void key_state_ssl_free(struct key_state_ssl *ks_ssl);
380 
389 void backend_tls_ctx_reload_crl(struct tls_root_ctx *ssl_ctx,
390  const char *crl_file, bool crl_inline);
391 
392 #define EXPORT_KEY_DATA_LABEL "EXPORTER-OpenVPN-datakeys"
393 #define EXPORT_P2P_PEERID_LABEL "EXPORTER-OpenVPN-p2p-peerid"
394 
406 bool
408  const char *label, size_t label_size,
409  void *ekm, size_t ekm_size);
410 
411 /**************************************************************************/
435 int key_state_write_plaintext(struct key_state_ssl *ks_ssl, struct buffer *buf);
436 
453  const uint8_t *data, int len);
454 
473 int key_state_read_ciphertext(struct key_state_ssl *ks_ssl, struct buffer *buf,
474  int maxlen);
475 
499 int key_state_write_ciphertext(struct key_state_ssl *ks_ssl,
500  struct buffer *buf);
501 
520 int key_state_read_plaintext(struct key_state_ssl *ks_ssl, struct buffer *buf,
521  int maxlen);
522 
527 /* **************************************
528  *
529  * Information functions
530  *
531  * Print information for the end user.
532  *
533  ***************************************/
534 
535 /*
536  * Print a one line summary of SSL/TLS session handshake.
537  */
538 void print_details(struct key_state_ssl *ks_ssl, const char *prefix);
539 
540 /*
541  * Show the TLS ciphers that are available for us to use in the
542  * library depending on the TLS version. This function prints
543  * a list of ciphers without headers/footers.
544  *
545  * @param cipher_list list of allowed TLS cipher, or NULL.
546  * @param tls_cert_profile TLS certificate crypto profile name.
547  * @param tls13 Select if <=TLS1.2 or TLS1.3+ ciphers
548  * should be shown
549  */
550 void
551 show_available_tls_ciphers_list(const char *cipher_list,
552  const char *tls_cert_profile,
553  bool tls13);
554 
555 /*
556  * Show the available elliptic curves in the crypto library
557  */
558 void show_available_curves(void);
559 
560 /*
561  * The OpenSSL library has a notion of preference in TLS ciphers. Higher
562  * preference == more secure. Return the highest preference cipher.
563  */
564 void get_highest_preference_tls_cipher(char *buf, int size);
565 
570 const char *get_ssl_library_version(void);
571 
572 #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:1970
tls_ctx_load_cert_file
void tls_ctx_load_cert_file(struct tls_root_ctx *ctx, const char *cert_file, bool cert_file_inline)
Use Windows cryptoapi for key and cert, and add to library-specific TLS context.
Definition: ssl_openssl.c:970
key_state_read_plaintext
int key_state_read_plaintext(struct key_state_ssl *ks_ssl, struct buffer *buf, int maxlen)
Extract plaintext data from the TLS module.
Definition: ssl_openssl.c:2045
key_state_ssl
Definition: ssl_mbedtls.h:125
tls_init_lib
void tls_init_lib(void)
Perform any static initialisation necessary by the library.
Definition: ssl_openssl.c:86
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:1031
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:723
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:2305
print_details
void print_details(struct key_state_ssl *ks_ssl, const char *prefix)
Definition: ssl_openssl.c:2143
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:1701
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:129
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:111
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:2167
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:317
ssl_verify_openssl.h
tls_free_lib
void tls_free_lib(void)
Free any global SSL library-specific data structures.
Definition: ssl_openssl.c:100
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:1092
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:1480
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:2030
tls_ctx_initialised
bool tls_ctx_initialised(struct tls_root_ctx *ctx)
Checks whether the given TLS context is initialised.
Definition: ssl_openssl.c:156
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:214
tls_ctx_free
void tls_ctx_free(struct tls_root_ctx *ctx)
Frees the library-specific TLSv1 context.
Definition: ssl_openssl.c:147
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:528
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:1930
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:163
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:1985
get_highest_preference_tls_cipher
void get_highest_preference_tls_cipher(char *buf, int size)
Definition: ssl_openssl.c:2280
tls_ctx_load_cryptoapi
void tls_ctx_load_cryptoapi(struct tls_root_ctx *ctx, const char *cryptoapi_cert)
Definition: ssl_openssl.c:923
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:566
tls_session
Security parameter state of a single session within a VPN tunnel.
Definition: ssl_common.h:439
buffer.h
key_state_read_ciphertext
int key_state_read_ciphertext(struct key_state_ssl *ks_ssl, struct buffer *buf, int maxlen)
Extract ciphertext data from the TLS module.
Definition: ssl_openssl.c:2015
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:499
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:626
tls_cipher_name_pair::openssl_name
const char * openssl_name
Definition: ssl_backend.h:62
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:370
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:1552
tls_root_ctx
Structure that wraps the TLS context.
Definition: ssl_mbedtls.h:104
show_available_curves
void show_available_curves(void)
Definition: ssl_openssl.c:2242
session
Definition: keyingmaterialexporter.c:56
tls_get_cipher_name_pair
const tls_cipher_name_pair * tls_get_cipher_name_pair(const char *cipher_name, size_t len)
Definition: ssl.c:259
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:2001
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:794
tls_version_parse
int tls_version_parse(const char *vstr, const char *extra)
Definition: ssl.c:509
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:662
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:437
tls_cipher_name_pair
Get a tls_cipher_name_pair containing OpenSSL and IANA names for supplied TLS cipher name.
Definition: ssl_backend.h:62
ssl_openssl.h