SSL control channel wrap/unwrap and decode functions. More...

#include "buffer.h"
#include "ssl_backend.h"
#include "ssl_common.h"

Include dependency graph for ssl_pkt.h:

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

Data Structures
struct	tls_auth_standalone

struct	tls_pre_decrypt_state
	struct that stores the temporary data for the tls lite decrypt functions More...

Macros
#define	P_KEY_ID_MASK 0x07

#define	P_OPCODE_SHIFT 3

#define	P_CONTROL_HARD_RESET_CLIENT_V1 1 /* initial key from client, forget previous state */

#define	P_CONTROL_HARD_RESET_SERVER_V1 2 /* initial key from server, forget previous state */

#define	P_CONTROL_SOFT_RESET_V1 3 /* new key, graceful transition from old to new key */

#define	P_CONTROL_V1 4 /* control channel packet (usually TLS ciphertext) */

#define	P_ACK_V1 5 /* acknowledgement for packets received */

#define	P_DATA_V1 6 /* data channel packet */

#define	P_DATA_V2 9 /* data channel packet with peer-id */

#define	P_CONTROL_HARD_RESET_CLIENT_V2 7 /* initial key from client, forget previous state */

#define	P_CONTROL_HARD_RESET_SERVER_V2 8 /* initial key from server, forget previous state */

#define	P_CONTROL_HARD_RESET_CLIENT_V3 10 /* initial key from client, forget previous state */

#define	P_CONTROL_WKC_V1 11

#define	P_FIRST_OPCODE 3

#define	P_LAST_OPCODE 11

#define	TLS_RELIABLE_N_SEND_BUFFERS 6 /* also window size for reliability layer */

#define	TLS_RELIABLE_N_REC_BUFFERS 12

#define	EARLY_NEG_MASK 0xff000000

#define	EARLY_NEG_START 0x0f000000

#define	TLV_TYPE_EARLY_NEG_FLAGS 0x0001

#define	EARLY_NEG_FLAG_RESEND_WKC 0x0001

Enumerations
enum	first_packet_verdict { VERDICT_VALID_RESET_V2 , VERDICT_VALID_RESET_V3 , VERDICT_VALID_CONTROL_V1 , VERDICT_VALID_ACK_V1 , VERDICT_VALID_WKC_V1 , VERDICT_INVALID }

Functions
void	free_tls_pre_decrypt_state (struct tls_pre_decrypt_state *state)

enum first_packet_verdict	tls_pre_decrypt_lite (const struct tls_auth_standalone tas, struct tls_pre_decrypt_state state, const struct link_socket_actual from, const struct buffer buf)
	Inspect an incoming packet for which no VPN tunnel is active, and determine whether a new VPN tunnel should be created.

hmac_ctx_t *	session_id_hmac_init (void)

struct session_id	calculate_session_id_hmac (struct session_id client_sid, const struct openvpn_sockaddr from, hmac_ctx_t hmac, int handwindow, int offset)
	Calculates the HMAC based server session id based on a client session id and socket addr.

bool	check_session_hmac_and_pkt_id (struct tls_pre_decrypt_state state, const struct openvpn_sockaddr from, hmac_ctx_t *hmac, int handwindow, bool pkt_is_ack)
	Checks if a control packet has a correct HMAC server session id.

void	write_control_auth (struct tls_session session, struct key_state ks, struct buffer buf, struct link_socket_actual *to_link_addr, int opcode, int max_ack, bool prepend_ack)

bool	read_control_auth (struct buffer buf, struct tls_wrap_ctx ctx, const struct link_socket_actual from, const struct tls_options opt, bool initial_packet)
	Read a control channel authentication record.

struct buffer	tls_reset_standalone (struct tls_wrap_ctx ctx, struct tls_auth_standalone tas, struct session_id own_sid, struct session_id remote_sid, uint8_t header, bool request_resend_wkc)
	This function creates a reset packet using the information from the tls pre decrypt state.

