OpenVPN
crypto.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 
122 #ifndef CRYPTO_H
123 #define CRYPTO_H
124 
125 #include "crypto_backend.h"
126 #include "basic.h"
127 #include "buffer.h"
128 #include "packet_id.h"
129 #include "mtu.h"
130 
134 };
135 
136 /*
137  * Defines a key type and key length for both cipher and HMAC.
138  */
139 struct key_type
140 {
144  const md_kt_t *digest;
145 };
146 
151 struct key
152 {
157 };
158 
159 
164 struct key_ctx
165 {
171 };
172 
173 #define KEY_DIRECTION_BIDIRECTIONAL 0 /* same keys for both directions */
174 #define KEY_DIRECTION_NORMAL 1 /* encrypt with keys[0], decrypt with keys[1] */
175 #define KEY_DIRECTION_INVERSE 2 /* encrypt with keys[1], decrypt with keys[0] */
176 
181 struct key2
182 {
183  int n;
185  struct key keys[2];
187 };
188 
199 {
200  int out_key;
202  int in_key;
204  int need_keys;
212 };
213 
220 {
221  struct key_ctx encrypt;
223  struct key_ctx decrypt;
226 };
227 
233 {
245 #define CO_PACKET_ID_LONG_FORM (1<<0)
246 
248 #define CO_IGNORE_PACKET_ID (1<<1)
249 
254 #define CO_MUTE_REPLAY_WARNINGS (1<<2)
255 
257  unsigned int flags;
259 };
260 
261 #define CRYPT_ERROR(format) \
262  do { msg(D_CRYPT_ERRORS, "%s: " format, error_prefix); goto error_exit; } while (false)
263 
268 #define OPENVPN_AEAD_MIN_IV_LEN (sizeof(packet_id_type) + 8)
269 
270 #define RKF_MUST_SUCCEED (1<<0)
271 #define RKF_INLINE (1<<1)
272 void read_key_file(struct key2 *key2, const char *file, const unsigned int flags);
273 
279 int write_key_file(const int nkeys, const char *filename);
280 
281 void generate_key_random(struct key *key, const struct key_type *kt);
282 
283 void check_replay_consistency(const struct key_type *kt, bool packet_id);
284 
285 bool check_key(struct key *key, const struct key_type *kt);
286 
287 void fixup_key(struct key *key, const struct key_type *kt);
288 
289 bool write_key(const struct key *key, const struct key_type *kt,
290  struct buffer *buf);
291 
292 int read_key(struct key *key, const struct key_type *kt, struct buffer *buf);
293 
306 void init_key_type(struct key_type *kt, const char *ciphername,
307  const char *authname, int keysize, bool tls_mode, bool warn);
308 
309 /*
310  * Key context functions
311  */
312 
313 void init_key_ctx(struct key_ctx *ctx, const struct key *key,
314  const struct key_type *kt, int enc,
315  const char *prefix);
316 
317 void free_key_ctx(struct key_ctx *ctx);
318 
319 void init_key_ctx_bi(struct key_ctx_bi *ctx, const struct key2 *key2,
320  int key_direction, const struct key_type *kt,
321  const char *name);
322 
323 void free_key_ctx_bi(struct key_ctx_bi *ctx);
324 
325 
326 /**************************************************************************/
356 void openvpn_encrypt(struct buffer *buf, struct buffer work,
357  struct crypto_options *opt);
358 
359 
393 bool openvpn_decrypt(struct buffer *buf, struct buffer work,
394  struct crypto_options *opt, const struct frame *frame,
395  const uint8_t *ad_start);
396 
409 bool crypto_check_replay(struct crypto_options *opt,
410  const struct packet_id_net *pin, const char *error_prefix,
411  struct gc_arena *gc);
412 
413 
416  const struct key_type *kt,
417  bool packet_id,
418  bool packet_id_long_form);
419 
421 unsigned int crypto_max_overhead(void);
422 
423 /* Minimum length of the nonce used by the PRNG */
424 #define NONCE_SECRET_LEN_MIN 16
425 
426 /* Maximum length of the nonce used by the PRNG */
427 #define NONCE_SECRET_LEN_MAX 64
428 
430 #define PRNG_NONCE_RESET_BYTES 1024
431 
439 void prng_init(const char *md_name, const int nonce_secret_len_parm);
440 
441 /*
442  * Message digest-based pseudo random number generator.
443  *
444  * If the PRNG was initialised with a certain message digest, uses the digest
445  * to calculate the next random number, and prevent depletion of the entropy
446  * pool.
447  *
448  * This PRNG is aimed at IV generation and similar miscellaneous tasks. Use
449  * \c rand_bytes() for higher-assurance functionality.
450  *
451  * Retrieves len bytes of pseudo random data, and places it in output.
452  *
453  * @param output Output buffer
454  * @param len Length of the output buffer
455  */
456 void prng_bytes(uint8_t *output, int len);
457 
458 void prng_uninit(void);
459 
460 /* an analogue to the random() function, but use prng_bytes */
461 long int get_random(void);
462 
464 void print_cipher(const cipher_kt_t *cipher);
465 
466 void test_crypto(struct crypto_options *co, struct frame *f);
467 
468 
469 /* key direction functions */
470 
471 void key_direction_state_init(struct key_direction_state *kds, int key_direction);
472 
473 void verify_fix_key2(struct key2 *key2, const struct key_type *kt, const char *shared_secret_file);
474 
475 void must_have_n_keys(const char *filename, const char *option, const struct key2 *key2, int n);
476 
477 int ascii2keydirection(int msglevel, const char *str);
478 
479 const char *keydirection2ascii(int kd, bool remote, bool humanreadable);
480 
481 /* print keys */
482 void key2_print(const struct key2 *k,
483  const struct key_type *kt,
484  const char *prefix0,
485  const char *prefix1);
486 
487 void crypto_read_openvpn_key(const struct key_type *key_type,
488  struct key_ctx_bi *ctx, const char *key_file, const char *key_inline,
489  const int key_direction, const char *key_name, const char *opt_name);
490 
491 /*
492  * Inline functions
493  */
494 
499 static inline int
500 memcmp_constant_time(const void *a, const void *b, size_t size)
501 {
502  const uint8_t *a1 = a;
503  const uint8_t *b1 = b;
504  int ret = 0;
505  size_t i;
506 
507  for (i = 0; i < size; i++)
508  {
509  ret |= *a1++ ^ *b1++;
510  }
511 
512  return ret;
513 }
514 
515 static inline bool
517 {
518  return key->encrypt.cipher || key->encrypt.hmac || key->decrypt.cipher || key->decrypt.hmac;
519 }
520 
521 #endif /* CRYPTO_H */
void free_key_ctx_bi(struct key_ctx_bi *ctx)
Definition: crypto.c:912
void key_direction_state_init(struct key_direction_state *kds, int key_direction)
Definition: crypto.c:1549
long int get_random(void)
Definition: crypto.c:1767
bool crypto_check_replay(struct crypto_options *opt, const struct packet_id_net *pin, const char *error_prefix, struct gc_arena *gc)
Check packet ID for replay, and perform replay administration.
Definition: crypto.c:323
size_t implicit_iv_len
The length of implicit_iv.
Definition: crypto.h:170
Security parameter state for processing data channel packets.
Definition: crypto.h:232
mbedtls_cipher_context_t cipher_ctx_t
Generic cipher context.
void init_key_ctx(struct key_ctx *ctx, const struct key *key, const struct key_type *kt, int enc, const char *prefix)
Definition: crypto.c:821
uint8_t hmac_length
HMAC length, in bytes.
Definition: crypto.h:142
void verify_fix_key2(struct key2 *key2, const struct key_type *kt, const char *shared_secret_file)
Definition: crypto.c:1578
unsigned int flags
Bit-flags determining behavior of security operation functions.
Definition: crypto.h:257
Key ordering of the key2.keys array.
Definition: crypto.h:198
struct packet_id_persist * pid_persist
Persistent packet ID state for keeping state between successive OpenVPN process startups.
Definition: crypto.h:240
Packet geometry parameters.
Definition: mtu.h:93
#define OPENVPN_MAX_IV_LENGTH
Maximum length of an IV.
int n
The number of key objects stored in the key2.keys array.
Definition: crypto.h:183
bool write_key(const struct key *key, const struct key_type *kt, struct buffer *buf)
Definition: crypto.c:1598
int out_key
Index into the key2.keys array for the sending direction.
Definition: crypto.h:200
void prng_uninit(void)
Definition: crypto.c:1726
#define MAX_CIPHER_KEY_LENGTH
void generate_key_random(struct key *key, const struct key_type *kt)
Definition: crypto.c:1023
mbedtls_md_context_t hmac_ctx_t
Generic HMAC context.
bool initialized
Definition: crypto.h:225
list flags
void crypto_read_openvpn_key(const struct key_type *key_type, struct key_ctx_bi *ctx, const char *key_file, const char *key_inline, const int key_direction, const char *key_name, const char *opt_name)
Definition: crypto.c:1178
static bool key_ctx_bi_defined(const struct key_ctx_bi *key)
Definition: crypto.h:516
void check_replay_consistency(const struct key_type *kt, bool packet_id)
Definition: crypto.c:1007
string f
Definition: http-client.py:6
uint8_t cipher_length
Cipher length, in bytes.
Definition: crypto.h:141
void print_cipher(const cipher_kt_t *cipher)
Print a cipher list entry.
Definition: crypto.c:1779
cipher_ctx_t * cipher
Generic cipher context.
Definition: crypto.h:166
void init_key_ctx_bi(struct key_ctx_bi *ctx, const struct key2 *key2, int key_direction, const struct key_type *kt, const char *name)
Definition: crypto.c:874
mbedtls_md_info_t md_kt_t
Generic message digest key type context.
uint8_t digest[SHA256_DIGEST_LENGTH]
Definition: crypto.h:133
bool check_key(struct key *key, const struct key_type *kt)
Definition: crypto.c:937
int in_key
Index into the key2.keys array for the receiving direction.
Definition: crypto.h:202
Container for one set of cipher and/or HMAC contexts.
Definition: crypto.h:164
mbedtls_cipher_info_t cipher_kt_t
Generic cipher key type context.
struct key_ctx encrypt
Cipher and/or HMAC contexts for sending direction.
Definition: crypto.h:221
const char * filename
Definition: packet_id.h:152
hmac_ctx_t * hmac
Generic HMAC context.
Definition: crypto.h:167
void crypto_adjust_frame_parameters(struct frame *frame, const struct key_type *kt, bool packet_id, bool packet_id_long_form)
Calculate crypto overhead and adjust frame to account for that.
Definition: crypto.c:698
void read_key_file(struct key2 *key2, const char *file, const unsigned int flags)
Definition: crypto.c:1225
struct key_ctx decrypt
cipher and/or HMAC contexts for receiving direction.
Definition: crypto.h:223
int write_key_file(const int nkeys, const char *filename)
Write nkeys 1024-bits keys to file.
Definition: crypto.c:1426
#define MAX_HMAC_KEY_LENGTH
void openvpn_encrypt(struct buffer *buf, struct buffer work, struct crypto_options *opt)
Encrypt and HMAC sign a packet so that it can be sent as a data channel VPN tunnel packet to a remote...
Definition: crypto.c:303
Container for bidirectional cipher and HMAC key material.
Definition: crypto.h:181
void free_key_ctx(struct key_ctx *ctx)
Definition: crypto.c:894
int need_keys
The number of key objects necessary to support both sending and receiving.
Definition: crypto.h:204
const char * keydirection2ascii(int kd, bool remote, bool humanreadable)
Definition: crypto.c:1520
bool openvpn_decrypt(struct buffer *buf, struct buffer work, struct crypto_options *opt, const struct frame *frame, const uint8_t *ad_start)
HMAC verify and decrypt a data channel packet received from a remote OpenVPN peer.
Definition: crypto.c:672
unsigned __int8 uint8_t
Definition: config-msvc.h:123
void fixup_key(struct key *key, const struct key_type *kt)
Definition: crypto.c:976
void key2_print(const struct key2 *k, const struct key_type *kt, const char *prefix0, const char *prefix1)
Definition: crypto.c:1067
const md_kt_t * digest
Message digest static parameters.
Definition: crypto.h:144
Wrapper structure for dynamically allocated memory.
Definition: buffer.h:60
int ascii2keydirection(int msglevel, const char *str)
Definition: crypto.c:1497
static int memcmp_constant_time(const void *a, const void *b, size_t size)
As memcmp(), but constant-time.
Definition: crypto.h:500
unsigned int crypto_max_overhead(void)
Return the worst-case OpenVPN crypto overhead (in bytes)
Definition: crypto.c:732
#define SHA256_DIGEST_LENGTH
void test_crypto(struct crypto_options *co, struct frame *f)
Definition: crypto.c:1090
void init_key_type(struct key_type *kt, const char *ciphername, const char *authname, int keysize, bool tls_mode, bool warn)
Initialize a key_type structure with.
Definition: crypto.c:743
Garbage collection arena used to keep track of dynamically allocated memory.
Definition: buffer.h:116
void prng_init(const char *md_name, const int nonce_secret_len_parm)
Pseudo-random number generator initialisation.
Definition: crypto.c:1707
void prng_bytes(uint8_t *output, int len)
Definition: crypto.c:1735
const cipher_kt_t * cipher
Cipher static parameters.
Definition: crypto.h:143
Wrapper struct to pass around SHA256 digests.
Definition: crypto.h:132
void must_have_n_keys(const char *filename, const char *option, const struct key2 *key2, int n)
Definition: crypto.c:1484
int read_key(struct key *key, const struct key_type *kt, struct buffer *buf)
Definition: crypto.c:1631
Container for two sets of OpenSSL cipher and/or HMAC contexts for both sending and receiving directio...
Definition: crypto.h:219
Container for unidirectional cipher and HMAC key material.
Definition: crypto.h:151