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-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 
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 {
141  uint8_t cipher_length;
142  uint8_t hmac_length;
144  const md_kt_t *digest;
145 };
146 
151 struct key
152 {
153  uint8_t cipher[MAX_CIPHER_KEY_LENGTH];
155  uint8_t hmac[MAX_HMAC_KEY_LENGTH];
157 };
158 
159 
164 struct key_ctx
165 {
168  uint8_t implicit_iv[OPENVPN_MAX_IV_LENGTH];
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 #define CO_USE_TLS_KEY_MATERIAL_EXPORT (1<<3)
258 
261  unsigned int flags;
263 };
264 
265 #define CRYPT_ERROR(format) \
266  do { msg(D_CRYPT_ERRORS, "%s: " format, error_prefix); goto error_exit; } while (false)
267 
272 #define OPENVPN_AEAD_MIN_IV_LEN (sizeof(packet_id_type) + 8)
273 
274 #define RKF_MUST_SUCCEED (1<<0)
275 #define RKF_INLINE (1<<1)
276 void read_key_file(struct key2 *key2, const char *file, const unsigned int flags);
277 
283 int write_key_file(const int nkeys, const char *filename);
284 
285 void generate_key_random(struct key *key, const struct key_type *kt);
286 
287 void check_replay_consistency(const struct key_type *kt, bool packet_id);
288 
289 bool check_key(struct key *key, const struct key_type *kt);
290 
291 void fixup_key(struct key *key, const struct key_type *kt);
292 
293 bool write_key(const struct key *key, const struct key_type *kt,
294  struct buffer *buf);
295 
296 int read_key(struct key *key, const struct key_type *kt, struct buffer *buf);
297 
308 void init_key_type(struct key_type *kt, const char *ciphername,
309  const char *authname, bool tls_mode, bool warn);
310 
311 /*
312  * Key context functions
313  */
314 
315 void init_key_ctx(struct key_ctx *ctx, const struct key *key,
316  const struct key_type *kt, int enc,
317  const char *prefix);
318 
319 void free_key_ctx(struct key_ctx *ctx);
320 
321 void init_key_ctx_bi(struct key_ctx_bi *ctx, const struct key2 *key2,
322  int key_direction, const struct key_type *kt,
323  const char *name);
324 
325 void free_key_ctx_bi(struct key_ctx_bi *ctx);
326 
327 
328 /**************************************************************************/
358 void openvpn_encrypt(struct buffer *buf, struct buffer work,
359  struct crypto_options *opt);
360 
361 
395 bool openvpn_decrypt(struct buffer *buf, struct buffer work,
396  struct crypto_options *opt, const struct frame *frame,
397  const uint8_t *ad_start);
398 
411 bool crypto_check_replay(struct crypto_options *opt,
412  const struct packet_id_net *pin, const char *error_prefix,
413  struct gc_arena *gc);
414 
415 
418  const struct key_type *kt,
419  bool packet_id,
420  bool packet_id_long_form);
421 
423 unsigned int crypto_max_overhead(void);
424 
432 void
433 write_pem_key_file(const char *filename, const char *key_name);
434 
442 bool
443 generate_ephemeral_key(struct buffer *key, const char *pem_name);
444 
455 bool
456 read_pem_key_file(struct buffer *key, const char *pem_name,
457  const char *key_file, bool key_inline);
458 
459 /* Minimum length of the nonce used by the PRNG */
460 #define NONCE_SECRET_LEN_MIN 16
461 
462 /* Maximum length of the nonce used by the PRNG */
463 #define NONCE_SECRET_LEN_MAX 64
464 
466 #define PRNG_NONCE_RESET_BYTES 1024
467 
475 void prng_init(const char *md_name, const int nonce_secret_len_parm);
476 
477 /*
478  * Message digest-based pseudo random number generator.
479  *
480  * If the PRNG was initialised with a certain message digest, uses the digest
481  * to calculate the next random number, and prevent depletion of the entropy
482  * pool.
483  *
484  * This PRNG is aimed at IV generation and similar miscellaneous tasks. Use
485  * \c rand_bytes() for higher-assurance functionality.
486  *
487  * Retrieves len bytes of pseudo random data, and places it in output.
488  *
489  * @param output Output buffer
490  * @param len Length of the output buffer
491  */
492 void prng_bytes(uint8_t *output, int len);
493 
494 void prng_uninit(void);
495 
496 /* an analogue to the random() function, but use prng_bytes */
497 long int get_random(void);
498 
500 void print_cipher(const cipher_kt_t *cipher);
501 
502 void test_crypto(struct crypto_options *co, struct frame *f);
503 
504 
505 /* key direction functions */
506 
507 void key_direction_state_init(struct key_direction_state *kds, int key_direction);
508 
509 void verify_fix_key2(struct key2 *key2, const struct key_type *kt, const char *shared_secret_file);
510 
511 void must_have_n_keys(const char *filename, const char *option, const struct key2 *key2, int n);
512 
513 int ascii2keydirection(int msglevel, const char *str);
514 
515 const char *keydirection2ascii(int kd, bool remote, bool humanreadable);
516 
517 /* print keys */
518 void key2_print(const struct key2 *k,
519  const struct key_type *kt,
520  const char *prefix0,
521  const char *prefix1);
522 
523 void crypto_read_openvpn_key(const struct key_type *key_type,
524  struct key_ctx_bi *ctx, const char *key_file,
525  bool key_inline, const int key_direction,
526  const char *key_name, const char *opt_name);
527 
528 /*
529  * Inline functions
530  */
531 
536 int memcmp_constant_time(const void *a, const void *b, size_t size);
537 
538 static inline bool
540 {
541  return key->encrypt.cipher || key->encrypt.hmac || key->decrypt.cipher || key->decrypt.hmac;
542 }
543 
554 const char *print_key_filename(const char *str, bool is_inline);
555 
556 #endif /* CRYPTO_H */
void free_key_ctx_bi(struct key_ctx_bi *ctx)
Definition: crypto.c:904
void key_direction_state_init(struct key_direction_state *kds, int key_direction)
Definition: crypto.c:1557
long int get_random(void)
Definition: crypto.c:1775
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:319
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:819
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:1586
unsigned int flags
Bit-flags determining behavior of security operation functions.
Definition: crypto.h:261
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
void init_key_type(struct key_type *kt, const char *ciphername, const char *authname, bool tls_mode, bool warn)
Initialize a key_type structure with.
Definition: crypto.c:741
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:1606
int out_key
Index into the key2.keys array for the sending direction.
Definition: crypto.h:200
void prng_uninit(void)
Definition: crypto.c:1734
#define MAX_CIPHER_KEY_LENGTH
void generate_key_random(struct key *key, const struct key_type *kt)
Definition: crypto.c:1015
mbedtls_md_context_t hmac_ctx_t
Generic HMAC context.
bool initialized
Definition: crypto.h:225
list flags
static bool key_ctx_bi_defined(const struct key_ctx_bi *key)
Definition: crypto.h:539
void check_replay_consistency(const struct key_type *kt, bool packet_id)
Definition: crypto.c:999
string f
Definition: http-client.py:6
int memcmp_constant_time(const void *a, const void *b, size_t size)
As memcmp(), but constant-time.
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:1787
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:867
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:929
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
bool read_pem_key_file(struct buffer *key, const char *pem_name, const char *key_file, bool key_inline)
Read key material from a PEM encoded files into the key structure.
Definition: crypto.c:1917
const char * filename
Definition: packet_id.h:152
hmac_ctx_t * hmac
Generic HMAC context.
Definition: crypto.h:167
const char * print_key_filename(const char *str, bool is_inline)
To be used when printing a string that may contain inline data.
Definition: crypto.c:1168
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:682
void read_key_file(struct key2 *key2, const char *file, const unsigned int flags)
Definition: crypto.c:1226
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:1429
#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:299
Container for bidirectional cipher and HMAC key material.
Definition: crypto.h:181
void free_key_ctx(struct key_ctx *ctx)
Definition: crypto.c:887
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:1528
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:656
void fixup_key(struct key *key, const struct key_type *kt)
Definition: crypto.c:968
void key2_print(const struct key2 *k, const struct key_type *kt, const char *prefix0, const char *prefix1)
Definition: crypto.c:1059
const md_kt_t * digest
Message digest static parameters.
Definition: crypto.h:144
Wrapper structure for dynamically allocated memory.
Definition: buffer.h:60
bool generate_ephemeral_key(struct buffer *key, const char *pem_name)
Generate ephermal key material into the key structure.
Definition: crypto.c:1899
int ascii2keydirection(int msglevel, const char *str)
Definition: crypto.c:1505
void crypto_read_openvpn_key(const struct key_type *key_type, struct key_ctx_bi *ctx, const char *key_file, bool key_inline, const int key_direction, const char *key_name, const char *opt_name)
Definition: crypto.c:1179
unsigned int crypto_max_overhead(void)
Return the worst-case OpenVPN crypto overhead (in bytes)
Definition: crypto.c:716
#define SHA256_DIGEST_LENGTH
void test_crypto(struct crypto_options *co, struct frame *f)
Definition: crypto.c:1082
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:1715
void prng_bytes(uint8_t *output, int len)
Definition: crypto.c:1743
const cipher_kt_t * cipher
Cipher static parameters.
Definition: crypto.h:143
void write_pem_key_file(const char *filename, const char *key_name)
Generate a server key with enough randomness to fill a key struct and write to file.
Definition: crypto.c:1861
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:1492
int read_key(struct key *key, const struct key_type *kt, struct buffer *buf)
Definition: crypto.c:1639
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