OpenVPN
Data Structures | Macros | Functions
crypto.h File Reference
#include "crypto_backend.h"
#include "basic.h"
#include "buffer.h"
#include "packet_id.h"
#include "mtu.h"
Include dependency graph for crypto.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  sha256_digest
 Wrapper struct to pass around SHA256 digests. More...
 
struct  key_type
 
struct  key
 Container for unidirectional cipher and HMAC key material. More...
 
struct  key_ctx
 Container for one set of cipher and/or HMAC contexts. More...
 
struct  key2
 Container for bidirectional cipher and HMAC key material. More...
 
struct  key_direction_state
 Key ordering of the key2.keys array. More...
 
struct  key_ctx_bi
 Container for two sets of OpenSSL cipher and/or HMAC contexts for both sending and receiving directions. More...
 
struct  crypto_options
 Security parameter state for processing data channel packets. More...
 

Macros

#define KEY_DIRECTION_BIDIRECTIONAL   0 /* same keys for both directions */
 
#define KEY_DIRECTION_NORMAL   1 /* encrypt with keys[0], decrypt with keys[1] */
 
#define KEY_DIRECTION_INVERSE   2 /* encrypt with keys[1], decrypt with keys[0] */
 
#define CO_PACKET_ID_LONG_FORM   (1<<0)
 Bit-flag indicating whether to use OpenVPN's long packet ID format. More...
 
#define CO_IGNORE_PACKET_ID   (1<<1)
 Bit-flag indicating whether to ignore the packet ID of a received packet. More...
 
#define CO_MUTE_REPLAY_WARNINGS   (1<<2)
 Bit-flag indicating not to display replay warnings. More...
 
#define CO_USE_TLS_KEY_MATERIAL_EXPORT   (1<<3)
 Bit-flag indicating that data channel key derivation is done using TLS keying material export [RFC5705]. More...
 
#define CRYPT_ERROR(format)   do { msg(D_CRYPT_ERRORS, "%s: " format, error_prefix); goto error_exit; } while (false)
 
#define OPENVPN_AEAD_MIN_IV_LEN   (sizeof(packet_id_type) + 8)
 Minimal IV length for AEAD mode ciphers (in bytes): 4-byte packet id + 8 bytes implicit IV. More...
 
#define RKF_MUST_SUCCEED   (1<<0)
 
#define RKF_INLINE   (1<<1)
 
#define NONCE_SECRET_LEN_MIN   16
 
#define NONCE_SECRET_LEN_MAX   64
 
#define PRNG_NONCE_RESET_BYTES   1024
 Number of bytes of random to allow before resetting the nonce. More...
 

Functions

void read_key_file (struct key2 *key2, const char *file, const unsigned int flags)
 
int write_key_file (const int nkeys, const char *filename)
 Write nkeys 1024-bits keys to file. More...
 
void generate_key_random (struct key *key, const struct key_type *kt)
 
void check_replay_consistency (const struct key_type *kt, bool packet_id)
 
bool check_key (struct key *key, const struct key_type *kt)
 
void fixup_key (struct key *key, const struct key_type *kt)
 
bool write_key (const struct key *key, const struct key_type *kt, struct buffer *buf)
 
int read_key (struct key *key, const struct key_type *kt, struct buffer *buf)
 
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. More...
 
void init_key_ctx (struct key_ctx *ctx, const struct key *key, const struct key_type *kt, int enc, const char *prefix)
 
void free_key_ctx (struct key_ctx *ctx)
 
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)
 
void free_key_ctx_bi (struct key_ctx_bi *ctx)
 
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. More...
 
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. More...
 
unsigned int crypto_max_overhead (void)
 Return the worst-case OpenVPN crypto overhead (in bytes) More...
 
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. More...
 
bool generate_ephemeral_key (struct buffer *key, const char *pem_name)
 Generate ephermal key material into the key structure. More...
 
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. More...
 
void prng_init (const char *md_name, const int nonce_secret_len_parm)
 Pseudo-random number generator initialisation. More...
 
void prng_bytes (uint8_t *output, int len)
 
void prng_uninit (void)
 
long int get_random (void)
 
void print_cipher (const cipher_kt_t *cipher)
 Print a cipher list entry. More...
 
void test_crypto (struct crypto_options *co, struct frame *f)
 
void key_direction_state_init (struct key_direction_state *kds, int key_direction)
 
void verify_fix_key2 (struct key2 *key2, const struct key_type *kt, const char *shared_secret_file)
 
void must_have_n_keys (const char *filename, const char *option, const struct key2 *key2, int n)
 
int ascii2keydirection (int msglevel, const char *str)
 
const char * keydirection2ascii (int kd, bool remote, bool humanreadable)
 
void key2_print (const struct key2 *k, const struct key_type *kt, const char *prefix0, const char *prefix1)
 
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)
 
