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-2018 OpenVPN Inc <sales@openvpn.net>
9  * Copyright (C) 2010-2018 Fox Crypto B.V. <openvpn@fox-it.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 
208 void tls_ctx_check_cert_time(const struct tls_root_ctx *ctx);
209 
219 void tls_ctx_load_dh_params(struct tls_root_ctx *ctx, const char *dh_file,
220  const char *dh_file_inline);
221 
229 void tls_ctx_load_ecdh_params(struct tls_root_ctx *ctx, const char *curve_name
230  );
231 
244 int tls_ctx_load_pkcs12(struct tls_root_ctx *ctx, const char *pkcs12_file,
245  const char *pkcs12_file_inline, bool load_ca_file
246  );
247 
255 #ifdef ENABLE_CRYPTOAPI
256 void tls_ctx_load_cryptoapi(struct tls_root_ctx *ctx, const char *cryptoapi_cert);
257 
258 #endif /* _WIN32 */
259 
269 void tls_ctx_load_cert_file(struct tls_root_ctx *ctx, const char *cert_file,
270  const char *cert_file_inline);
271 
283 int tls_ctx_load_priv_file(struct tls_root_ctx *ctx, const char *priv_key_file,
284  const char *priv_key_file_inline);
285 
286 #ifdef ENABLE_MANAGEMENT
287 
297 
298 #endif /* ENABLE_MANAGEMENT */
299 
311 void tls_ctx_load_ca(struct tls_root_ctx *ctx, const char *ca_file,
312  const char *ca_file_inline, const char *ca_path, bool tls_server
313  );
314 
326 void tls_ctx_load_extra_certs(struct tls_root_ctx *ctx, const char *extra_certs_file,
327  const char *extra_certs_file_inline
328  );
329 
330 #ifdef ENABLE_CRYPTO_MBEDTLS
331 
337 void tls_ctx_personalise_random(struct tls_root_ctx *ctx);
338 
339 #endif
340 
341 /* **************************************
342  *
343  * Key-state specific functions
344  *
345  ***************************************/
346 
356 void key_state_ssl_init(struct key_state_ssl *ks_ssl,
357  const struct tls_root_ctx *ssl_ctx, bool is_server, struct tls_session *session);
358 
364 void key_state_ssl_free(struct key_state_ssl *ks_ssl);
365 
374 void backend_tls_ctx_reload_crl(struct tls_root_ctx *ssl_ctx,
375  const char *crl_file, const char *crl_inline);
376 
386 void
388  struct tls_session *session) __attribute__((nonnull));
389 
390 /**************************************************************************/
414 int key_state_write_plaintext(struct key_state_ssl *ks_ssl, struct buffer *buf);
415 
432  const uint8_t *data, int len);
433 
452 int key_state_read_ciphertext(struct key_state_ssl *ks_ssl, struct buffer *buf,
453  int maxlen);
454 
478 int key_state_write_ciphertext(struct key_state_ssl *ks_ssl,
479  struct buffer *buf);
480 
499 int key_state_read_plaintext(struct key_state_ssl *ks_ssl, struct buffer *buf,
500  int maxlen);
501 
506 /* **************************************
507  *
508  * Information functions
509  *
510  * Print information for the end user.
511  *
512  ***************************************/
513 
514 /*
515  * Print a one line summary of SSL/TLS session handshake.
516  */
517 void print_details(struct key_state_ssl *ks_ssl, const char *prefix);
518 
519 /*
520  * Show the TLS ciphers that are available for us to use in the
521  * library depending on the TLS version. This function prints
522  * a list of ciphers without headers/footers.
523  *
524  * @param cipher_list list of allowed TLS cipher, or NULL.
525  * @param tls_cert_profile TLS certificate crypto profile name.
526  * @param tls13 Select if <=TLS1.2 or TLS1.3+ ciphers
527  * should be shown
528  */
529 void
530 show_available_tls_ciphers_list(const char *cipher_list,
531  const char *tls_cert_profile,
532  bool tls13);
533 
534 /*
535  * Show the available elliptic curves in the crypto library
536  */
537 void show_available_curves(void);
538 
539 /*
540  * The OpenSSL library has a notion of preference in TLS ciphers. Higher
541  * preference == more secure. Return the highest preference cipher.
542  */
543 void get_highest_preference_tls_cipher(char *buf, int size);
544 
549 const char *get_ssl_library_version(void);
550 
551 #endif /* SSL_BACKEND_H_ */
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...
Definition: ssl_openssl.c:700
void tls_ctx_load_cryptoapi(struct tls_root_ctx *ctx, const char *cryptoapi_cert)
Definition: ssl_openssl.c:829
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:617
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:1871
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:1838
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.
Definition: ssl_openssl.c:997
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 TL...
Definition: ssl_openssl.c:149
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:1853
void tls_free_lib(void)
Free any global SSL library-specific data structures.
Definition: ssl_openssl.c:90
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:2133
void tls_ctx_client_new(struct tls_root_ctx *ctx)
Initialises a library-specific TLS context for a client.
Definition: ssl_openssl.c:118
void tls_ctx_set_cert_profile(struct tls_root_ctx *ctx, const char *profile)
Set the TLS certificate profile.
Definition: ssl_openssl.c:488
void get_highest_preference_tls_cipher(char *buf, int size)
Definition: ssl_openssl.c:2108
void print_details(struct key_state_ssl *ks_ssl, const char *prefix)
Definition: ssl_openssl.c:1937
void tls_ctx_free(struct tls_root_ctx *ctx)
Frees the library-specific TLSv1 context.
Definition: ssl_openssl.c:131
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:1798
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.
Definition: ssl_openssl.c:1571
int tls_version_parse(const char *vstr, const char *extra)
Definition: ssl.c:516
bool tls_ctx_initialised(struct tls_root_ctx *ctx)
Checks whether the given TLS context is initialised.
Definition: ssl_openssl.c:142
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:397
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:459
void tls_ctx_server_new(struct tls_root_ctx *ctx)
Initialise a library-specific TLS context for a server.
Definition: ssl_openssl.c:105
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:1915
Get a tls_cipher_name_pair containing OpenSSL and IANA names for supplied TLS cipher name...
Definition: ssl_backend.h:62
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:522
void show_available_tls_ciphers_list(const char *cipher_list, const char *tls_cert_profile, bool tls13)
Definition: ssl_openssl.c:1997
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.
Definition: ssl_openssl.c:1418
unsigned __int8 uint8_t
Definition: config-msvc.h:123
Structure that wraps the TLS context.
Definition: ssl_mbedtls.h:90
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.
Definition: ssl_openssl.c:573
Security parameter state of a single session within a VPN tunnel.
Definition: ssl_common.h:407
bool tls_ctx_set_options(struct tls_root_ctx *ctx, unsigned int ssl_flags)
Set any library specific options.
Definition: ssl_openssl.c:281
const tls_cipher_name_pair * tls_get_cipher_name_pair(const char *cipher_name, size_t len)
Definition: ssl.c:269
Wrapper structure for dynamically allocated memory.
Definition: buffer.h:60
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.
Definition: ssl_openssl.c:930
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:1900
void tls_init_lib(void)
Perform any static initialisation necessary by the library.
Definition: ssl_openssl.c:77
void tls_clear_error(void)
Clear the underlying SSL library&#39;s error state.
Definition: ssl_openssl.c:99
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.
Definition: ssl_openssl.c:864
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:212
const char * openssl_name
Definition: ssl_backend.h:62
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:1341
int pem_password_callback(char *buf, int size, int rwflag, void *u)
Callback to retrieve the user&#39;s password.
Definition: ssl.c:381
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:1885
void show_available_curves(void)
Definition: ssl_openssl.c:2072