struct buffer	extract_command_buffer (struct buffer buf, struct gc_arena gc)
	Extracts a control channel message from buf and adjusts the size of buf after the message has been extracted.

static const char *	packet_opcode_name (int op)

static struct tls_wrap_ctx *	tls_session_get_tls_wrap (struct tls_session *session, int key_id)
	Determines if the current session should use the renegotiation tls wrap struct instead the normal one and returns it.

Detailed Description

SSL control channel wrap/unwrap and decode functions.

This file (and its .c file) is designed to to be included in units/etc without pulling in a lot of dependencies.

Definition in file ssl_pkt.h.

Macro Definition Documentation

◆ EARLY_NEG_FLAG_RESEND_WKC

#define EARLY_NEG_FLAG_RESEND_WKC 0x0001

Definition at line 323 of file ssl_pkt.h.

◆ EARLY_NEG_MASK

#define EARLY_NEG_MASK 0xff000000

Definition at line 314 of file ssl_pkt.h.

◆ EARLY_NEG_START

#define EARLY_NEG_START 0x0f000000

Definition at line 315 of file ssl_pkt.h.

◆ P_ACK_V1

#define P_ACK_V1 5 /* acknowledgement for packets received */

Definition at line 46 of file ssl_pkt.h.

◆ P_CONTROL_HARD_RESET_CLIENT_V1

#define P_CONTROL_HARD_RESET_CLIENT_V1 1 /* initial key from client, forget previous state */

Definition at line 42 of file ssl_pkt.h.

◆ P_CONTROL_HARD_RESET_CLIENT_V2

#define P_CONTROL_HARD_RESET_CLIENT_V2 7 /* initial key from client, forget previous state */

Definition at line 51 of file ssl_pkt.h.

◆ P_CONTROL_HARD_RESET_CLIENT_V3

#define P_CONTROL_HARD_RESET_CLIENT_V3 10 /* initial key from client, forget previous state */

Definition at line 55 of file ssl_pkt.h.

◆ P_CONTROL_HARD_RESET_SERVER_V1

#define P_CONTROL_HARD_RESET_SERVER_V1 2 /* initial key from server, forget previous state */

Definition at line 43 of file ssl_pkt.h.

◆ P_CONTROL_HARD_RESET_SERVER_V2

#define P_CONTROL_HARD_RESET_SERVER_V2 8 /* initial key from server, forget previous state */

Definition at line 52 of file ssl_pkt.h.

◆ P_CONTROL_SOFT_RESET_V1

#define P_CONTROL_SOFT_RESET_V1 3 /* new key, graceful transition from old to new key */

Definition at line 44 of file ssl_pkt.h.

◆ P_CONTROL_V1

#define P_CONTROL_V1 4 /* control channel packet (usually TLS ciphertext) */

Definition at line 45 of file ssl_pkt.h.

◆ P_CONTROL_WKC_V1

#define P_CONTROL_WKC_V1 11

Definition at line 59 of file ssl_pkt.h.

◆ P_DATA_V1

#define P_DATA_V1 6 /* data channel packet */

Definition at line 47 of file ssl_pkt.h.

◆ P_DATA_V2

#define P_DATA_V2 9 /* data channel packet with peer-id */

Definition at line 48 of file ssl_pkt.h.

◆ P_FIRST_OPCODE

#define P_FIRST_OPCODE 3

Definition at line 64 of file ssl_pkt.h.

◆ P_KEY_ID_MASK

#define P_KEY_ID_MASK 0x07

Definition at line 38 of file ssl_pkt.h.

◆ P_LAST_OPCODE

#define P_LAST_OPCODE 11

Definition at line 65 of file ssl_pkt.h.

◆ P_OPCODE_SHIFT

#define P_OPCODE_SHIFT 3

Definition at line 39 of file ssl_pkt.h.

◆ TLS_RELIABLE_N_REC_BUFFERS