int memcmp_constant_time (const void *a, const void *b, size_t size)
 As memcmp(), but constant-time. More...
 
static bool key_ctx_bi_defined (const struct key_ctx_bi *key)
 
const char * print_key_filename (const char *str, bool is_inline)
 To be used when printing a string that may contain inline data. More...
 
Functions for performing security operations on data channel packets
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 OpenVPN peer. More...
 
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. More...
 

Macro Definition Documentation

◆ CO_IGNORE_PACKET_ID

#define CO_IGNORE_PACKET_ID   (1<<1)

Bit-flag indicating whether to ignore the packet ID of a received packet.

This flag is used during processing of the first packet received from a client.

Definition at line 248 of file crypto.h.

Referenced by openvpn_decrypt_v1(), tls_auth_standalone_init(), tls_crypt_ignore_replay(), and tls_crypt_unwrap().

◆ CO_MUTE_REPLAY_WARNINGS

#define CO_MUTE_REPLAY_WARNINGS   (1<<2)

Bit-flag indicating not to display replay warnings.

Definition at line 254 of file crypto.h.

Referenced by crypto_check_replay(), do_init_crypto_static(), and do_init_crypto_tls().

◆ CO_PACKET_ID_LONG_FORM

#define CO_PACKET_ID_LONG_FORM   (1<<0)

Bit-flag indicating whether to use OpenVPN's long packet ID format.

Definition at line 245 of file crypto.h.

Referenced by crypto_check_replay(), do_init_crypto_static(), do_init_crypto_tls(), openvpn_decrypt_v1(), openvpn_encrypt_v1(), tls_crypt_v2_extract_client_key(), and tls_session_update_crypto_params_do_work().

◆ CO_USE_TLS_KEY_MATERIAL_EXPORT

#define CO_USE_TLS_KEY_MATERIAL_EXPORT   (1<<3)

Bit-flag indicating that data channel key derivation is done using TLS keying material export [RFC5705].

Definition at line 257 of file crypto.h.

Referenced by add_option(), generate_key_expansion(), multi_client_set_protocol_options(), p2p_mode_ncp(), p2p_ncp_set_options(), and prepare_push_reply().

◆ CRYPT_ERROR

#define CRYPT_ERROR (   format)    do { msg(D_CRYPT_ERRORS, "%s: " format, error_prefix); goto error_exit; } while (false)

◆ KEY_DIRECTION_BIDIRECTIONAL

#define KEY_DIRECTION_BIDIRECTIONAL   0 /* same keys for both directions */

◆ KEY_DIRECTION_INVERSE

#define KEY_DIRECTION_INVERSE   2 /* encrypt with keys[1], decrypt with keys[0] */

◆ KEY_DIRECTION_NORMAL

#define KEY_DIRECTION_NORMAL   1 /* encrypt with keys[0], decrypt with keys[1] */

◆ NONCE_SECRET_LEN_MAX

#define NONCE_SECRET_LEN_MAX   64

Definition at line 463 of file crypto.h.

Referenced by add_option(), and prng_init().

◆ NONCE_SECRET_LEN_MIN

#define NONCE_SECRET_LEN_MIN   16

Definition at line 460 of file crypto.h.

Referenced by add_option(), and prng_init().

◆ OPENVPN_AEAD_MIN_IV_LEN

#define OPENVPN_AEAD_MIN_IV_LEN   (sizeof(packet_id_type) + 8)

Minimal IV length for AEAD mode ciphers (in bytes): 4-byte packet id + 8 bytes implicit IV.

Definition at line 272 of file crypto.h.

Referenced by key_ctx_update_implicit_iv(), openvpn_encrypt_aead(), and test_crypto().

◆ PRNG_NONCE_RESET_BYTES

#define PRNG_NONCE_RESET_BYTES   1024

Number of bytes of random to allow before resetting the nonce.

Definition at line 466 of file crypto.h.

Referenced by prng_bytes().

◆ RKF_INLINE

#define RKF_INLINE   (1<<1)

Definition at line 275 of file crypto.h.

Referenced by crypto_read_openvpn_key(), and read_key_file().

◆ RKF_MUST_SUCCEED

#define RKF_MUST_SUCCEED   (1<<0)

Definition at line 274 of file crypto.h.

Referenced by crypto_read_openvpn_key(), and read_key_file().

Function Documentation

◆ ascii2keydirection()

int ascii2keydirection ( int  msglevel,
const char *  str 
)

Definition at line 1505 of file crypto.c.

References KEY_DIRECTION_BIDIRECTIONAL, KEY_DIRECTION_INVERSE, KEY_DIRECTION_NORMAL, and msg.

Referenced by add_option().

◆ check_key()

bool check_key ( struct key key,
const struct key_type kt 
)

