crypto.h File Reference

QUIC cryptographic utilities (headers) More...

#include <stdint.h>
#include <glib.h>
#include <openssl/ssl.h>
#include <openssl/crypto.h>
#include <openssl/evp.h>
#include <openssl/kdf.h>
#include <openssl/err.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	imquic_tls
	TLS context. More...
struct	imquic_encryption
	Encryption context for a specific direction and encryption level in a QUIC connection. More...
struct	imquic_protection
	Protection context in both directions for a specific encryption level in a QUIC connection. More...

Typedefs
typedef struct imquic_tls	imquic_tls
	TLS context.
typedef struct imquic_encryption	imquic_encryption
	Encryption context for a specific direction and encryption level in a QUIC connection.
typedef struct imquic_protection	imquic_protection
	Protection context in both directions for a specific encryption level in a QUIC connection.

Functions
const char *	imquic_encryption_level_str (enum ssl_encryption_level_t level)
	Helper function to serialize to string the name of an SSL encryption level.
int	imquic_tls_init (const char *secrets_log)
	Initialize the TLS stack at startup.
void	imquic_tls_deinit (void)
	Uninitialize the TLS stack.
imquic_tls *	imquic_tls_create (gboolean is_server, const char *server_pem, const char *server_key, const char *password)
	Helper to create a new TLS context.
int	imquic_tls_enable_early_data (imquic_tls *tls, const char *ticket_file)
	Enable early data on an existing TLS context.
SSL *	imquic_tls_new_ssl (imquic_tls *tls)
	Get a new SSL instance from an existing TLS context.
void	imquic_tls_destroy (imquic_tls *tls)
	Destroy an existing imquic_tls context.
int	imquic_update_keys (imquic_protection *p, gboolean phase)
	Update the key phase for an existing context.
int	imquic_verify_retry (uint8_t *bytes, size_t blen, uint8_t *dcid, size_t dcid_len)
	Verify the integrity of a Retry packet.
HKDF utilities
int	imquic_build_hkdf_label (const char *label, uint8_t *hkdf_label, size_t buflen, size_t outlen)
	Helper to build an HKDF label, to use with HKDF_expand.
int	imquic_hkdf_extract (const EVP_MD *digest, uint8_t *key, size_t keylen, uint8_t *out, size_t *outlen)
	Helper to perform an HKDF extract.
int	imquic_hkdf_expand_label (const EVP_MD *digest, uint8_t *key, size_t keylen, const char *label, uint8_t *out, size_t outlen)
	Helper to expand an HKDF label.
int	imquic_derive_initial_secret (imquic_protection *p, uint8_t *dcid, size_t dcid_len, gboolean is_server)
	Helper to derive the initial secrets from a known connection ID.
int	imquic_expand_secret (const char *name, imquic_encryption *e, gboolean expand_hp, gboolean phase)
	Helper to expand a secret, taking into account the key phase.
Header protection
int	imquic_unprotect_header (uint8_t *bytes, size_t blen, size_t pn_offset, uint8_t *hp, size_t hp_len)
	Unprotect a received QUIC message (and unobfuscate the header)
int	imquic_protect_header (uint8_t *bytes, size_t blen, size_t pn_offset, uint8_t *hp, size_t hp_len)
	Protect a QUIC message to send (and obfuscate the header)
Payload encryption and decryption
int	imquic_decrypt_payload (uint8_t *bytes, size_t blen, uint8_t *to, size_t tlen, uint8_t *header, size_t hlen, uint64_t pn, uint8_t *key, size_t key_len, uint8_t *iv, size_t iv_len)
	Decrypt a received QUIC payload.
int	imquic_encrypt_payload (uint8_t *bytes, size_t blen, uint8_t *to, size_t tlen, uint8_t *header, size_t hlen, uint64_t pn, uint8_t *key, size_t key_len, uint8_t *iv, size_t iv_len)
	Encrypt a QUIC payload to send.

Detailed Description

QUIC cryptographic utilities (headers)

Author

Lorenzo Miniero loren.nosp@m.zo@m.nosp@m.eetec.nosp@m.ho.c.nosp@m.om

Copyright

MIT License

Cryptographic utilities for QUIC. This is where contexts for taking care of header protection and encryption at different levels are provided, with helper functions exposed to the internal QUIC stack.

Typedef Documentation

imquic_encryption

typedef struct imquic_encryption imquic_encryption

Encryption context for a specific direction and encryption level in a QUIC connection.

imquic_protection

typedef struct imquic_protection imquic_protection

Protection context in both directions for a specific encryption level in a QUIC connection.