#define TLS_RELIABLE_N_REC_BUFFERS 12

Definition at line 71 of file ssl_pkt.h.

◆ TLS_RELIABLE_N_SEND_BUFFERS

#define TLS_RELIABLE_N_SEND_BUFFERS 6 /* also window size for reliability layer */

Definition at line 70 of file ssl_pkt.h.

◆ TLV_TYPE_EARLY_NEG_FLAGS

#define TLV_TYPE_EARLY_NEG_FLAGS 0x0001

Definition at line 322 of file ssl_pkt.h.

Enumeration Type Documentation

◆ first_packet_verdict

enum first_packet_verdict

Enumerator
VERDICT_VALID_RESET_V2	This packet is a valid reset packet from the peer (all but tls-crypt-v2)
VERDICT_VALID_RESET_V3	This is a valid v3 reset (tls-crypt-v2)
VERDICT_VALID_CONTROL_V1	This packet is a valid control packet from the peer.
VERDICT_VALID_ACK_V1	This packet is a valid ACK control packet from the peer, i.e. it has a valid session id hmac in it
VERDICT_VALID_WKC_V1	The packet is a valid control packet with appended wrapped client key.
VERDICT_INVALID	the packet failed on of the various checks

Definition at line 84 of file ssl_pkt.h.

Function Documentation

◆ calculate_session_id_hmac()

struct session_id calculate_session_id_hmac	(	struct session_id	client_sid,
		const struct openvpn_sockaddr *	from,
		hmac_ctx_t *	hmac,
		int	handwindow,
		int	offset
	)

Calculates the HMAC based server session id based on a client session id and socket addr.

Parameters

client_sid	session id of the client
from	link_socket from the client
hmac	the hmac context to use for the calculation
handwindow	the quantisation of the current time
offset	offset to 'now' to use

Returns: the expected server session id

Definition at line 464 of file ssl_pkt.c.

References hmac_ctx_final(), hmac_ctx_reset(), hmac_ctx_update(), now, SHA256_DIGEST_LENGTH, and SID_SIZE.

Referenced by check_session_hmac_and_pkt_id(), do_pre_decrypt_check(), and test_calc_session_id_hmac_static().

◆ check_session_hmac_and_pkt_id()

bool check_session_hmac_and_pkt_id	(	struct tls_pre_decrypt_state *	state,
		const struct openvpn_sockaddr *	from,
		hmac_ctx_t *	hmac,
		int	handwindow,
		bool	pkt_is_ack
	)

Checks if a control packet has a correct HMAC server session id.

This will also consider packets that have a packet id higher than 1 or ack packets higher than 1 to be invalid as they are not part of the initial three way handshake of OpenVPN and should not create a new connection.

Parameters

state	session information
from	link_socket from the client
hmac	the hmac context to use for the calculation
handwindow	the quantisation of the current time
pkt_is_ack	the packet being checked is a P_ACK_V1

Returns: the expected server session id

Definition at line 508 of file ssl_pkt.c.

References calculate_session_id_hmac(), i, reliable_ack::len, memcmp_constant_time(), tls_pre_decrypt_state::newbuf, tls_pre_decrypt_state::peer_session_id, reliable_ack_parse(), reliable_ack_read_packet_id(), tls_pre_decrypt_state::server_session_id, and SID_SIZE.

Referenced by do_pre_decrypt_check(), test_verify_hmac_none(), test_verify_hmac_none_out_of_range_ack(), and test_verify_hmac_tls_auth().

◆ extract_command_buffer()

struct buffer extract_command_buffer	(	struct buffer *	buf,
		struct gc_arena *	gc
	)

Extracts a control channel message from buf and adjusts the size of buf after the message has been extracted.

Parameters

buf	The buffer the message should be extracted from
gc	gc_arena to be used for the returned buffer and displaying diagnostic messages

Returns: A buffer with a control channel message or a buffer with with length 0 if there is no message or the message has invalid characters.