◆ check_replay_consistency()

void check_replay_consistency ( const struct key_type kt,
bool  packet_id 
)

◆ crypto_adjust_frame_parameters()

void crypto_adjust_frame_parameters ( struct frame frame,
const struct key_type kt,
bool  packet_id,
bool  packet_id_long_form 
)

◆ crypto_check_replay()

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.

Parameters
optCrypto options for this packet, contains replay state.
pinPacket ID read from packet.
error_prefixPrefix to use when printing error messages.
gcGarbage collector to use.
Returns
true if packet ID is validated to be not a replay, false otherwise.

Definition at line 319 of file crypto.c.

References CO_MUTE_REPLAY_WARNINGS, CO_PACKET_ID_LONG_FORM, D_REPLAY_ERRORS, crypto_options::flags, msg, crypto_options::packet_id, packet_id_add(), packet_id_net_print(), packet_id_persist_save_obj(), packet_id_reap_test(), packet_id_test(), crypto_options::pid_persist, and packet_id::rec.

Referenced by openvpn_decrypt_aead(), openvpn_decrypt_v1(), and tls_crypt_unwrap().

◆ crypto_max_overhead()

unsigned int crypto_max_overhead ( void  )

◆ crypto_read_openvpn_key()

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 
)

◆ fixup_key()

void fixup_key ( struct key key,
const struct key_type kt 
)

◆ free_key_ctx()

void free_key_ctx ( struct key_ctx ctx)

◆ free_key_ctx_bi()

void free_key_ctx_bi ( struct key_ctx_bi ctx)

◆ generate_ephemeral_key()

bool generate_ephemeral_key ( struct buffer key,
const char *  pem_name 
)

Generate ephermal key material into the key structure.

Parameters
keythe key structure that will hold the key material
pem_namethe name used for logging
Returns
true if key generation was successful

Definition at line 1905 of file crypto.c.

References BCAP, BEND, buf_inc_len(), buffer::len, M_INFO, M_WARN, msg, and rand_bytes().

Referenced by auth_token_init_secret().

◆ generate_key_random()

void generate_key_random ( struct key key,
const struct key_type kt 
)

◆ get_random()

long int get_random ( void  )

◆ init_key_ctx()

void init_key_ctx ( struct key_ctx ctx,
const struct key key,
const struct key_type kt,
int  enc,
const char *  prefix 
)

◆ init_key_ctx_bi()

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 
)

◆ init_key_type()

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.

Parameters
ktThe struct key_type to initialize
ciphernameThe name of the cipher to use
authnameThe name of the HMAC digest to use
tls_modeSpecifies whether we are running in TLS mode, which allows more ciphers than static key mode.
warnPrint warnings when null cipher / auth is used.

Definition at line 741 of file crypto.c.

References ASSERT, key_type::cipher, cipher_kt_block_size(), cipher_kt_get(), cipher_kt_key_size(), cipher_kt_mode_aead(), cipher_kt_mode_cbc(), cipher_kt_mode_ofb_cfb(), key_type::cipher_length, CLEAR, key_type::digest, ENABLE_OFB_CFB_MODE, key_type::hmac_length, M_FATAL, M_WARN, md_kt_get(), md_kt_size(), msg, OPENVPN_MAX_CIPHER_BLOCK_SIZE, and warn_insecure_key_type().

Referenced by calc_options_string_link_mtu(), do_init_crypto_static(), do_init_crypto_tls_c1(), options_string(), and tls_session_update_crypto_params_do_work().

◆ key2_print()

void key2_print ( const struct key2 k,
const struct key_type kt,
const char *  prefix0,
const char *  prefix1 
)

◆ key_ctx_bi_defined()

static bool key_ctx_bi_defined ( const struct key_ctx_bi key)
inlinestatic

◆ key_direction_state_init()

void key_direction_state_init ( struct key_direction_state kds,
int  key_direction 
)

◆ keydirection2ascii()

const char* keydirection2ascii ( int  kd,
bool  remote,
bool  humanreadable 
)

◆ memcmp_constant_time()

int memcmp_constant_time ( const void *  a,
const void *  b,
size_t  size 
)

As memcmp(), but constant-time.

Returns 0 when data is equal, non-zero otherwise.

Definition at line 1071 of file crypto_openssl.c.

References SSL_CTX_get_default_passwd_cb(), and SSL_CTX_get_default_passwd_cb_userdata().

Referenced by check_hmac_token(), is_auth_token(), openvpn_decrypt_v1(), tls_crypt_unwrap(), tls_crypt_v2_unwrap_client_key(), verify_auth_token(), and verify_cert().

◆ must_have_n_keys()

void must_have_n_keys ( const char *  filename,
const char *  option,
const struct key2 key2,
int  n 
)

