crypto_epoch.h File Reference

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
void	ovpn_hkdf_expand (const uint8_t *secret, const uint8_t *info, int info_len, uint8_t *out, int out_len)
	Implementation of the RFC5869 HKDF-Expand function with the following restrictions.
bool	ovpn_expand_label (const uint8_t *secret, size_t secret_len, const uint8_t *label, size_t label_len, const uint8_t *context, size_t context_len, uint8_t *out, uint16_t out_len)
	Variant of the RFC 8446 TLS 1.3 HKDF-Expand-Label function with the following differences/restrictions:
void	epoch_data_key_derive (struct key_parameters *key, const struct epoch_key *epoch_key, const struct key_type *kt)
	Generate a data channel key pair from the epoch key.
void	epoch_generate_future_receive_keys (struct crypto_options *co)
	Generates and fills the epoch_data_keys_future with next valid future keys in crypto_options using the epoch of the key in crypto_options.key_ctx_bi.decrypt as starting point.
void	epoch_replace_update_recv_key (struct crypto_options *co, uint16_t new_epoch)
	This is called when the peer uses a new send key that is not the default key.
void	epoch_iterate_send_key (struct crypto_options *co)
	Updates the send key and send_epoch_key in cryptio_options->key_ctx_bi to use the next epoch.
void	free_epoch_key_ctx (struct crypto_options *co)
	Frees the extra data structures used by epoch keys in crypto_options.
void	epoch_init_key_ctx (struct crypto_options *co, const struct key_type *key_type, const struct epoch_key *e1_send, const struct epoch_key *e1_recv, uint16_t future_key_count)
	Initialises data channel keys and internal structures for epoch data keys using the provided E0 epoch key.
struct key_ctx *	epoch_lookup_decrypt_key (struct crypto_options *opt, uint16_t epoch)
	Using an epoch, this function will try to retrieve a decryption key context that matches that epoch from the opt argument.
void	epoch_check_send_iterate (struct crypto_options *opt)
	Checks if we need to iterate the send epoch key.

Function Documentation

epoch_check_send_iterate()

void epoch_check_send_iterate

(

struct crypto_options *

opt

)

Checks if we need to iterate the send epoch key.

This needs to be in one of the following condition

• max epoch counter reached
• send key aead usage limit reached (for AES-GCM and similar ciphers)
• recv key usage limit reached

Definition at line 414 of file crypto_epoch.c.

References crypto_options::aead_usage_limit, aead_usage_limit_reached(), cipher_decrypt_verify_fail_warn(), key_ctx_bi::decrypt, key_ctx_bi::encrypt, epoch_key::epoch, key_ctx::epoch, epoch_iterate_send_key(), crypto_options::epoch_key_send, packet_id_rec::id, packet_id_send::id, crypto_options::key_ctx_bi, crypto_options::packet_id, PACKET_ID_EPOCH_MAX, packet_id::rec, and packet_id::send.

Referenced by openvpn_encrypt_aead().

epoch_data_key_derive()

void epoch_data_key_derive	(	struct key_parameters *	key,
		const struct epoch_key *	epoch_key,
		const struct key_type *	kt
	)

Generate a data channel key pair from the epoch key.

Parameters

key	Destination for the generated data key
epoch_key	Epoch key to be used
kt	Cipher information to generate the data channel key for

Definition at line 145 of file crypto_epoch.c.

References key_type::cipher, key::cipher, cipher_kt_iv_size(), cipher_kt_key_size(), epoch_key::epoch, epoch_key::epoch_key, key::hmac, and ovpn_expand_label().

Referenced by epoch_init_recv_key(), epoch_init_send_key_ctx(), and epoch_test_derive_data_key().

epoch_generate_future_receive_keys()

void epoch_generate_future_receive_keys

(

struct crypto_options *

co

)

Generates and fills the epoch_data_keys_future with next valid future keys in crypto_options using the epoch of the key in crypto_options.key_ctx_bi.decrypt as starting point.

