]>
git.ipfire.org Git - thirdparty/openvpn.git/blob - src/openvpn/ssl_backend.h
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
8 * Copyright (C) 2002-2024 OpenVPN Inc <sales@openvpn.net>
9 * Copyright (C) 2010-2021 Fox Crypto B.V. <openvpn@foxcrypto.com>
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.
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.
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.
26 * @file Control Channel SSL library backend module
30 #ifndef SSL_BACKEND_H_
31 #define SSL_BACKEND_H_
35 #ifdef ENABLE_CRYPTO_OPENSSL
36 #include "ssl_openssl.h"
37 #include "ssl_verify_openssl.h"
38 #define SSLAPI SSLAPI_OPENSSL
40 #ifdef ENABLE_CRYPTO_MBEDTLS
41 #include "ssl_mbedtls.h"
42 #include "ssl_verify_mbedtls.h"
43 #define SSLAPI SSLAPI_MBEDTLS
46 /* Ensure that SSLAPI got a sane value if SSL is disabled or unknown */
48 #define SSLAPI SSLAPI_NONE
52 * prototype for struct tls_session from ssl_common.h
58 * Functions implemented in ssl.c for use by the backend SSL library
63 * Callback to retrieve the user's password
65 * @param buf Buffer to return the password in
66 * @param size Size of the buffer
67 * @param rwflag Unused, needed for OpenSSL compatibility
68 * @param u Unused, needed for OpenSSL compatibility
70 int pem_password_callback(char *buf
, int size
, int rwflag
, void *u
);
74 * Functions used in ssl.c which must be implemented by the backend SSL library
79 * Perform any static initialisation necessary by the library.
80 * Called on OpenVPN initialisation
82 void tls_init_lib(void);
85 * Free any global SSL library-specific data structures.
87 void tls_free_lib(void);
90 * Clear the underlying SSL library's error state.
92 void tls_clear_error(void);
95 * Parse a TLS version specifier
97 * @param vstr The TLS version string
98 * @param extra An optional extra parameter, may be NULL
100 * @return One of the TLS_VER_x constants or TLS_VER_BAD
101 * if a parse error should be flagged.
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
);
112 * Return the maximum TLS version (as a TLS_VER_x constant)
113 * supported by current SSL implementation
115 * @return One of the TLS_VER_x constants (but not TLS_VER_BAD).
117 int tls_version_max(void);
120 * Initialise a library-specific TLS context for a server.
122 * @param ctx TLS context to initialise
124 void tls_ctx_server_new(struct tls_root_ctx
*ctx
);
127 * Initialises a library-specific TLS context for a client.
129 * @param ctx TLS context to initialise
131 void tls_ctx_client_new(struct tls_root_ctx
*ctx
);
134 * Frees the library-specific TLSv1 context
136 * @param ctx TLS context to free
138 void tls_ctx_free(struct tls_root_ctx
*ctx
);
141 * Checks whether the given TLS context is initialised
143 * @param ctx TLS context to check
145 * @return true if the context is initialised, false if not.
147 bool tls_ctx_initialised(struct tls_root_ctx
*ctx
);
150 * Set any library specific options.
152 * Examples include disabling session caching, the password callback to use,
153 * and session verification parameters.
155 * @param ctx TLS context to set options on
156 * @param ssl_flags SSL flags to set
158 * @return true on success, false otherwise.
160 bool tls_ctx_set_options(struct tls_root_ctx
*ctx
, unsigned int ssl_flags
);
163 * Restrict the list of ciphers that can be used within the TLS context for TLS 1.2
166 * @param ctx TLS context to restrict, must be valid.
167 * @param ciphers String containing : delimited cipher names, or NULL to use
170 void tls_ctx_restrict_ciphers(struct tls_root_ctx
*ctx
, const char *ciphers
);
173 * Restrict the list of ciphers that can be used within the TLS context for TLS 1.3
176 * @param ctx TLS context to restrict, must be valid.
177 * @param ciphers String containing : delimited cipher names, or NULL to use
180 void tls_ctx_restrict_ciphers_tls13(struct tls_root_ctx
*ctx
, const char *ciphers
);
183 * Set the TLS certificate profile. The profile defines which crypto
184 * algorithms may be used in the supplied certificate.
186 * @param ctx TLS context to restrict, must be valid.
187 * @param profile The profile name ('preferred', 'legacy' or 'suiteb').
188 * Defaults to 'preferred' if NULL.
190 void tls_ctx_set_cert_profile(struct tls_root_ctx
*ctx
, const char *profile
);
193 * Set the (elliptic curve) group allowed for signatures and
196 * @param ctx TLS context to restrict, must be valid.
197 * @param groups List of groups that will be allowed, in priority,
200 void tls_ctx_set_tls_groups(struct tls_root_ctx
*ctx
, const char *groups
);
203 * Check our certificate notBefore and notAfter fields, and warn if the cert is
204 * either not yet valid or has expired. Note that this is a non-fatal error,
205 * since we compare against the system time, which might be incorrect.
207 * @param ctx TLS context to get our certificate from.
209 void tls_ctx_check_cert_time(const struct tls_root_ctx
*ctx
);
212 * Load Diffie Hellman Parameters, and load them into the library-specific
215 * @param ctx TLS context to use
216 * @param dh_file The file name to load the parameters from, or
217 * a string containing the parameters in the case
219 * @param dh_file_inline True if dh_file is an inline file.
221 void tls_ctx_load_dh_params(struct tls_root_ctx
*ctx
, const char *dh_file
,
222 bool dh_file_inline
);
225 * Load Elliptic Curve Parameters, and load them into the library-specific
228 * @param ctx TLS context to use
229 * @param curve_name The name of the elliptic curve to load.
231 void tls_ctx_load_ecdh_params(struct tls_root_ctx
*ctx
, const char *curve_name
235 * Load PKCS #12 file for key, cert and (optionally) CA certs, and add to
236 * library-specific TLS context.
238 * @param ctx TLS context to use
239 * @param pkcs12_file The file name to load the information from, or
240 * a string containing the information in the case
242 * @param pkcs12_file_inline True if pkcs12_file is an inline file.
244 * @return 1 if an error occurred, 0 if parsing was
247 int tls_ctx_load_pkcs12(struct tls_root_ctx
*ctx
, const char *pkcs12_file
,
248 bool pkcs12_file_inline
, bool load_ca_file
);
251 * Use Windows cryptoapi for key and cert, and add to library-specific TLS
254 * @param ctx TLS context to use
255 * @param crypto_api_cert String representing the certificate to load.
257 #ifdef ENABLE_CRYPTOAPI
258 void tls_ctx_load_cryptoapi(struct tls_root_ctx
*ctx
, const char *cryptoapi_cert
);
263 * Load certificate file into the given TLS context. If the given certificate
264 * file contains a certificate chain, load the whole chain.
266 * @param ctx TLS context to use
267 * @param cert_file The file name to load the certificate from, or
268 * a string containing the certificate in the case
270 * @param cert_file_inline True if cert_file is an inline file.
272 void tls_ctx_load_cert_file(struct tls_root_ctx
*ctx
, const char *cert_file
,
273 bool cert_file_inline
);
276 * Load private key file into the given TLS context.
278 * @param ctx TLS context to use
279 * @param priv_key_file The file name to load the private key from, or
280 * a string containing the private key in the case
282 * @param priv_key_file_inline True if priv_key_file is an inline file
284 * @return 1 if an error occurred, 0 if parsing was
287 int tls_ctx_load_priv_file(struct tls_root_ctx
*ctx
, const char *priv_key_file
,
288 bool priv_key_file_inline
);
290 #ifdef ENABLE_MANAGEMENT
293 * Tell the management interface to load the given certificate and the external
294 * private key matching the given certificate.
296 * @param ctx TLS context to use
298 * @return 1 if an error occurred, 0 if successful.
300 int tls_ctx_use_management_external_key(struct tls_root_ctx
*ctx
);
302 #endif /* ENABLE_MANAGEMENT */
305 * Load certificate authority certificates from the given file or path.
307 * Note that not all SSL libraries support loading from a path.
309 * @param ctx TLS context to use
310 * @param ca_file The file name to load the CAs from, or
311 * a string containing the CAs in the case of
313 * @param ca_file_inline True if ca_file is an inline file
314 * @param ca_path The path to load the CAs from
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
);
320 * Load extra certificate authority certificates from the given file or path.
321 * These Load extra certificates that are part of our own certificate
322 * chain but shouldn't be included in the verify chain.
325 * @param ctx TLS context to use
326 * @param extra_certs_file The file name to load the certs from, or
327 * a string containing the certs in the
328 * case of inline files.
329 * @param extra_certs_file_inline True if extra_certs_file is an inline
332 void tls_ctx_load_extra_certs(struct tls_root_ctx
*ctx
,
333 const char *extra_certs_file
,
334 bool extra_certs_file_inline
);
336 #ifdef ENABLE_CRYPTO_MBEDTLS
338 * Add a personalisation string to the mbed TLS RNG, based on the certificate
339 * loaded into the given context.
341 * @param ctx TLS context to use
343 void tls_ctx_personalise_random(struct tls_root_ctx
*ctx
);
347 /* **************************************
349 * Key-state specific functions
351 ***************************************/
354 * Initialise the SSL channel part of the given key state. Settings will be
355 * loaded from a previously initialised TLS context.
357 * @param ks_ssl The SSL channel's state info to initialise
358 * @param ssl_ctx The TLS context to use when initialising the channel.
359 * @param is_server Initialise a server?
360 * @param session The session associated with the given key_state
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
);
366 * Free the SSL channel part of the given key state.
368 * @param ks_ssl The SSL channel's state info to free
370 void key_state_ssl_free(struct key_state_ssl
*ks_ssl
);
373 * Reload the Certificate Revocation List for the SSL channel
375 * @param ssl_ctx The TLS context to use when reloading the CRL
376 * @param crl_file The file name to load the CRL from, or
377 * an array containing the inline CRL.
378 * @param crl_inline True if crl_file is an inline CRL.
380 void backend_tls_ctx_reload_crl(struct tls_root_ctx
*ssl_ctx
,
381 const char *crl_file
, bool crl_inline
);
383 #define EXPORT_KEY_DATA_LABEL "EXPORTER-OpenVPN-datakeys"
384 #define EXPORT_P2P_PEERID_LABEL "EXPORTER-OpenVPN-p2p-peerid"
385 #define EXPORT_DYNAMIC_TLS_CRYPT_LABEL "EXPORTER-OpenVPN-dynamic-tls-crypt"
387 * Keying Material Exporters [RFC 5705] allows additional keying material to be
388 * derived from existing TLS channel. This exported keying material can then be
389 * used for a variety of purposes.
391 * @param session The session associated with the given key_state
392 * @param label The label to use when exporting the key
393 * @param label_size The size of the label to use when exporting the key
394 * @param ekm Buffer to return the exported key material in
395 * @param ekm_size The size of ekm, in bytes
396 * @returns true if exporting succeeded, false otherwise
399 key_state_export_keying_material(struct tls_session
*session
,
400 const char *label
, size_t label_size
,
401 void *ekm
, size_t ekm_size
);
403 /**************************************************************************/
404 /** @addtogroup control_tls
407 /** @name Functions for packets to be sent to a remote OpenVPN peer
411 * Insert a plaintext buffer into the TLS module.
413 * After successfully processing the data, the data in \a buf is zeroized,
414 * its length set to zero, and a value of \c 1 is returned.
416 * @param ks_ssl - The security parameter state for this %key
418 * @param buf - The plaintext message to process.
420 * @return The return value indicates whether the data was successfully
422 * - \c 1: All the data was processed successfully.
423 * - \c 0: The data was not processed, this function should be called
424 * again later to retry.
425 * - \c -1: An error occurred.
427 int key_state_write_plaintext(struct key_state_ssl
*ks_ssl
, struct buffer
*buf
);
430 * Insert plaintext data into the TLS module.
432 * @param ks_ssl - The security parameter state for this %key
434 * @param data - A pointer to the data to process.
435 * @param len - The length in bytes of the data to process.
437 * @return The return value indicates whether the data was successfully
439 * - \c 1: All the data was processed successfully.
440 * - \c 0: The data was not processed, this function should be called
441 * again later to retry.
442 * - \c -1: An error occurred.
444 int key_state_write_plaintext_const(struct key_state_ssl
*ks_ssl
,
445 const uint8_t *data
, int len
);
448 * Extract ciphertext data from the TLS module.
450 * If the \a buf buffer has a length other than zero, this function does
451 * not perform any action and returns 0.
453 * @param ks_ssl - The security parameter state for this %key
455 * @param buf - A buffer in which to store the ciphertext.
457 * @return The return value indicates whether the data was successfully
459 * - \c 1: Data was extracted successfully.
460 * - \c 0: No data was extracted, this function should be called again
462 * - \c -1: An error occurred.
464 int key_state_read_ciphertext(struct key_state_ssl
*ks_ssl
, struct buffer
*buf
);
467 /** @} name Functions for packets to be sent to a remote OpenVPN peer */
470 /** @name Functions for packets received from a remote OpenVPN peer
474 * Insert a ciphertext buffer into the TLS module.
476 * After successfully processing the data, the data in \a buf is zeroized,
477 * its length set to zero, and a value of \c 1 is returned.
479 * @param ks_ssl - The security parameter state for this %key
481 * @param buf - The ciphertext message to process.
483 * @return The return value indicates whether the data was successfully
485 * - \c 1: All the data was processed successfully.
486 * - \c 0: The data was not processed, this function should be called
487 * again later to retry.
488 * - \c -1: An error occurred.
490 int key_state_write_ciphertext(struct key_state_ssl
*ks_ssl
,
494 * Extract plaintext data from the TLS module.
496 * If the \a buf buffer has a length other than zero, this function does
497 * not perform any action and returns 0.
499 * @param ks_ssl - The security parameter state for this %key
501 * @param buf - A buffer in which to store the plaintext.
502 * @param maxlen - The maximum number of bytes to extract.
504 * @return The return value indicates whether the data was successfully
506 * - \c 1: Data was extracted successfully.
507 * - \c 0: No data was extracted, this function should be called again
509 * - \c -1: An error occurred.
511 int key_state_read_plaintext(struct key_state_ssl
*ks_ssl
, struct buffer
*buf
);
513 /** @} name Functions for packets received from a remote OpenVPN peer */
515 /** @} addtogroup control_tls */
517 /* **************************************
519 * Information functions
521 * Print information for the end user.
523 ***************************************/
526 * Print a one line summary of SSL/TLS session handshake.
528 void print_details(struct key_state_ssl
*ks_ssl
, const char *prefix
);
531 * Show the TLS ciphers that are available for us to use in the
532 * library depending on the TLS version. This function prints
533 * a list of ciphers without headers/footers.
535 * @param cipher_list list of allowed TLS cipher, or NULL.
536 * @param tls_cert_profile TLS certificate crypto profile name.
537 * @param tls13 Select if <=TLS1.2 or TLS1.3+ ciphers
541 show_available_tls_ciphers_list(const char *cipher_list
,
542 const char *tls_cert_profile
,
546 * Show the available elliptic curves in the crypto library
548 void show_available_curves(void);
551 * The OpenSSL library has a notion of preference in TLS ciphers. Higher
552 * preference == more secure. Return the highest preference cipher.
554 void get_highest_preference_tls_cipher(char *buf
, int size
);
557 * return a pointer to a static memory area containing the
558 * name and version number of the SSL library in use
560 const char *get_ssl_library_version(void);
562 #endif /* SSL_BACKEND_H_ */