imquic_tls

typedef struct imquic_tls imquic_tls

TLS context.

Function Documentation

imquic_build_hkdf_label()

int imquic_build_hkdf_label	(	const char *	label,
		uint8_t *	hkdf_label,
		size_t	buflen,
		size_t	outlen )

Helper to build an HKDF label, to use with HKDF_expand.

Note

This automatically prefixes the provided label with "tls13 "

Parameters

[in]	label	The label to build (without the "tls13 " prefix)
[out]	hkdf_label	The buffer where to store the HKDF label
	buflen	Size of the buffer where to store the HKDF label
	outlen	To how many bytes we want to expand

Returns

the size of the label in case of success, a negative integer otherwise

imquic_decrypt_payload()

int imquic_decrypt_payload	(	uint8_t *	bytes,
		size_t	blen,
		uint8_t *	to,
		size_t	tlen,
		uint8_t *	header,
		size_t	hlen,
		uint64_t	pn,
		uint8_t *	key,
		size_t	key_len,
		uint8_t *	iv,
		size_t	iv_len )

Decrypt a received QUIC payload.

Parameters

[in]	bytes	The buffer containing the encrypted payload
[in]	blen	The size of the buffer containing the encrypted payload
[out]	to	The buffer where to copy the decrypted payload
[in]	tlen	The size of the buffer for the decrypted payload
[in]	header	The buffer containing the QUIC message header (as AAD for authentication)
[in]	hlen	The size of the header
[in]	pn	The packet number (to use for the nonce)
[in]	key	The remote key
[in]	key_len	Size of the remote key
[in]	iv	The remote IV (to use for the nonce)
[in]	iv_len	Size of the remote IV

Returns

The size of the decrypted payload, if successful, or a negative integer otherwise

imquic_derive_initial_secret()

int imquic_derive_initial_secret	(	imquic_protection *	p,
		uint8_t *	dcid,
		size_t	dcid_len,
		gboolean	is_server )

Helper to derive the initial secrets from a known connection ID.

Note

Depending on whether we're calling this from a server or a remote endpoint, we update the local and remote properties of imquic_protection accordingly.

Parameters

p	The imquic_protection instance to derive the initial secret for
dcid	Buffer containing the connection ID to derive the initial secret from
dcid_len	Size of the connection ID buffer
is_server	Whether the endpoint is a server or a client

Returns

0 in case of success, a negative integer otherwise

imquic_encrypt_payload()

int imquic_encrypt_payload	(	uint8_t *	bytes,
		size_t	blen,
		uint8_t *	to,
		size_t	tlen,
		uint8_t *	header,
		size_t	hlen,
		uint64_t	pn,
		uint8_t *	key,
		size_t	key_len,
		uint8_t *	iv,
		size_t	iv_len )

Encrypt a QUIC payload to send.

Parameters

[in]	bytes	The buffer containing the unencrypted payload
[in]	blen	The size of the buffer containing the unencrypted payload
[out]	to	The buffer where to copy the encrypted payload
[in]	tlen	The size of the buffer for the encrypted payload
[in]	header	The buffer containing the QUIC message header (as AAD for authentication)
[in]	hlen	The size of the header
[in]	pn	The packet number (to use for the nonce)
[in]	key	The local key
[in]	key_len	Size of the local key
[in]	iv	The local IV (to use for the nonce)
[in]	iv_len	Size of the local IV

Returns

The size of the encrypted payload, if successful, or a negative integer otherwise

imquic_encryption_level_str()

const char * imquic_encryption_level_str

(

enum ssl_encryption_level_t

level

)

Helper function to serialize to string the name of an SSL encryption level.

Parameters

level

The SSL encryption level

Returns

The encryption level name as a string, if valid, or NULL otherwise

imquic_expand_secret()

int imquic_expand_secret	(	const char *	name,
		imquic_encryption *	e,
		gboolean	expand_hp,
		gboolean	phase )

Helper to expand a secret, taking into account the key phase.

Parameters

name	Short string description of what we're updating
e	The imquic_encryption we're updating
expand_hp	Whether we should expand the header protection info as well (will be FALSE when just updating keys because of the key phase)
phase	The value of the key phase bit

Returns

0 in case of success, a negative integer otherwise

imquic_hkdf_expand_label()

int imquic_hkdf_expand_label	(	const EVP_MD *	digest,
		uint8_t *	key,
		size_t	keylen,
		const char *	label,
		uint8_t *	out,
		size_t	outlen )

Helper to expand an HKDF label.

Parameters