This assume that the normal key_ctx_bi and epoch keys have been already setup.

This method is also called if crypto_options.key_ctx_bi.decrypt is changed. The method will then change the future keys in epoch_data_keys_future to free the ones that are older than the crypto_options.key_ctx_bi.decrypt and generate the keys from the newer epoch.

Definition at line 213 of file crypto_epoch.c.

References ASSERT, CLEAR, key_ctx_bi::decrypt, epoch_key::epoch, key_ctx::epoch, crypto_options::epoch_data_keys_future, crypto_options::epoch_data_keys_future_count, epoch_init_recv_key(), epoch_key_iterate(), crypto_options::epoch_key_recv, free_key_ctx(), key_ctx_bi::initialized, and crypto_options::key_ctx_bi.

Referenced by crypto_test_epoch_key_generation(), epoch_init_key_ctx(), and epoch_replace_update_recv_key().

epoch_init_key_ctx()

void epoch_init_key_ctx	(	struct crypto_options *	co,
		const struct key_type *	key_type,
		const struct epoch_key *	e1_send,
		const struct epoch_key *	e1_recv,
		uint16_t	future_key_count
	)

Initialises data channel keys and internal structures for epoch data keys using the provided E0 epoch key.

Parameters

co	The crypto option struct to initialise the epoch related fields
key_type	The parameter of what encryption cipher to use when initialising the epoch related fields
e1_send	The E1 send epoch key derived by TLS-EKM
e1_recv	The E1 receive epoch key derived by TLS-EKM
future_key_count	the number of future epoch keys that should be considered valid when receiving data from the peer

Definition at line 353 of file crypto_epoch.c.

References crypto_options::aead_usage_limit, ALLOC_ARRAY_CLEAR, ASSERT, key_type::cipher, cipher_get_aead_limits(), key_ctx_bi::decrypt, epoch_key::epoch, crypto_options::epoch_data_keys_future, crypto_options::epoch_data_keys_future_count, epoch_generate_future_receive_keys(), epoch_init_recv_key(), epoch_init_send_key_ctx(), crypto_options::epoch_key_recv, crypto_options::epoch_key_send, crypto_options::epoch_key_type, key_ctx_bi::initialized, and crypto_options::key_ctx_bi.

Referenced by crypto_test_epoch_setup(), init_crypto_options(), and init_epoch_keys().

epoch_iterate_send_key()

void epoch_iterate_send_key

(

struct crypto_options *

co

)

Updates the send key and send_epoch_key in cryptio_options->key_ctx_bi to use the next epoch.

Definition at line 275 of file crypto_epoch.c.

References ASSERT, key_ctx_bi::encrypt, epoch_key::epoch, epoch_init_send_key_ctx(), epoch_key_iterate(), crypto_options::epoch_key_send, free_key_ctx(), and crypto_options::key_ctx_bi.

Referenced by crypto_test_epoch_key_rotation(), epoch_check_send_iterate(), and init_crypto_options().

epoch_lookup_decrypt_key()

struct key_ctx * epoch_lookup_decrypt_key	(	struct crypto_options *	opt,
		uint16_t	epoch
	)

Using an epoch, this function will try to retrieve a decryption key context that matches that epoch from the opt argument.

Parameters

opt	crypto_options to use to find the decrypt key
epoch	epoch of the key to lookup

Returns

the key context with

Definition at line 375 of file crypto_epoch.c.

References key_ctx_bi::decrypt, key_ctx::epoch, crypto_options::epoch_data_keys_future, crypto_options::epoch_data_keys_future_count, crypto_options::epoch_retiring_data_receive_key, and crypto_options::key_ctx_bi.

Referenced by crypto_test_epoch_key_overflow(), crypto_test_epoch_key_receive_lookup(), and openvpn_decrypt_aead().

epoch_replace_update_recv_key()

void epoch_replace_update_recv_key	(	struct crypto_options *	co,
		uint16_t	new_epoch
	)

