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-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 
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 
95 const char *translate_cipher_name_from_openvpn(const char *cipher_name);
96 
101 const char *translate_cipher_name_from_openvpn(const char *cipher_name);
102 
103 void show_available_ciphers(void);
104 
105 void show_available_digests(void);
106 
107 void show_available_engines(void);
108 
122 bool crypto_pem_encode(const char *name, struct buffer *dst,
123  const struct buffer *src, struct gc_arena *gc);
124 
134 bool crypto_pem_decode(const char *name, struct buffer *dst,
135  const struct buffer *src);
136 
137 /*
138  *
139  * Random number functions, used in cases where we want
140  * reasonably strong cryptographic random number generation
141  * without depleting our entropy pool. Used for random
142  * IV values and a number of other miscellaneous tasks.
143  *
144  */
145 
155 int rand_bytes(uint8_t *output, int len);
156 
157 /*
158  *
159  * Key functions, allow manipulation of keys.
160  *
161  */
162 
163 
172 int key_des_num_cblocks(const cipher_kt_t *kt);
173 
174 /*
175  * Check the given DES key. Checks the given key's length, weakness and parity.
176  *
177  * @param key Key to check
178  * @param key_len Length of the key, in bytes
179  * @param ndc Number of DES cblocks that the key is made up of.
180  *
181  * @return \c true if the key is valid, \c false otherwise.
182  */
183 bool key_des_check(uint8_t *key, int key_len, int ndc);
184 
185 /*
186  * Fix the given DES key, setting its parity to odd.
187  *
188  * @param key Key to check
189  * @param key_len Length of the key, in bytes
190  * @param ndc Number of DES cblocks that the key is made up of.
191  */
192 void key_des_fixup(uint8_t *key, int key_len, int ndc);
193 
201 void cipher_des_encrypt_ecb(const unsigned char key[DES_KEY_LENGTH],
202  unsigned char src[DES_KEY_LENGTH],
203  unsigned char dst[DES_KEY_LENGTH]);
204 
205 /*
206  *
207  * Generic cipher key type functions
208  *
209  */
210 /*
211  * Max size in bytes of any cipher key that might conceivably be used.
212  *
213  * This value is checked at compile time in crypto.c to make sure
214  * it is always at least EVP_MAX_KEY_LENGTH.
215  *
216  * We define our own value, since this parameter
217  * is used to control the size of static key files.
218  * If the OpenSSL library increases EVP_MAX_KEY_LENGTH,
219  * we don't want our key files to be suddenly rendered
220  * unusable.
221  */
222 #define MAX_CIPHER_KEY_LENGTH 64
223 
236 const cipher_kt_t *cipher_kt_get(const char *ciphername);
237 
245 const char *cipher_kt_name(const cipher_kt_t *cipher_kt);
246 
255 int cipher_kt_key_size(const cipher_kt_t *cipher_kt);
256 
266 int cipher_kt_iv_size(const cipher_kt_t *cipher_kt);
267 
275 int cipher_kt_block_size(const cipher_kt_t *cipher_kt);
276 
285 int cipher_kt_tag_size(const cipher_kt_t *cipher_kt);
286 
290 bool cipher_kt_insecure(const cipher_kt_t *cipher);
291 
300 int cipher_kt_mode(const cipher_kt_t *cipher_kt);
301 
309 bool cipher_kt_mode_cbc(const cipher_kt_t *cipher);
310 
318 bool cipher_kt_mode_ofb_cfb(const cipher_kt_t *cipher);
319 
327 bool cipher_kt_mode_aead(const cipher_kt_t *cipher);
328 
329 
342 
348 void cipher_ctx_free(cipher_ctx_t *ctx);
349 
360 void cipher_ctx_init(cipher_ctx_t *ctx, const uint8_t *key, int key_len,
361  const cipher_kt_t *kt, int enc);
362 
369 
379 int cipher_ctx_iv_length(const cipher_ctx_t *ctx);
380 
388 int cipher_ctx_get_tag(cipher_ctx_t *ctx, uint8_t *tag, int tag_len);
389 
397 int cipher_ctx_block_size(const cipher_ctx_t *ctx);
398 
407 int cipher_ctx_mode(const cipher_ctx_t *ctx);
408 
418 
428 int cipher_ctx_reset(cipher_ctx_t *ctx, const uint8_t *iv_buf);
429 
440 int cipher_ctx_update_ad(cipher_ctx_t *ctx, const uint8_t *src, int src_len);
441 
459 int cipher_ctx_update(cipher_ctx_t *ctx, uint8_t *dst, int *dst_len,
460  uint8_t *src, int src_len);
461 
472 int cipher_ctx_final(cipher_ctx_t *ctx, uint8_t *dst, int *dst_len);
473 
487 int cipher_ctx_final_check_tag(cipher_ctx_t *ctx, uint8_t *dst, int *dst_len,
488  uint8_t *tag, size_t tag_len);
489 
490 
491 /*
492  *
493  * Generic message digest information functions
494  *
495  */
496 
497 /*
498  * Max size in bytes of any HMAC key that might conceivably be used.
499  *
500  * This value is checked at compile time in crypto.c to make sure
501  * it is always at least EVP_MAX_MD_SIZE. We define our own value
502  * for the same reason as above.
503  */
504 #define MAX_HMAC_KEY_LENGTH 64
505 
517 const md_kt_t *md_kt_get(const char *digest);
518 
527 const char *md_kt_name(const md_kt_t *kt);
528 
536 int md_kt_size(const md_kt_t *kt);
537 
538 
539 /*
540  *
541  * Generic message digest functions
542  *
543  */
544 
545 /*
546  * Calculates the message digest for the given buffer.
547  *
548  * @param kt Static message digest parameters
549  * @param src Buffer to digest. May not be NULL.
550  * @param src_len The length of the incoming buffer.
551  * @param dst Buffer to write the message digest to. May not be NULL.
552  *
553  * @return \c 1 on success, \c 0 on failure
554  */
555 int md_full(const md_kt_t *kt, 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 
571 /*
572  * Initialises the given message digest context.
573  *
574  * @param ctx Message digest context
575  * @param kt Static message digest parameters
576  */
577 void md_ctx_init(md_ctx_t *ctx, const md_kt_t *kt);
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 key_len The key length to use
640  * @param kt Static message digest parameters
641  *
642  */
643 void hmac_ctx_init(hmac_ctx_t *ctx, const uint8_t *key, int key_length,
644  const md_kt_t *kt);
645 
646 /*
647  * Free the given HMAC context.
648  *
649  * @param ctx HMAC context
650  */
651 void hmac_ctx_cleanup(hmac_ctx_t *ctx);
652 
653 /*
654  * Returns the size of the HMAC output by the given HMAC Context
655  *
656  * @param ctx HMAC context.
657  *
658  * @return Size of the HMAC, or \0 if ctx is NULL.
659  */
660 int hmac_ctx_size(const hmac_ctx_t *ctx);
661 
662 /*
663  * Resets the given HMAC context, preserving the associated key information
664  *
665  * @param ctx HMAC context. May not be NULL.
666  */
667 void hmac_ctx_reset(hmac_ctx_t *ctx);
668 
669 /*
670  * Process the given data for use in the HMAC.
671  *
672  * @param ctx HMAC context. May not be NULL.
673  * @param src The buffer to HMAC. May not be NULL.
674  * @param src_len The length of the incoming buffer.
675  */
676 void hmac_ctx_update(hmac_ctx_t *ctx, const uint8_t *src, int src_len);
677 
678 /*
679  * Output the HMAC to the given buffer.
680  *
681  * @param ctx HMAC context. May not be NULL.
682  * @param dst buffer to write the HMAC to. May not be NULL.
683  */
684 void hmac_ctx_final(hmac_ctx_t *ctx, uint8_t *dst);
685 
694 const char *translate_cipher_name_from_openvpn(const char *cipher_name);
695 
704 const char *translate_cipher_name_to_openvpn(const char *cipher_name);
705 
706 #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 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:1840
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.
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)
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.
int md_kt_size(const md_kt_t *kt)
Returns the size of the message digest, in bytes.
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.
int cipher_ctx_block_size(const cipher_ctx_t *ctx)
Returns the block size of the cipher, in bytes.
unsigned __int8 uint8_t
Definition: config-msvc.h:123
const size_t cipher_name_translation_table_count
void show_available_digests(void)
Struct used in cipher name translation table.
Wrapper structure for dynamically allocated memory.
Definition: buffer.h:60
const char * translate_cipher_name_from_openvpn(const char *cipher_name)
Translate a data channel cipher name from the OpenVPN config file &#39;language&#39; to the crypto library sp...
Definition: crypto.c:1827
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)
char * dst
Definition: compat-lz4.h:455
hmac_ctx_t * hmac_ctx_new(void)
void crypto_init_lib_engine(const char *engine_name)
void cipher_ctx_cleanup(cipher_ctx_t *ctx)
Cleanup the specified context.
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.