Definition at line 1492 of file crypto.c.

References M_FATAL, msg, key2::n, and PACKAGE.

Referenced by crypto_read_openvpn_key().

◆ print_cipher()

void print_cipher ( const cipher_kt_t cipher)

Print a cipher list entry.

Definition at line 1787 of file crypto.c.

References cipher_kt_block_size(), cipher_kt_key_size(), cipher_kt_mode_cbc(), cipher_kt_name(), and cipher_kt_var_key_size().

Referenced by show_available_ciphers().

◆ print_key_filename()

const char* print_key_filename ( const char *  str,
bool  is_inline 
)

To be used when printing a string that may contain inline data.

If "is_inline" is true, return the inline tag. If "is_inline" is false and "str" is not NULL, return "str". Return the constant string "[NULL]" otherwise.

Parameters
strthe original string to return when is_inline is false
is_inlinetrue when str contains an inline data of some sort

Definition at line 1168 of file crypto.c.

References np().

Referenced by backend_tls_ctx_reload_crl(), crypto_read_openvpn_key(), key_ctx_bi_defined(), read_key_file(), tls_ctx_load_ca(), tls_ctx_load_dh_params(), tls_ctx_load_extra_certs(), and tls_ctx_load_priv_file().

◆ prng_bytes()

void prng_bytes ( uint8_t *  output,
int  len 
)

◆ prng_init()

void prng_init ( const char *  md_name,
const int  nonce_secret_len_parm 
)

Pseudo-random number generator initialisation.

(see prng_rand_bytes())

Parameters
md_nameName of the message digest to use
nonce_secret_len_paramLength of the nonce to use

Definition at line 1715 of file crypto.c.

References ASSERT, check_malloc_return(), D_CRYPTO_DEBUG, dmsg, malloc, md_kt_get(), md_kt_name(), md_kt_size(), nonce_data, nonce_md, nonce_secret_len, NONCE_SECRET_LEN_MAX, NONCE_SECRET_LEN_MIN, prng_reset_nonce(), and prng_uninit().

Referenced by do_init_crypto_tls_c1(), and init_static().

◆ prng_uninit()

void prng_uninit ( void  )

Definition at line 1734 of file crypto.c.

References free, nonce_data, nonce_md, and nonce_secret_len.

Referenced by free_ssl_lib(), init_static(), and prng_init().

◆ read_key()

int read_key ( struct key key,
const struct key_type kt,
struct buffer buf 
)

◆ read_key_file()

void read_key_file ( struct key2 key2,
const char *  file,
const unsigned int  flags 
)

◆ read_pem_key_file()

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.

Parameters
keythe key structure that will hold the key material
pem_namethe name used in the pem encoding start/end lines
key_filename of the file to read or the key itself if key_inline is true
key_inlineTrue if key_file contains an inline key, False otherwise.
Returns
true if reading into key was successful

Definition at line 1923 of file crypto.c.

References buf_clear(), buf_set_read(), buf_valid(), buffer_read_from_file(), crypto_pem_decode(), gc_free(), gc_new(), M_WARN, and msg.

Referenced by auth_token_init_secret(), tls_crypt_v2_init_client_key(), and tls_crypt_v2_init_server_key().

◆ test_crypto()

void test_crypto ( struct crypto_options co,
struct frame f 
)

◆ verify_fix_key2()

void verify_fix_key2 ( struct key2 key2,
const struct key_type kt,
const char *  shared_secret_file 
)

Definition at line 1586 of file crypto.c.

References check_key(), fixup_key(), key2::keys, M_FATAL, msg, and key2::n.

Referenced by crypto_read_openvpn_key().

◆ write_key()

bool write_key ( const struct key key,
const struct key_type kt,
struct buffer buf 
)

◆ write_key_file()

int write_key_file ( const int  nkeys,
const char *  filename 
)

Write nkeys 1024-bits keys to file.

Returns
number of random bits written, or -1 on failure.

Definition at line 1429 of file crypto.c.

References alloc_buf_gc(), BLEN, BPTR, buf_clear(), buf_printf(), buffer_write_file(), format_hex_ex(), gc_free(), gc_new(), generate_key_random(), secure_memzero(), static_key_foot, and static_key_head.

Referenced by do_genkey().

◆ write_pem_key_file()

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.

Parameters
filenameFilename of the server key file to create.
pem_nameThe name to use in the PEM header/footer.

Definition at line 1867 of file crypto.c.

References BLEN, BPTR, buf_clear(), buf_set_read(), buffer_write_file(), clear_buf(), crypto_pem_encode(), gc_free(), gc_new(), M_ERR, M_NONFATAL, M_WARN, msg, rand_bytes(), and secure_memzero().

Referenced by auth_token_write_server_key_file(), and tls_crypt_v2_write_server_key_file().