[in]	digest	The digest to use for the expansion
[in]	key	The key to use for the expansion
[in]	keylen	Size of the key
[in]	label	The label to use for the expansion (without the "tls13 " prefix)
[out]	out	The output buffer where to store the result of the operation
[out]	outlen	Size of the output buffer

Returns

0 in case of success, a negative integer otherwise

imquic_hkdf_extract()

int imquic_hkdf_extract	(	const EVP_MD *	digest,
		uint8_t *	key,
		size_t	keylen,
		uint8_t *	out,
		size_t *	outlen )

Helper to perform an HKDF extract.

Parameters

[in]	digest	The digest to use for the extraction
[in]	key	The key to use for the extraction
[in]	keylen	Size of the key
[out]	out	The output buffer where to store the result of the operation
[out]	outlen	Size of the output buffer

Returns

0 in case of success, a negative integer otherwise

imquic_protect_header()

int imquic_protect_header	(	uint8_t *	bytes,
		size_t	blen,
		size_t	pn_offset,
		uint8_t *	hp,
		size_t	hp_len )

Protect a QUIC message to send (and obfuscate the header)

Note

The buffer is updated inline

Parameters

[in]	bytes	The buffer containing the unprotected message
[in]	blen	The size of the buffer containing the unprotected message
[in]	pn_offset	Offset in the buffer where the packet number can be found
[in]	hp	The local header protection key
[in]	hp_len	Size of the local header protection key

Returns

0 in case of success, a negative integer otherwise

imquic_tls_create()

imquic_tls * imquic_tls_create	(	gboolean	is_server,
		const char *	server_pem,
		const char *	server_key,
		const char *	password )

Helper to create a new TLS context.

Parameters

is_server	Whether this is for a server or a client
server_pem	Path to the certificate file
server_key	Path to the certificate key
password	Certificate password, if any

Returns

A pointer to a new imquic_tls instance, if successful, or NULL otherwise

imquic_tls_deinit()

void imquic_tls_deinit

(

void

)

Uninitialize the TLS stack.

imquic_tls_destroy()

void imquic_tls_destroy

(

imquic_tls *

tls

)

Destroy an existing imquic_tls context.

Parameters

tls	The imquic_tls context to destroy

imquic_tls_enable_early_data()

int imquic_tls_enable_early_data	(	imquic_tls *	tls,
		const char *	ticket_file )

Enable early data on an existing TLS context.

Parameters

tls	The imquic_tls context to enable early data on
ticket_file	The file to write/read the ticket to/from

Returns

0 in case of success, a negative integer otherwise

imquic_tls_init()

int imquic_tls_init

(

const char *

secrets_log

)

Initialize the TLS stack at startup.

Parameters

secrets_log

File to use to store QUIC secret, e.g., for Wireshark debugging (see SSLKEYLOGFILE)

Returns

0 in case of success, a negative integer otherwise

imquic_tls_new_ssl()

SSL * imquic_tls_new_ssl

(

imquic_tls *

tls

)

Get a new SSL instance from an existing TLS context.

Parameters

tls	The imquic_tls context to create the new SSL instance from

Returns

A pointer to a new SSL instance, if successful, or NULL otherwise

imquic_unprotect_header()

int imquic_unprotect_header	(	uint8_t *	bytes,
		size_t	blen,
		size_t	pn_offset,
		uint8_t *	hp,
		size_t	hp_len )

Unprotect a received QUIC message (and unobfuscate the header)

Note

The buffer is updated inline

Parameters

[in]	bytes	The buffer containing the protected message
[in]	blen	The size of the buffer containing the protected message
[in]	pn_offset	Offset in the buffer where the packet number can be found
[in]	hp	The remote header protection key
[in]	hp_len	Size of the remote header protection key

Returns

0 in case of success, a negative integer otherwise

imquic_update_keys()

int imquic_update_keys	(	imquic_protection *	p,
		gboolean	phase )

Update the key phase for an existing context.

Parameters

p	The imquic_protection instance to update
phase	The new key phase bit value

Returns

0 in case of success, a negative integer otherwise

imquic_verify_retry()

int imquic_verify_retry	(	uint8_t *	bytes,
		size_t	blen,
		uint8_t *	dcid,
		size_t	dcid_len )

Verify the integrity of a Retry packet.

Parameters

[in]	bytes	The buffer containing the payload of the Retry message
[in]	blen	The size of the buffer containing the payload
[in]	dcid	Original Destination Connection ID
[in]	dcid_len	The size of the original Destination Connection ID

Returns

0 if the packet is verified, or a negative integer otherwise