Definition at line 572 of file ssl_pkt.c.

References alloc_buf_gc(), BLEN, BPTR, BSTR, buf_advance(), buf_chomp(), buf_write(), CC_CRLF, CC_NULL, CC_PRINT, D_PUSH_ERRORS, format_hex(), gc, buffer::len, msg, and string_check_buf().

Referenced by check_incoming_control_channel(), and test_extract_control_message().

◆ free_tls_pre_decrypt_state()

void free_tls_pre_decrypt_state ( struct tls_pre_decrypt_state * state )

Definition at line 276 of file ssl_pkt.c.

References tls_wrap_ctx::cleanup_key_ctx, free_buf(), free_key_ctx_bi(), crypto_options::key_ctx_bi, tls_pre_decrypt_state::newbuf, tls_wrap_ctx::opt, tls_wrap_ctx::tls_crypt_v2_metadata, and tls_pre_decrypt_state::tls_wrap_tmp.

Referenced by multi_get_create_instance_udp(), test_generate_reset_packet_plain(), test_generate_reset_packet_tls_auth(), test_tls_decrypt_lite_auth(), test_tls_decrypt_lite_crypt(), test_tls_decrypt_lite_none(), test_verify_hmac_none(), test_verify_hmac_none_out_of_range_ack(), and test_verify_hmac_tls_auth().

◆ packet_opcode_name()

static const char * packet_opcode_name ( int op )

inlinestatic

Definition at line 241 of file ssl_pkt.h.

References P_ACK_V1, P_CONTROL_HARD_RESET_CLIENT_V1, P_CONTROL_HARD_RESET_CLIENT_V2, P_CONTROL_HARD_RESET_CLIENT_V3, P_CONTROL_HARD_RESET_SERVER_V1, P_CONTROL_HARD_RESET_SERVER_V2, P_CONTROL_SOFT_RESET_V1, P_CONTROL_V1, P_CONTROL_WKC_V1, P_DATA_V1, and P_DATA_V2.

Referenced by do_pre_decrypt_check(), protocol_dump(), tls_pre_decrypt(), and write_control_auth().

◆ read_control_auth()

bool read_control_auth	(	struct buffer *	buf,
		struct tls_wrap_ctx *	ctx,
		const struct link_socket_actual *	from,
		const struct tls_options *	opt,
		bool	initial_packet
	)

Read a control channel authentication record.

Parameters

buf	buffer that holds the incoming packet
ctx	control channel security context
from	incoming link socket address
opt	tls options struct for the session
initial_packet	whether this is the initial packet for the connection

Returns: if the packet was successfully processed

Definition at line 197 of file ssl_pkt.c.

References alloc_buf_gc(), ASSERT, BPTR, buf_advance(), buf_clear(), buf_copy(), buf_forward_capacity_total(), buf_init, key_ctx::cipher, cleanup(), clear_buf(), D_TLS_ERRORS, gc, gc_free(), gc_new(), buffer::len, tls_wrap_ctx::mode, msg, buffer::offset, openvpn_decrypt(), tls_wrap_ctx::opt, P_CONTROL_HARD_RESET_CLIENT_V3, P_CONTROL_WKC_V1, P_OPCODE_SHIFT, print_link_socket_actual(), SID_SIZE, swap_hmac(), tls_crypt_unwrap(), tls_crypt_v2_extract_client_key(), and tls_wrap_ctx::tls_crypt_v2_server_key.

Referenced by tls_pre_decrypt(), and tls_pre_decrypt_lite().

◆ session_id_hmac_init()

hmac_ctx_t * session_id_hmac_init ( void )

Definition at line 450 of file ssl_pkt.c.

References ASSERT, hmac_ctx_init(), hmac_ctx_new(), buffer::len, md_valid(), rand_bytes(), and SHA256_DIGEST_LENGTH.

