OpenVPN
crypto_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 
29 #ifndef CRYPTO_BACKEND_H_
30 #define CRYPTO_BACKEND_H_
31 
32 #ifdef ENABLE_CRYPTO_OPENSSL
33 #include "crypto_openssl.h"
34 #endif
35 #ifdef ENABLE_CRYPTO_MBEDTLS
36 #include "crypto_mbedtls.h"
37 #endif
38 #include "basic.h"
39 #include "buffer.h"
40 
41 /* TLS uses a tag of 128 bytes, let's do the same for OpenVPN */
42 #define OPENVPN_AEAD_TAG_LENGTH 16
43 
44 /* Maximum cipher block size (bytes) */
45 #define OPENVPN_MAX_CIPHER_BLOCK_SIZE 32
46 
47 /* Maximum HMAC digest size (bytes) */
48 #define OPENVPN_MAX_HMAC_SIZE 64
49 
51 typedef enum {
55 
57 typedef struct {
58  const char *openvpn_name;
59  const char *lib_name;
61 
64 extern const size_t cipher_name_translation_table_count;
65 
66 /*
67  * This routine should have additional OpenSSL crypto library initialisations
68  * used by both crypto and ssl components of OpenVPN.
69  */
70 void crypto_init_lib(void);
71 
72 void crypto_uninit_lib(void);
73 
74 void crypto_clear_error(void);
75 
76 /*
77  * Initialise the given named crypto engine.
78  */
79 void crypto_init_lib_engine(const char *engine_name);
80 
81 
87 provider_t *crypto_load_provider(const char *provider);
88 
94 void crypto_unload_provider(const char *provname, provider_t *provider);
95 
96 #ifdef DMALLOC
97 /*
98  * OpenSSL memory debugging. If dmalloc debugging is enabled, tell
99  * OpenSSL to use our private malloc/realloc/free functions so that
100  * we can dispatch them to dmalloc.
101  */
102 void crypto_init_dmalloc(void);
103 
104 #endif /* DMALLOC */
105 
106 void show_available_ciphers(void);
107 
108 void show_available_digests(void);
109 
110 void show_available_engines(void);
111 
125 bool crypto_pem_encode(const char *name, struct buffer *dst,
126  const struct buffer *src, struct gc_arena *gc);
127 
137 bool crypto_pem_decode(const char *name, struct buffer *dst,
138  const struct buffer *src);
139 
140 /*
141  *
142  * Random number functions, used in cases where we want
143  * reasonably strong cryptographic random number generation
144  * without depleting our entropy pool. Used for random
145  * IV values and a number of other miscellaneous tasks.
146  *
147  */
148 
158 int rand_bytes(uint8_t *output, int len);
159 
160 /*
161  *
162  * Generic cipher key type functions
163  *
164  */
165 /*
166  * Max size in bytes of any cipher key that might conceivably be used.
167  *
168  * This value is checked at compile time in crypto.c to make sure
169  * it is always at least EVP_MAX_KEY_LENGTH.
170  *
171  * We define our own value, since this parameter
172  * is used to control the size of static key files.
173  * If the OpenSSL library increases EVP_MAX_KEY_LENGTH,
174  * we don't want our key files to be suddenly rendered
175  * unusable.
176  */
177 #define MAX_CIPHER_KEY_LENGTH 64
178 
192 bool cipher_valid_reason(const char *ciphername, const char **reason);
193 
203 static inline bool
204 cipher_valid(const char *ciphername)
205 {
206  const char *reason;
207  return cipher_valid_reason(ciphername, &reason);
208 }
209 
217 static inline bool
218 cipher_defined(const char *ciphername)
219 {
220  ASSERT(ciphername);
221  return strcmp(ciphername, "none") != 0;
222 }
223 
236 const char *cipher_kt_name(const char *ciphername);
237 
246 int cipher_kt_key_size(const char *ciphername);
247 
257 int cipher_kt_iv_size(const char *ciphername);
258 
266 int cipher_kt_block_size(const char *ciphername);
267 
276 int cipher_kt_tag_size(const char *ciphername);
277 
281 bool cipher_kt_insecure(const char *ciphername);
282 
283 
291 bool cipher_kt_mode_cbc(const char *ciphername);
292 
300 bool cipher_kt_mode_ofb_cfb(const char *ciphername);
301 
309 bool cipher_kt_mode_aead(const char *ciphername);
310 
311 
324 
330 void cipher_ctx_free(cipher_ctx_t *ctx);
331 
341 void cipher_ctx_init(cipher_ctx_t *ctx, const uint8_t *key,
342  const char *cipername, crypto_operation_t enc);
343 
353 int cipher_ctx_iv_length(const cipher_ctx_t *ctx);
354 
362 int cipher_ctx_get_tag(cipher_ctx_t *ctx, uint8_t *tag, int tag_len);
363 
371 int cipher_ctx_block_size(const cipher_ctx_t *ctx);
372 
381 int cipher_ctx_mode(const cipher_ctx_t *ctx);
382 
390 bool cipher_ctx_mode_cbc(const cipher_ctx_t *ctx);
391 
399 bool cipher_ctx_mode_ofb_cfb(const cipher_ctx_t *ctx);
400 
408 bool cipher_ctx_mode_aead(const cipher_ctx_t *ctx);
409 
419 int cipher_ctx_reset(cipher_ctx_t *ctx, const uint8_t *iv_buf);
420 
431 int cipher_ctx_update_ad(cipher_ctx_t *ctx, const uint8_t *src, int src_len);
432 
450 int cipher_ctx_update(cipher_ctx_t *ctx, uint8_t *dst, int *dst_len,
451  uint8_t *src, int src_len);
452 
463 int cipher_ctx_final(cipher_ctx_t *ctx, uint8_t *dst, int *dst_len);
464 
478 int cipher_ctx_final_check_tag(cipher_ctx_t *ctx, uint8_t *dst, int *dst_len,
479  uint8_t *tag, size_t tag_len);
480 
481 
482 /*
483  *
484  * Generic message digest information functions
485  *
486  */
487 
488 /*
489  * Max size in bytes of any HMAC key that might conceivably be used.
490  *
491  * This value is checked at compile time in crypto.c to make sure
492  * it is always at least EVP_MAX_MD_SIZE. We define our own value
493  * for the same reason as above.
494  */
495 #define MAX_HMAC_KEY_LENGTH 64
496 
503 static inline bool
504 md_defined(const char *mdname)
505 {
506  return strcmp(mdname, "none") != 0;
507 }
508 
509 
517 bool md_valid(const char *digest);
518 
527 const char *md_kt_name(const char *mdname);
528 
536 unsigned char md_kt_size(const char *mdname);
537 
538 
539 /*
540  *
541  * Generic message digest functions
542  *
543  */
544 
555 int md_full(const char *mdname, const uint8_t *src, int src_len, uint8_t *dst);
556 
557 /*
558  * Allocate a new message digest context
559  *
560  * @return a new zeroed MD context
561  */
562 md_ctx_t *md_ctx_new(void);
563 
564 /*
565  * Free an existing, non-null message digest context
566  *
567  * @param ctx Message digest context
568  */
569 void md_ctx_free(md_ctx_t *ctx);
570 
577 void md_ctx_init(md_ctx_t *ctx, const char *mdname);
578 
579 /*
580  * Free the given message digest context.
581  *
582  * @param ctx Message digest context
583  */
584 void md_ctx_cleanup(md_ctx_t *ctx);
585 
586 /*
587  * Returns the size of the message digest output by the given context
588  *
589  * @param ctx Message digest context.
590  *
591  * @return Size of the message digest, or \0 if ctx is NULL.
592  */
593 int md_ctx_size(const md_ctx_t *ctx);
594 
595 /*
596  * Process the given data for use in the message digest.
597  *
598  * @param ctx Message digest context. May not be NULL.
599  * @param src Buffer to digest. May not be NULL.
600  * @param src_len The length of the incoming buffer.
601  */
602 void md_ctx_update(md_ctx_t *ctx, const uint8_t *src, int src_len);
603 
604 /*
605  * Output the message digest to the given buffer.
606  *
607  * @param ctx Message digest context. May not be NULL.
608  * @param dst Buffer to write the message digest to. May not be NULL.
609  */
610 void md_ctx_final(md_ctx_t *ctx, uint8_t *dst);
611 
612 
613 /*
614  *
615  * Generic HMAC functions
616  *
617  */
618 
619 /*
620  * Create a new HMAC context
621  *
622  * @return A new HMAC context
623  */
624 hmac_ctx_t *hmac_ctx_new(void);
625 
626 /*
627  * Free an existing HMAC context
628  *
629  * @param ctx HMAC context to free
630  */
631 void hmac_ctx_free(hmac_ctx_t *ctx);
632 
633 /*
634  * Initialises the given HMAC context, using the given digest
635  * and key.
636  *
637  * @param ctx HMAC context to initialise
638  * @param key The key to use for the HMAC
639  * @param mdname message digest name
640  *
641  */
642 void hmac_ctx_init(hmac_ctx_t *ctx, const uint8_t *key, const char *mdname);
643 
644 
645 /*
646  * Free the given HMAC context.
647  *
648  * @param ctx HMAC context
649  */
650 void hmac_ctx_cleanup(hmac_ctx_t *ctx);
651 
652 /*
653  * Returns the size of the HMAC output by the given HMAC Context
654  *
655  * @param ctx HMAC context.
656  *
657  * @return Size of the HMAC, or \0 if ctx is NULL.
658  */
659 int hmac_ctx_size(hmac_ctx_t *ctx);
660 
661 /*
662  * Resets the given HMAC context, preserving the associated key information
663  *
664  * @param ctx HMAC context. May not be NULL.
665  */
666 void hmac_ctx_reset(hmac_ctx_t *ctx);
667 
668 /*
669  * Process the given data for use in the HMAC.
670  *
671  * @param ctx HMAC context. May not be NULL.
672  * @param src The buffer to HMAC. May not be NULL.
673  * @param src_len The length of the incoming buffer.
674  */
675 void hmac_ctx_update(hmac_ctx_t *ctx, const uint8_t *src, int src_len);
676 
677 /*
678  * Output the HMAC to the given buffer.
679  *
680  * @param ctx HMAC context. May not be NULL.
681  * @param dst buffer to write the HMAC to. May not be NULL.
682  */
683 void hmac_ctx_final(hmac_ctx_t *ctx, uint8_t *dst);
684 
693 const char *translate_cipher_name_from_openvpn(const char *cipher_name);
694 
703 const char *translate_cipher_name_to_openvpn(const char *cipher_name);
704 
705 
719 bool ssl_tls1_PRF(const uint8_t *seed, int seed_len, const uint8_t *secret,
720  int secret_len, uint8_t *output, int output_len);
721 
722 #endif /* CRYPTO_BACKEND_H_ */
md_full
int md_full(const char *mdname, const uint8_t *src, int src_len, uint8_t *dst)
Calculates the message digest for the given buffer.
Definition: crypto_openssl.c:1114
cipher_ctx_new
cipher_ctx_t * cipher_ctx_new(void)
Generic cipher functions.
Definition: crypto_openssl.c:848
crypto_uninit_lib
void crypto_uninit_lib(void)
Definition: crypto_openssl.c:209
cipher_valid
static bool cipher_valid(const char *ciphername)
Returns if the cipher is valid, based on the given cipher name.
Definition: crypto_backend.h:204
hmac_ctx_cleanup
void hmac_ctx_cleanup(hmac_ctx_t *ctx)
cipher_ctx_iv_length
int cipher_ctx_iv_length(const cipher_ctx_t *ctx)
Returns the size of the IV used by the cipher, in bytes, or 0 if no IV is used.
hmac_ctx_t
mbedtls_md_context_t hmac_ctx_t
Generic HMAC context.
Definition: crypto_mbedtls.h:46
cipher_defined
static bool cipher_defined(const char *ciphername)
Checks if the cipher is defined and is not the null (none) cipher.
Definition: crypto_backend.h:218
md_ctx_t
mbedtls_md_context_t md_ctx_t
Generic message digest context.
Definition: crypto_mbedtls.h:43
cipher_ctx_final_check_tag
int cipher_ctx_final_check_tag(cipher_ctx_t *ctx, uint8_t *dst, int *dst_len, uint8_t *tag, size_t tag_len)
Like cipher_ctx_final, but check the computed authentication tag against the supplied (expected) tag.
translate_cipher_name_to_openvpn
const char * translate_cipher_name_to_openvpn(const char *cipher_name)
Translate a crypto library cipher name to an OpenVPN cipher name.
Definition: crypto.c:1687
show_available_ciphers
void show_available_ciphers(void)
Definition: crypto_openssl.c:369
md_ctx_size
int md_ctx_size(const md_ctx_t *ctx)
cipher_ctx_mode_cbc
bool cipher_ctx_mode_cbc(const cipher_ctx_t *ctx)
Check if the supplied cipher is a supported CBC mode cipher.
Definition: crypto_openssl.c:905
hmac_ctx_update
void hmac_ctx_update(hmac_ctx_t *ctx, const uint8_t *src, int src_len)
cipher_kt_name
const char * cipher_kt_name(const char *ciphername)
Retrieve a normalised string describing the cipher (e.g.
Definition: crypto_openssl.c:659
crypto_openssl.h
md_ctx_new
md_ctx_t * md_ctx_new(void)
Definition: crypto_openssl.c:1125
cipher_ctx_mode_ofb_cfb
bool cipher_ctx_mode_ofb_cfb(const cipher_ctx_t *ctx)
Check if the supplied cipher is a supported OFB or CFB mode cipher.
Definition: crypto_openssl.c:924
cipher_ctx_final
int cipher_ctx_final(cipher_ctx_t *ctx, uint8_t *dst, int *dst_len)
Pads the final cipher block using PKCS padding, and output to the destination buffer.
key
Container for unidirectional cipher and HMAC key material.
Definition: crypto.h:149
cipher_ctx_free
void cipher_ctx_free(cipher_ctx_t *ctx)
Cleanup and free a cipher context.
MD_SHA256
@ MD_SHA256
Definition: crypto_backend.h:53
crypto_mbedtls.h
cipher_kt_block_size
int cipher_kt_block_size(const char *ciphername)
Returns the block size of the cipher, in bytes.
Definition: crypto_openssl.c:697
cipher_name_translation_table
const cipher_name_pair cipher_name_translation_table[]
Cipher name translation table.
Definition: crypto_openssl.c:316
md_ctx_final
void md_ctx_final(md_ctx_t *ctx, uint8_t *dst)
ASSERT
#define ASSERT(x)
Definition: error.h:195
md_kt_name
const char * md_kt_name(const char *mdname)
Retrieve a string describing the digest digest (e.g.
Definition: crypto_openssl.c:1070
cipher_valid_reason
bool cipher_valid_reason(const char *ciphername, const char **reason)
Returns if the cipher is valid, based on the given cipher name and provides a reason if invalid.
Definition: crypto_openssl.c:618
cipher_name_pair::openvpn_name
const char * openvpn_name
Cipher name used by OpenVPN.
Definition: crypto_backend.h:58
cipher_ctx_t
mbedtls_cipher_context_t cipher_ctx_t
Generic cipher context.
Definition: crypto_mbedtls.h:40
md_ctx_cleanup
void md_ctx_cleanup(md_ctx_t *ctx)
cipher_ctx_update
int cipher_ctx_update(cipher_ctx_t *ctx, uint8_t *dst, int *dst_len, uint8_t *src, int src_len)
Updates the given cipher context, encrypting data in the source buffer, and placing any complete bloc...
cipher_ctx_init
void cipher_ctx_init(cipher_ctx_t *ctx, const uint8_t *key, const char *cipername, crypto_operation_t enc)
Initialise a cipher context, based on the given key and key type.
crypto_init_lib
void crypto_init_lib(void)
Definition: crypto_openssl.c:194
crypto_clear_error
void crypto_clear_error(void)
Definition: crypto_openssl.c:229
hash_algo_type
hash_algo_type
Types referencing specific message digest hashing algorithms.
Definition: crypto_backend.h:51
cipher_ctx_mode
int cipher_ctx_mode(const cipher_ctx_t *ctx)
Returns the mode that the cipher runs in.
md_kt_size
unsigned char md_kt_size(const char *mdname)
Returns the size of the message digest, in bytes.
Definition: crypto_openssl.c:1094
cipher_ctx_update_ad
int cipher_ctx_update_ad(cipher_ctx_t *ctx, const uint8_t *src, int src_len)
Updates the given cipher context, providing additional data (AD) for authenticated encryption with ad...
hmac_ctx_final
void hmac_ctx_final(hmac_ctx_t *ctx, uint8_t *dst)
crypto_unload_provider
void crypto_unload_provider(const char *provname, provider_t *provider)
Unloads the given (OpenSSL) provider.
Definition: crypto_openssl.c:177
cipher_kt_mode_aead
bool cipher_kt_mode_aead(const char *ciphername)
Check if the supplied cipher is a supported AEAD mode cipher.
Definition: crypto_openssl.c:816
cipher_ctx_mode_aead
bool cipher_ctx_mode_aead(const cipher_ctx_t *ctx)
Check if the supplied cipher is a supported AEAD mode cipher.
Definition: crypto_openssl.c:939
cipher_name_translation_table_count
const size_t cipher_name_translation_table_count
Definition: crypto_openssl.c:322
buffer
Wrapper structure for dynamically allocated memory.
Definition: buffer.h:60
md_ctx_update
void md_ctx_update(md_ctx_t *ctx, const uint8_t *src, int src_len)
md_ctx_init
void md_ctx_init(md_ctx_t *ctx, const char *mdname)
Initialises the given message digest context.
hmac_ctx_reset
void hmac_ctx_reset(hmac_ctx_t *ctx)
rand_bytes
int rand_bytes(uint8_t *output, int len)
Wrapper for secure random number generator.
Definition: crypto_openssl.c:592
provider_t
void provider_t
Definition: crypto_mbedtls.h:49
hmac_ctx_free
void hmac_ctx_free(hmac_ctx_t *ctx)
cipher_name_pair
Struct used in cipher name translation table.
Definition: crypto_backend.h:57
show_available_engines
void show_available_engines(void)
Definition: crypto_openssl.c:477
cipher_ctx_block_size
int cipher_ctx_block_size(const cipher_ctx_t *ctx)
Returns the block size of the cipher, in bytes.
buffer.h
show_available_digests
void show_available_digests(void)
Definition: crypto_openssl.c:436
cipher_kt_mode_ofb_cfb
bool cipher_kt_mode_ofb_cfb(const char *ciphername)
Check if the supplied cipher is a supported OFB or CFB mode cipher.
Definition: crypto_openssl.c:804
cipher_kt_insecure
bool cipher_kt_insecure(const char *ciphername)
Returns true if we consider this cipher to be insecure.
Definition: crypto_openssl.c:759
gc_arena
Garbage collection arena used to keep track of dynamically allocated memory.
Definition: buffer.h:116
crypto_pem_encode
bool crypto_pem_encode(const char *name, struct buffer *dst, const struct buffer *src, struct gc_arena *gc)
Encode binary data as PEM.
Definition: crypto_openssl.c:502
cipher_ctx_get_tag
int cipher_ctx_get_tag(cipher_ctx_t *ctx, uint8_t *tag, int tag_len)
Gets the computed message authenticated code (MAC) tag for this cipher.
cipher_kt_key_size
int cipher_kt_key_size(const char *ciphername)
Returns the size of keys used by the cipher, in bytes.
Definition: crypto_openssl.c:679
cipher_kt_tag_size
int cipher_kt_tag_size(const char *ciphername)
Returns the MAC tag size of the cipher, in bytes.
Definition: crypto_openssl.c:746
basic.h
md_ctx_free
void md_ctx_free(md_ctx_t *ctx)
crypto_pem_decode
bool crypto_pem_decode(const char *name, struct buffer *dst, const struct buffer *src)
Decode a PEM buffer to binary data.
Definition: crypto_openssl.c:530
md_defined
static bool md_defined(const char *mdname)
Checks if the cipher is defined and is not the null (none) cipher.
Definition: crypto_backend.h:504
crypto_load_provider
provider_t * crypto_load_provider(const char *provider)
Load the given (OpenSSL) providers.
Definition: crypto_openssl.c:160
cipher_kt_mode_cbc
bool cipher_kt_mode_cbc(const char *ciphername)
Check if the supplied cipher is a supported CBC mode cipher.
Definition: crypto_openssl.c:789
cipher_ctx_reset
int cipher_ctx_reset(cipher_ctx_t *ctx, const uint8_t *iv_buf)
Resets the given cipher context, setting the IV to the specified value.
hmac_ctx_new
hmac_ctx_t * hmac_ctx_new(void)
Definition: crypto_openssl.c:1186
MD_SHA1
@ MD_SHA1
Definition: crypto_backend.h:52
translate_cipher_name_from_openvpn
const char * translate_cipher_name_from_openvpn(const char *cipher_name)
Translate an OpenVPN cipher name to a crypto library cipher name.
Definition: crypto.c:1674
hmac_ctx_init
void hmac_ctx_init(hmac_ctx_t *ctx, const uint8_t *key, const char *mdname)
md_valid
bool md_valid(const char *digest)
Return if a message digest parameters is valid given the name of the digest.
Definition: crypto_openssl.c:1038
crypto_init_lib_engine
void crypto_init_lib_engine(const char *engine_name)
Definition: crypto_openssl.c:144
cipher_kt_iv_size
int cipher_kt_iv_size(const char *ciphername)
Returns the size of the IV used by the cipher, in bytes, or 0 if no IV is used.
Definition: crypto_openssl.c:688
cipher_name_pair::lib_name
const char * lib_name
Cipher name used by crypto library.
Definition: crypto_backend.h:59
ssl_tls1_PRF
bool ssl_tls1_PRF(const uint8_t *seed, int seed_len, const uint8_t *secret, int secret_len, uint8_t *output, int output_len)
Calculates the TLS 1.0-1.1 PRF function.
Definition: crypto_openssl.c:1402
crypto_operation_t
mbedtls_operation_t crypto_operation_t
Definition: crypto_mbedtls.h:66
hmac_ctx_size
int hmac_ctx_size(hmac_ctx_t *ctx)