This is called when the peer uses a new send key that is not the default key.

This function ensures the following:

• recv key matches the epoch index provided
• send key epoch is equal or higher than recv_key epoch

Parameters

co	crypto_options to update
new_epoch	the new epoch to use for the receive key

Definition at line 284 of file crypto_epoch.c.

References ASSERT, key_ctx_bi::decrypt, key_ctx_bi::encrypt, epoch_key::epoch, key_ctx::epoch, crypto_options::epoch_data_keys_future, crypto_options::epoch_data_keys_future_count, epoch_generate_future_receive_keys(), epoch_init_send_key_ctx(), epoch_key_iterate(), crypto_options::epoch_key_send, crypto_options::epoch_retiring_data_receive_key, crypto_options::epoch_retiring_key_pid_recv, free_key_ctx(), crypto_options::key_ctx_bi, crypto_options::packet_id, packet_id_move_recv(), and packet_id::rec.

Referenced by crypto_check_replay(), crypto_test_epoch_key_overflow(), crypto_test_epoch_key_receive_lookup(), and crypto_test_epoch_key_rotation().

free_epoch_key_ctx()

void free_epoch_key_ctx

(

struct crypto_options *

co

)

Frees the extra data structures used by epoch keys in crypto_options.

Definition at line 338 of file crypto_epoch.c.

References CLEAR, crypto_options::epoch_data_keys_future, crypto_options::epoch_data_keys_future_count, crypto_options::epoch_key_recv, crypto_options::epoch_key_send, crypto_options::epoch_retiring_data_receive_key, crypto_options::epoch_retiring_key_pid_recv, free_key_ctx(), and packet_id_rec::seq_list.

Referenced by crypto_test_epoch_teardown(), key_state_free(), and uninit_crypto_options().

ovpn_expand_label()

bool ovpn_expand_label	(	const uint8_t *	secret,
		size_t	secret_len,
		const uint8_t *	label,
		size_t	label_len,
		const uint8_t *	context,
		size_t	context_len,
		uint8_t *	out,
		uint16_t	out_len
	)

Variant of the RFC 8446 TLS 1.3 HKDF-Expand-Label function with the following differences/restrictions:

• secret must 32 bytes in length
• label prefix is "ovpn " instead of "tls13 "
• HASH is always SHA256

Parameters

secret	Input secret
secret_len	length of the input secret
label	Label for the exported key material
label_len	length of the label
context	optional context
context_len	length of the context
out	output keying material
out_len	length of output keying material

Returns

Definition at line 78 of file crypto_epoch.c.

References alloc_buf_gc(), ASSERT, buf_bptr(), buf_len(), buf_write(), buf_write_u16(), buf_write_u8(), gc, gc_free(), gc_new(), buffer::len, and ovpn_hkdf_expand().

Referenced by crypto_test_ovpn_label_expand(), epoch_data_key_derive(), and epoch_key_iterate().

ovpn_hkdf_expand()

void ovpn_hkdf_expand	(	const uint8_t *	secret,
		const uint8_t *	info,
		int	info_len,
		uint8_t *	out,
		int	out_len
	)

Implementation of the RFC5869 HKDF-Expand function with the following restrictions.

• secret is assumed to be always 32 bytes
• HASH is always SHA256

Parameters

secret	the input keying material (HMAC key)
info	context and application specific information
info_len	length of the info string
out	output keying material
out_len	length of output keying material

Definition at line 43 of file crypto_epoch.c.

References hmac_ctx_cleanup(), hmac_ctx_final(), hmac_ctx_free(), hmac_ctx_init(), hmac_ctx_new(), hmac_ctx_reset(), hmac_ctx_update(), min_int(), and SHA256_DIGEST_LENGTH.

Referenced by crypto_test_hkdf_expand_test_ovpn(), crypto_test_hkdf_expand_testa1(), crypto_test_hkdf_expand_testa2(), crypto_test_hkdf_expand_testa3(), and ovpn_expand_label().