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 
237 const cipher_kt_t *cipher_kt_get(const char *ciphername);
238 
250 const char *cipher_kt_name(const cipher_kt_t *cipher_kt);
251 
260 int cipher_kt_key_size(const cipher_kt_t *cipher_kt);
261 
271 int cipher_kt_iv_size(const cipher_kt_t *cipher_kt);
272 
280 int cipher_kt_block_size(const cipher_kt_t *cipher_kt);
281 
290 int cipher_kt_tag_size(const cipher_kt_t *cipher_kt);
291 
295 bool cipher_kt_insecure(const cipher_kt_t *cipher);
296 
305 int cipher_kt_mode(const cipher_kt_t *cipher_kt);
306 
314 bool cipher_kt_mode_cbc(const cipher_kt_t *cipher);
315 
323 bool cipher_kt_mode_ofb_cfb(const cipher_kt_t *cipher);
324 
332 bool cipher_kt_mode_aead(const cipher_kt_t *cipher);
333 
334 
347 
353 void cipher_ctx_free(cipher_ctx_t *ctx);
354 
365 void cipher_ctx_init(cipher_ctx_t *ctx, const uint8_t *key, int key_len,
366  const cipher_kt_t *kt, int enc);
367 
377 int cipher_ctx_iv_length(const cipher_ctx_t *ctx);
378 
386 int cipher_ctx_get_tag(cipher_ctx_t *ctx, uint8_t *tag, int tag_len);
387 
395 int cipher_ctx_block_size(const cipher_ctx_t *ctx);
396 
405 int cipher_ctx_mode(const cipher_ctx_t *ctx);
406 
416 
426 int cipher_ctx_reset(cipher_ctx_t *ctx, const uint8_t *iv_buf);
427 
438 int cipher_ctx_update_ad(cipher_ctx_t *ctx, const uint8_t *src, int src_len);
439 
457 int cipher_ctx_update(cipher_ctx_t *ctx, uint8_t *dst, int *dst_len,
458  uint8_t *src, int src_len);
459 
470 int cipher_ctx_final(cipher_ctx_t *ctx, uint8_t *dst, int *dst_len);
471 
485 int cipher_ctx_final_check_tag(cipher_ctx_t *ctx, uint8_t *dst, int *dst_len,
486  uint8_t *tag, size_t tag_len);
487 
488 
489 /*
490  *
491  * Generic message digest information functions
492  *
493  */
494 
495 /*
496  * Max size in bytes of any HMAC key that might conceivably be used.
497  *
498  * This value is checked at compile time in crypto.c to make sure
499  * it is always at least EVP_MAX_MD_SIZE. We define our own value
500  * for the same reason as above.
501  */
502 #define MAX_HMAC_KEY_LENGTH 64
503 
515 const md_kt_t *md_kt_get(const char *digest);
516 
525 const char *md_kt_name(const md_kt_t *kt);
526 
534 unsigned char md_kt_size(const md_kt_t *kt);
535 
536 
537 /*
538  *
539  * Generic message digest functions
540  *
541  */
542 
543 /*
544  * Calculates the message digest for the given buffer.
545  *
546  * @param kt Static message digest parameters
547  * @param src Buffer to digest. May not be NULL.
548  * @param src_len The length of the incoming buffer.
549  * @param dst Buffer to write the message digest to. May not be NULL.
550  *
551  * @return \c 1 on success, \c 0 on failure
552  */
553 int md_full(const md_kt_t *kt, const uint8_t *src, int src_len, uint8_t *dst);
554 
555 /*
556  * Allocate a new message digest context
557  *
558  * @return a new zeroed MD context
559  */
560 md_ctx_t *md_ctx_new(void);
561 
562 /*
563  * Free an existing, non-null message digest context
564  *
565  * @param ctx Message digest context
566  */
567 void md_ctx_free(md_ctx_t *ctx);
568 
569 /*
570  * Initialises the given message digest context.
571  *
572  * @param ctx Message digest context
573  * @param kt Static message digest parameters
574  */
575 void md_ctx_init(md_ctx_t *ctx, const md_kt_t *kt);
576 
577 /*
578  * Free the given message digest context.
579  *
580  * @param ctx Message digest context
581  */
582 void md_ctx_cleanup(md_ctx_t *ctx);
583 
584 /*
585  * Returns the size of the message digest output by the given context
586  *
587  * @param ctx Message digest context.
588  *
589  * @return Size of the message digest, or \0 if ctx is NULL.
590  */
591 int md_ctx_size(const md_ctx_t *ctx);
592 
593 /*
594  * Process the given data for use in the message digest.
595  *
596  * @param ctx Message digest context. May not be NULL.
597  * @param src Buffer to digest. May not be NULL.
598  * @param src_len The length of the incoming buffer.
599  */
600 void md_ctx_update(md_ctx_t *ctx, const uint8_t *src, int src_len);
601 
602 /*
603  * Output the message digest to the given buffer.
604  *
605  * @param ctx Message digest context. May not be NULL.
606  * @param dst Buffer to write the message digest to. May not be NULL.
607  */
608 void md_ctx_final(md_ctx_t *ctx, uint8_t *dst);
609 
610 
611 /*
612  *
613  * Generic HMAC functions
614  *
615  */
616 
617 /*
618  * Create a new HMAC context
619  *
620  * @return A new HMAC context
621  */
622 hmac_ctx_t *hmac_ctx_new(void);
623 
624 /*
625  * Free an existing HMAC context
626  *
627  * @param ctx HMAC context to free
628  */
629 void hmac_ctx_free(hmac_ctx_t *ctx);
630 
631 /*
632  * Initialises the given HMAC context, using the given digest
633  * and key.
634  *
635  * @param ctx HMAC context to initialise
636  * @param key The key to use for the HMAC
637  * @param key_len The key length to use
638  * @param kt Static message digest parameters
639  *
640  */
641 void hmac_ctx_init(hmac_ctx_t *ctx, const uint8_t *key, int key_length,
642  const md_kt_t *kt);
643 
644 /*
645  * Free the given HMAC context.
646  *
647  * @param ctx HMAC context
648  */
649 void hmac_ctx_cleanup(hmac_ctx_t *ctx);
650 
651 /*
652  * Returns the size of the HMAC output by the given HMAC Context
653  *
654  * @param ctx HMAC context.
655  *
656  * @return Size of the HMAC, or \0 if ctx is NULL.
657  */
658 int hmac_ctx_size(const hmac_ctx_t *ctx);
659 
660 /*
661  * Resets the given HMAC context, preserving the associated key information
662  *
663  * @param ctx HMAC context. May not be NULL.
664  */
665 void hmac_ctx_reset(hmac_ctx_t *ctx);
666 
667 /*
668  * Process the given data for use in the HMAC.
669  *
670  * @param ctx HMAC context. May not be NULL.
671  * @param src The buffer to HMAC. May not be NULL.
672  * @param src_len The length of the incoming buffer.
673  */
674 void hmac_ctx_update(hmac_ctx_t *ctx, const uint8_t *src, int src_len);
675 
676 /*
677  * Output the HMAC to the given buffer.
678  *
679  * @param ctx HMAC context. May not be NULL.
680  * @param dst buffer to write the HMAC to. May not be NULL.
681  */
682 void hmac_ctx_final(hmac_ctx_t *ctx, uint8_t *dst);
683 
692 const char *translate_cipher_name_from_openvpn(const char *cipher_name);
693 
702 const char *translate_cipher_name_to_openvpn(const char *cipher_name);
703 
704 
718 bool ssl_tls1_PRF(const uint8_t *seed, int seed_len, const uint8_t *secret,
719  int secret_len, uint8_t *output, int output_len);
720 
721 #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:1848
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.
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:1835
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.