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-2021 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 #ifdef DMALLOC
82 /*
83  * OpenSSL memory debugging. If dmalloc debugging is enabled, tell
84  * OpenSSL to use our private malloc/realloc/free functions so that
85  * we can dispatch them to dmalloc.
86  */
87 void crypto_init_dmalloc(void);
88 
89 #endif /* DMALLOC */
90 
91 void show_available_ciphers(void);
92 
93 void show_available_digests(void);
94 
95 void show_available_engines(void);
96 
110 bool crypto_pem_encode(const char *name, struct buffer *dst,
111  const struct buffer *src, struct gc_arena *gc);
112 
122 bool crypto_pem_decode(const char *name, struct buffer *dst,
123  const struct buffer *src);
124 
125 /*
126  *
127  * Random number functions, used in cases where we want
128  * reasonably strong cryptographic random number generation
129  * without depleting our entropy pool. Used for random
130  * IV values and a number of other miscellaneous tasks.
131  *
132  */
133 
143 int rand_bytes(uint8_t *output, int len);
144 
145 /*
146  *
147  * Key functions, allow manipulation of keys.
148  *
149  */
150 
151 
160 int key_des_num_cblocks(const cipher_kt_t *kt);
161 
162 /*
163  * Check the given DES key. Checks the given key's length, weakness and parity.
164  *
165  * @param key Key to check
166  * @param key_len Length of the key, in bytes
167  * @param ndc Number of DES cblocks that the key is made up of.
168  *
169  * @return \c true if the key is valid, \c false otherwise.
170  */
171 bool key_des_check(uint8_t *key, int key_len, int ndc);
172 
173 /*
174  * Fix the given DES key, setting its parity to odd.
175  *
176  * @param key Key to check
177  * @param key_len Length of the key, in bytes
178  * @param ndc Number of DES cblocks that the key is made up of.
179  */
180 void key_des_fixup(uint8_t *key, int key_len, int ndc);
181 
189 void cipher_des_encrypt_ecb(const unsigned char key[DES_KEY_LENGTH],
190  unsigned char src[DES_KEY_LENGTH],
191  unsigned char dst[DES_KEY_LENGTH]);
192 
193 /*
194  *
195  * Generic cipher key type functions
196  *
197  */
198 /*
199  * Max size in bytes of any cipher key that might conceivably be used.
200  *
201  * This value is checked at compile time in crypto.c to make sure
202  * it is always at least EVP_MAX_KEY_LENGTH.
203  *
204  * We define our own value, since this parameter
205  * is used to control the size of static key files.
206  * If the OpenSSL library increases EVP_MAX_KEY_LENGTH,
207  * we don't want our key files to be suddenly rendered
208  * unusable.
209  */
210 #define MAX_CIPHER_KEY_LENGTH 64
211 
225 const cipher_kt_t *cipher_kt_get(const char *ciphername);
226 
238 const char *cipher_kt_name(const cipher_kt_t *cipher_kt);
239 
248 int cipher_kt_key_size(const cipher_kt_t *cipher_kt);
249 
259 int cipher_kt_iv_size(const cipher_kt_t *cipher_kt);
260 
268 int cipher_kt_block_size(const cipher_kt_t *cipher_kt);
269 
278 int cipher_kt_tag_size(const cipher_kt_t *cipher_kt);
279 
283 bool cipher_kt_insecure(const cipher_kt_t *cipher);
284 
293 int cipher_kt_mode(const cipher_kt_t *cipher_kt);
294 
302 bool cipher_kt_mode_cbc(const cipher_kt_t *cipher);
303 
311 bool cipher_kt_mode_ofb_cfb(const cipher_kt_t *cipher);
312 
320 bool cipher_kt_mode_aead(const cipher_kt_t *cipher);
321 
322 
335 
341 void cipher_ctx_free(cipher_ctx_t *ctx);
342 
353 void cipher_ctx_init(cipher_ctx_t *ctx, const uint8_t *key, int key_len,
354  const cipher_kt_t *kt, int enc);
355 
365 int cipher_ctx_iv_length(const cipher_ctx_t *ctx);
366 
374 int cipher_ctx_get_tag(cipher_ctx_t *ctx, uint8_t *tag, int tag_len);
375 
383 int cipher_ctx_block_size(const cipher_ctx_t *ctx);
384 
393 int cipher_ctx_mode(const cipher_ctx_t *ctx);
394 
404 
414 int cipher_ctx_reset(cipher_ctx_t *ctx, const uint8_t *iv_buf);
415 
426 int cipher_ctx_update_ad(cipher_ctx_t *ctx, const uint8_t *src, int src_len);
427 
445 int cipher_ctx_update(cipher_ctx_t *ctx, uint8_t *dst, int *dst_len,
446  uint8_t *src, int src_len);
447 
458 int cipher_ctx_final(cipher_ctx_t *ctx, uint8_t *dst, int *dst_len);
459 
473 int cipher_ctx_final_check_tag(cipher_ctx_t *ctx, uint8_t *dst, int *dst_len,
474  uint8_t *tag, size_t tag_len);
475 
476 
477 /*
478  *
479  * Generic message digest information functions
480  *
481  */
482 
483 /*
484  * Max size in bytes of any HMAC key that might conceivably be used.
485  *
486  * This value is checked at compile time in crypto.c to make sure
487  * it is always at least EVP_MAX_MD_SIZE. We define our own value
488  * for the same reason as above.
489  */
490 #define MAX_HMAC_KEY_LENGTH 64
491 
503 const md_kt_t *md_kt_get(const char *digest);
504 
513 const char *md_kt_name(const md_kt_t *kt);
514 
522 unsigned char md_kt_size(const md_kt_t *kt);
523 
524 
525 /*
526  *
527  * Generic message digest functions
528  *
529  */
530 
531 /*
532  * Calculates the message digest for the given buffer.
533  *
534  * @param kt Static message digest parameters
535  * @param src Buffer to digest. May not be NULL.
536  * @param src_len The length of the incoming buffer.
537  * @param dst Buffer to write the message digest to. May not be NULL.
538  *
539  * @return \c 1 on success, \c 0 on failure
540  */
541 int md_full(const md_kt_t *kt, const uint8_t *src, int src_len, uint8_t *dst);
542 
543 /*
544  * Allocate a new message digest context
545  *
546  * @return a new zeroed MD context
547  */
548 md_ctx_t *md_ctx_new(void);
549 
550 /*
551  * Free an existing, non-null message digest context
552  *
553  * @param ctx Message digest context
554  */
555 void md_ctx_free(md_ctx_t *ctx);
556 
557 /*
558  * Initialises the given message digest context.
559  *
560  * @param ctx Message digest context
561  * @param kt Static message digest parameters
562  */
563 void md_ctx_init(md_ctx_t *ctx, const md_kt_t *kt);
564 
565 /*
566  * Free the given message digest context.
567  *
568  * @param ctx Message digest context
569  */
570 void md_ctx_cleanup(md_ctx_t *ctx);
571 
572 /*
573  * Returns the size of the message digest output by the given context
574  *
575  * @param ctx Message digest context.
576  *
577  * @return Size of the message digest, or \0 if ctx is NULL.
578  */
579 int md_ctx_size(const md_ctx_t *ctx);
580 
581 /*
582  * Process the given data for use in the message digest.
583  *
584  * @param ctx Message digest context. May not be NULL.
585  * @param src Buffer to digest. May not be NULL.
586  * @param src_len The length of the incoming buffer.
587  */
588 void md_ctx_update(md_ctx_t *ctx, const uint8_t *src, int src_len);
589 
590 /*
591  * Output the message digest to the given buffer.
592  *
593  * @param ctx Message digest context. May not be NULL.
594  * @param dst Buffer to write the message digest to. May not be NULL.
595  */
596 void md_ctx_final(md_ctx_t *ctx, uint8_t *dst);
597 
598 
599 /*
600  *
601  * Generic HMAC functions
602  *
603  */
604 
605 /*
606  * Create a new HMAC context
607  *
608  * @return A new HMAC context
609  */
610 hmac_ctx_t *hmac_ctx_new(void);
611 
612 /*
613  * Free an existing HMAC context
614  *
615  * @param ctx HMAC context to free
616  */
617 void hmac_ctx_free(hmac_ctx_t *ctx);
618 
619 /*
620  * Initialises the given HMAC context, using the given digest
621  * and key.
622  *
623  * @param ctx HMAC context to initialise
624  * @param key The key to use for the HMAC
625  * @param key_len The key length to use
626  * @param kt Static message digest parameters
627  *
628  */
629 void hmac_ctx_init(hmac_ctx_t *ctx, const uint8_t *key, int key_length,
630  const md_kt_t *kt);
631 
632 /*
633  * Free the given HMAC context.
634  *
635  * @param ctx HMAC context
636  */
637 void hmac_ctx_cleanup(hmac_ctx_t *ctx);
638 
639 /*
640  * Returns the size of the HMAC output by the given HMAC Context
641  *
642  * @param ctx HMAC context.
643  *
644  * @return Size of the HMAC, or \0 if ctx is NULL.
645  */
646 int hmac_ctx_size(const hmac_ctx_t *ctx);
647 
648 /*
649  * Resets the given HMAC context, preserving the associated key information
650  *
651  * @param ctx HMAC context. May not be NULL.
652  */
653 void hmac_ctx_reset(hmac_ctx_t *ctx);
654 
655 /*
656  * Process the given data for use in the HMAC.
657  *
658  * @param ctx HMAC context. May not be NULL.
659  * @param src The buffer to HMAC. May not be NULL.
660  * @param src_len The length of the incoming buffer.
661  */
662 void hmac_ctx_update(hmac_ctx_t *ctx, const uint8_t *src, int src_len);
663 
664 /*
665  * Output the HMAC to the given buffer.
666  *
667  * @param ctx HMAC context. May not be NULL.
668  * @param dst buffer to write the HMAC to. May not be NULL.
669  */
670 void hmac_ctx_final(hmac_ctx_t *ctx, uint8_t *dst);
671 
680 const char *translate_cipher_name_from_openvpn(const char *cipher_name);
681 
690 const char *translate_cipher_name_to_openvpn(const char *cipher_name);
691 
692 
706 bool ssl_tls1_PRF(const uint8_t *seed, int seed_len, const uint8_t *secret,
707  int secret_len, uint8_t *output, int output_len);
708 
709 #endif /* CRYPTO_BACKEND_H_ */
int md_full(const md_kt_t *kt, const uint8_t *src, int src_len, uint8_t *dst)
bool cipher_kt_mode_aead(const cipher_kt_t *cipher)
Check if the supplied cipher is a supported AEAD mode cipher.
bool crypto_pem_decode(const char *name, struct buffer *dst, const struct buffer *src)
Decode a PEM buffer to binary data.
const cipher_kt_t * cipher_ctx_get_cipher_kt(const cipher_ctx_t *ctx)
Returns the static cipher parameters for this context.
mbedtls_cipher_context_t cipher_ctx_t
Generic cipher context.
md_ctx_t * md_ctx_new(void)
int key_des_num_cblocks(const cipher_kt_t *kt)
Return number of DES cblocks (1 cblock = length of a single-DES key) for the current key type or 0 if...
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.
bool cipher_kt_mode_ofb_cfb(const cipher_kt_t *cipher)
Check if the supplied cipher is a supported OFB or CFB mode cipher.
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.
const char * openvpn_name
Cipher name used by OpenVPN.
void md_ctx_free(md_ctx_t *ctx)
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:1854
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.
hash_algo_type
Types referencing specific message digest hashing algorithms.
int cipher_kt_iv_size(const cipher_kt_t *cipher_kt)
Returns the size of the IV used by the cipher, in bytes, or 0 if no IV is used.
bool cipher_kt_insecure(const cipher_kt_t *cipher)
Returns true if we consider this cipher to be insecure.
int cipher_kt_tag_size(const cipher_kt_t *cipher_kt)
Returns the MAC tag size of the cipher, in bytes.
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.
bool key_des_check(uint8_t *key, int key_len, int ndc)
void hmac_ctx_cleanup(hmac_ctx_t *ctx)
mbedtls_md_context_t hmac_ctx_t
Generic HMAC context.
void cipher_des_encrypt_ecb(const unsigned char key[DES_KEY_LENGTH], unsigned char src[DES_KEY_LENGTH], unsigned char dst[DES_KEY_LENGTH])
Encrypt the given block, using DES ECB mode.
static char * engine_name
Definition: libtestengine.c:7
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.
void cipher_ctx_free(cipher_ctx_t *ctx)
Cleanup and free a cipher context.
const cipher_name_pair cipher_name_translation_table[]
Cipher name translation table.
void md_ctx_final(md_ctx_t *ctx, uint8_t *dst)
void crypto_clear_error(void)
int cipher_ctx_mode(const cipher_ctx_t *ctx)
Returns the mode that the cipher runs in.
bool crypto_pem_encode(const char *name, struct buffer *dst, const struct buffer *src, struct gc_arena *gc)
Encode binary data as PEM.
void show_available_engines(void)
void md_ctx_update(md_ctx_t *ctx, const uint8_t *src, int src_len)
int rand_bytes(uint8_t *output, int len)
Wrapper for secure random number generator.
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...
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...
void hmac_ctx_update(hmac_ctx_t *ctx, const uint8_t *src, int src_len)
mbedtls_md_info_t md_kt_t
Generic message digest key type context.
int md_ctx_size(const md_ctx_t *ctx)
mbedtls_cipher_info_t cipher_kt_t
Generic cipher key type context.
const char * md_kt_name(const md_kt_t *kt)
Retrieve a string describing the digest digest (e.g.
int hmac_ctx_size(const hmac_ctx_t *ctx)
void key_des_fixup(uint8_t *key, int key_len, int ndc)
const md_kt_t * md_kt_get(const char *digest)
Return message digest parameters, based on the given digest name.
void show_available_ciphers(void)
const char * lib_name
Cipher name used by crypto library.
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...
int cipher_kt_key_size(const cipher_kt_t *cipher_kt)
Returns the size of keys used by the cipher, in bytes.
void md_ctx_cleanup(md_ctx_t *ctx)
cipher_ctx_t * cipher_ctx_new(void)
Generic cipher functions.
unsigned char md_kt_size(const md_kt_t *kt)
Returns the size of the message digest, in bytes.
int cipher_ctx_block_size(const cipher_ctx_t *ctx)
Returns the block size of the cipher, in bytes.
const size_t cipher_name_translation_table_count
void show_available_digests(void)
Struct used in cipher name translation table.
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:1841
Wrapper structure for dynamically allocated memory.
Definition: buffer.h:60
int cipher_kt_mode(const cipher_kt_t *cipher_kt)
Returns the mode that the cipher runs in.
int cipher_kt_block_size(const cipher_kt_t *cipher_kt)
Returns the block size of the cipher, in bytes.
void cipher_ctx_init(cipher_ctx_t *ctx, const uint8_t *key, int key_len, const cipher_kt_t *kt, int enc)
Initialise a cipher context, based on the given key and key type.
void crypto_uninit_lib(void)
Garbage collection arena used to keep track of dynamically allocated memory.
Definition: buffer.h:116
void md_ctx_init(md_ctx_t *ctx, const md_kt_t *kt)
void hmac_ctx_init(hmac_ctx_t *ctx, const uint8_t *key, int key_length, const md_kt_t *kt)
hmac_ctx_t * hmac_ctx_new(void)
void crypto_init_lib_engine(const char *engine_name)
void hmac_ctx_final(hmac_ctx_t *ctx, uint8_t *dst)
#define DES_KEY_LENGTH
void hmac_ctx_free(hmac_ctx_t *ctx)
const cipher_kt_t * cipher_kt_get(const char *ciphername)
Return cipher parameters, based on the given cipher name.
mbedtls_md_context_t md_ctx_t
Generic message digest context.
void crypto_init_lib(void)
void hmac_ctx_reset(hmac_ctx_t *ctx)
const char * cipher_kt_name(const cipher_kt_t *cipher_kt)
Retrieve a string describing the cipher (e.g.
Container for unidirectional cipher and HMAC key material.
Definition: crypto.h:151
bool cipher_kt_mode_cbc(const cipher_kt_t *cipher)
Check if the supplied cipher is a supported CBC mode cipher.