Referenced by do_init_crypto_tls(), test_verify_hmac_none(), test_verify_hmac_none_out_of_range_ack(), and test_verify_hmac_tls_auth().

◆ tls_reset_standalone()

struct buffer tls_reset_standalone	(	struct tls_wrap_ctx *	ctx,
		struct tls_auth_standalone *	tas,
		struct session_id *	own_sid,
		struct session_id *	remote_sid,
		uint8_t	header,
		bool	request_resend_wkc
	)

This function creates a reset packet using the information from the tls pre decrypt state.

Definition at line 408 of file ssl_pkt.c.

References ASSERT, buf_init, buf_write(), buf_write_u16(), buf_write_u32(), buf_write_u8(), EARLY_NEG_FLAG_RESEND_WKC, htonpid, buffer::len, SID_SIZE, tls_wrap_control(), and TLV_TYPE_EARLY_NEG_FLAGS.

Referenced by send_hmac_reset_packet(), test_generate_reset_packet_plain(), and test_generate_reset_packet_tls_auth().

◆ tls_session_get_tls_wrap()

static struct tls_wrap_ctx * tls_session_get_tls_wrap	(	struct tls_session *	session,
		int	key_id
	)

inlinestatic

Determines if the current session should use the renegotiation tls wrap struct instead the normal one and returns it.

Parameters

session
key_id	key_id of the received/or to be send packet

Returns

Definition at line 292 of file ssl_pkt.h.

References tls_wrap_ctx::TLS_WRAP_CRYPT.

Referenced by tls_pre_decrypt(), and write_control_auth().

◆ write_control_auth()

void write_control_auth	(	struct tls_session *	session,
		struct key_state *	ks,
		struct buffer *	buf,
		struct link_socket_actual **	to_link_addr,
		int	opcode,
		int	max_ack,
		bool	prepend_ack
	)

Definition at line 169 of file ssl_pkt.c.

References ASSERT, CO_USE_TLS_KEY_MATERIAL_EXPORT, D_TLS_DEBUG, key_state::key_id, buffer::len, link_socket_actual_defined(), key_state::lru_acks, min_int(), msg, P_OPCODE_SHIFT, packet_opcode_name(), key_state::rec_ack, reliable_ack_write(), key_state::remote_addr, key_state::session_id_remote, tls_session_get_tls_wrap(), and tls_wrap_control().

Referenced by tls_process(), and tls_process_state().

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ EARLY_NEG_FLAG_RESEND_WKC

◆ EARLY_NEG_MASK

◆ EARLY_NEG_START

◆ P_ACK_V1

◆ P_CONTROL_HARD_RESET_CLIENT_V1

◆ P_CONTROL_HARD_RESET_CLIENT_V2

◆ P_CONTROL_HARD_RESET_CLIENT_V3

◆ P_CONTROL_HARD_RESET_SERVER_V1

◆ P_CONTROL_HARD_RESET_SERVER_V2

◆ P_CONTROL_SOFT_RESET_V1

◆ P_CONTROL_V1

◆ P_CONTROL_WKC_V1

◆ P_DATA_V1

◆ P_DATA_V2

◆ P_FIRST_OPCODE

◆ P_KEY_ID_MASK

◆ P_LAST_OPCODE

◆ P_OPCODE_SHIFT

◆ TLS_RELIABLE_N_REC_BUFFERS

◆ TLS_RELIABLE_N_SEND_BUFFERS

◆ TLV_TYPE_EARLY_NEG_FLAGS

Enumeration Type Documentation

◆ first_packet_verdict

Function Documentation

◆ calculate_session_id_hmac()

◆ check_session_hmac_and_pkt_id()

◆ extract_command_buffer()

◆ free_tls_pre_decrypt_state()

◆ packet_opcode_name()

◆ read_control_auth()

◆ session_id_hmac_init()

◆ tls_reset_standalone()

◆ tls_session_get_tls_wrap()

◆ write_control_auth()