#include "session_id.h"
#include "socket.h"
#include "packet_id.h"
#include "crypto.h"
#include "options.h"
#include "ssl_backend.h"

Include dependency graph for ssl_common.h:

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

Go to the source code of this file.

Data Structures
struct	key_source
	Container for one half of random material to be used in key method 2 data channel key generation. More...

struct	key_source2
	Container for both halves of random material to be used in key method 2 data channel key generation. More...

struct	auth_deferred_status

struct	key_state
	Security parameter state of one TLS and data channel key session. More...

struct	tls_wrap_ctx
	Control channel wrapping (–tls-auth/–tls-crypt) context. More...

struct	tls_options

struct	tls_session
	Security parameter state of a single session within a VPN tunnel. More...

struct	tls_multi
	Security parameter state for a single VPN tunnel. More...

Macros
#define	UP_TYPE_AUTH "Auth"

#define	UP_TYPE_PRIVATE_KEY "Private Key"

#define	SSLF_CLIENT_CERT_NOT_REQUIRED (1<<0)

#define	SSLF_CLIENT_CERT_OPTIONAL (1<<1)

#define	SSLF_USERNAME_AS_COMMON_NAME (1<<2)

#define	SSLF_AUTH_USER_PASS_OPTIONAL (1<<3)

#define	SSLF_OPT_VERIFY (1<<4)

#define	SSLF_CRL_VERIFY_DIR (1<<5)

#define	SSLF_TLS_VERSION_MIN_SHIFT 6

#define	SSLF_TLS_VERSION_MIN_MASK 0xF /* (uses bit positions 6 to 9) */

#define	SSLF_TLS_VERSION_MAX_SHIFT 10

#define	SSLF_TLS_VERSION_MAX_MASK 0xF /* (uses bit positions 10 to 13) */

#define	SSLF_TLS_DEBUG_ENABLED (1<<14)

#define	KEY_SCAN_SIZE 3

#define	AUTH_TOKEN_HMAC_OK (1<<0)
	Auth-token sent from client has valid hmac. More...

#define	AUTH_TOKEN_EXPIRED (1<<1)
	Auth-token sent from client has expired. More...

#define	AUTH_TOKEN_VALID_EMPTYUSER (1<<2)
	Auth-token is only valid for an empty username and not the username actually supplied from the client. More...

Control channel negotiation states
These states represent the different phases of control channel negotiation between OpenVPN peers. OpenVPN servers and clients progress through the states in a different order, because of their different roles during exchange of random material. The references to the `key_source2` structure in the list below is only valid if key method 2 is being used. See the data channel key generation related page for more information. Clients follow this order: `S_INITIAL`, ready to begin three-way handshake and control channel negotiation. `S_PRE_START`, have started three-way handshake, waiting for acknowledgment from remote. `S_START`, initial three-way handshake complete. `S_SENT_KEY`, have sent local part of `key_source2` random material. `S_GOT_KEY`, have received remote part of `key_source2` random material. `S_ACTIVE`, control channel successfully established `S_GENERATED_KEYS`, the data channel keys have been generated Servers follow the same order, except for `S_SENT_KEY` and `S_GOT_KEY` being reversed, because the server first receives the client's `key_source2` random material before generating and sending its own.
#define	S_ERROR (-2)
	Error state. More...

#define	S_ERROR_PRE (-1)
	Error state but try to send out alerts before killing the keystore and moving it to S_ERROR. More...

#define	S_UNDEF 0
	Undefined state, used after a `key_state` is cleaned up. More...

#define	S_INITIAL 1
	Initial `key_state` state after initialization by `key_state_init()` before start of three-way handshake. More...

#define	S_PRE_START 2
	Waiting for the remote OpenVPN peer to acknowledge during the initial three-way handshake. More...

#define	S_START 3
	Three-way handshake is complete, start of key exchange. More...

#define	S_SENT_KEY 4
	Local OpenVPN process has sent its part of the key material. More...

#define	S_GOT_KEY 5
	Local OpenVPN process has received the remote's part of the key material. More...

#define	S_ACTIVE 6
	Operational `key_state` state immediately after negotiation has completed while still within the handshake window. More...

#define	S_GENERATED_KEYS 7
	The data channel keys have been generated The TLS session is fully authenticated when reaching this state. More...

Index of key_state objects within a tls_session structure
This is the index of `tls_session.key`
#define	KS_PRIMARY 0
	Primary key state index. More...

#define	KS_LAME_DUCK 1
	Key state index that will retire soon. More...

#define	KS_SIZE 2
	Size of the `tls_session.key` array. More...

Index of tls_session objects within a tls_multi structure
This is the index of `tls_multi.session` Normally three tls_session objects are maintained by an active openvpn session. The first is the current, TLS authenticated session, the second is used to process connection requests from a new client that would usurp the current session if successfully authenticated, and the third is used as a repository for a "lame-duck" key in the event that the primary session resets due to error while the lame-duck key still has time left before its expiration. Lame duck keys are used to maintain the continuity of the data channel connection while a new key is being negotiated.
#define	TM_ACTIVE 0
	Active `tls_session`. More...

#define	TM_INITIAL 1
	As yet un-trusted `tls_session` being negotiated. More...

#define	TM_LAME_DUCK 2
	Old `tls_session`. More...

#define	TM_SIZE 3
	Size of the `tls_multi.session` array. More...

Enumerations
enum	ks_auth_state { KS_AUTH_FALSE, KS_AUTH_DEFERRED, KS_AUTH_TRUE }
	This reflects the (server side) authentication state after the TLS session has been established and key_method_2_read is called. More...

enum	auth_deferred_result { ACF_PENDING, ACF_SUCCEEDED, ACF_DISABLED, ACF_FAILED }

enum	dco_key_status { DCO_NOT_INSTALLED, DCO_INSTALLED_PRIMARY, DCO_INSTALLED_SECONDARY }

enum	multi_status { CAS_NOT_CONNECTED, CAS_WAITING_AUTH, CAS_PENDING, CAS_PENDING_DEFERRED, CAS_PENDING_DEFERRED_PARTIAL, CAS_FAILED, CAS_WAITING_OPTIONS_IMPORT, CAS_RECONNECT_PENDING, CAS_CONNECT_DONE }

Functions
static struct key_state *	get_key_scan (struct tls_multi *multi, int index)
	gets an item of `key_state` objects in the order they should be scanned by data channel modules. More...

static const struct key_state *	get_primary_key (const struct tls_multi *multi)
	gets an item of `key_state` objects in the order they should be scanned by data channel modules. More...

Macro Definition Documentation

◆ AUTH_TOKEN_EXPIRED

#define AUTH_TOKEN_EXPIRED (1<<1)

Auth-token sent from client has expired.

Definition at line 654 of file ssl_common.h.

◆ AUTH_TOKEN_HMAC_OK

#define AUTH_TOKEN_HMAC_OK (1<<0)

Auth-token sent from client has valid hmac.

Definition at line 652 of file ssl_common.h.

◆ AUTH_TOKEN_VALID_EMPTYUSER

#define AUTH_TOKEN_VALID_EMPTYUSER (1<<2)

Auth-token is only valid for an empty username and not the username actually supplied from the client.

OpenVPN 3 clients sometimes wipes or replaces the username with a username hint from their config.

Definition at line 656 of file ssl_common.h.

◆ KEY_SCAN_SIZE

#define KEY_SCAN_SIZE 3

Definition at line 549 of file ssl_common.h.

◆ SSLF_AUTH_USER_PASS_OPTIONAL

#define SSLF_AUTH_USER_PASS_OPTIONAL (1<<3)

Definition at line 410 of file ssl_common.h.

◆ SSLF_CLIENT_CERT_NOT_REQUIRED

#define SSLF_CLIENT_CERT_NOT_REQUIRED (1<<0)

Definition at line 407 of file ssl_common.h.

◆ SSLF_CLIENT_CERT_OPTIONAL

#define SSLF_CLIENT_CERT_OPTIONAL (1<<1)

Definition at line 408 of file ssl_common.h.

◆ SSLF_CRL_VERIFY_DIR

#define SSLF_CRL_VERIFY_DIR (1<<5)

Definition at line 412 of file ssl_common.h.

◆ SSLF_OPT_VERIFY

#define SSLF_OPT_VERIFY (1<<4)

Definition at line 411 of file ssl_common.h.

◆ SSLF_TLS_DEBUG_ENABLED

#define SSLF_TLS_DEBUG_ENABLED (1<<14)

Definition at line 417 of file ssl_common.h.

◆ SSLF_TLS_VERSION_MAX_MASK

#define SSLF_TLS_VERSION_MAX_MASK 0xF /* (uses bit positions 10 to 13) */

Definition at line 416 of file ssl_common.h.

◆ SSLF_TLS_VERSION_MAX_SHIFT

#define SSLF_TLS_VERSION_MAX_SHIFT 10

Definition at line 415 of file ssl_common.h.

◆ SSLF_TLS_VERSION_MIN_MASK

#define SSLF_TLS_VERSION_MIN_MASK 0xF /* (uses bit positions 6 to 9) */

Definition at line 414 of file ssl_common.h.

◆ SSLF_TLS_VERSION_MIN_SHIFT

#define SSLF_TLS_VERSION_MIN_SHIFT 6

Definition at line 413 of file ssl_common.h.

◆ SSLF_USERNAME_AS_COMMON_NAME

#define SSLF_USERNAME_AS_COMMON_NAME (1<<2)

Definition at line 409 of file ssl_common.h.

◆ UP_TYPE_AUTH

#define UP_TYPE_AUTH "Auth"

Definition at line 41 of file ssl_common.h.

◆ UP_TYPE_PRIVATE_KEY

#define UP_TYPE_PRIVATE_KEY "Private Key"

Definition at line 42 of file ssl_common.h.

Enumeration Type Documentation

◆ auth_deferred_result

enum auth_deferred_result

Enumerator
ACF_PENDING	deferred auth still pending
ACF_SUCCEEDED	deferred auth has suceeded
ACF_DISABLED	deferred auth is not used
ACF_FAILED	deferred auth has failed

Definition at line 167 of file ssl_common.h.

◆ dco_key_status

enum dco_key_status

Enumerator
DCO_NOT_INSTALLED
DCO_INSTALLED_PRIMARY
DCO_INSTALLED_SECONDARY

Definition at line 174 of file ssl_common.h.

◆ ks_auth_state

enum ks_auth_state

This reflects the (server side) authentication state after the TLS session has been established and key_method_2_read is called.

If async auth is enabled the state will first move to KS_AUTH_DEFERRED before eventually being set to KS_AUTH_TRUE or KS_AUTH_FALSE Only KS_AUTH_TRUE is fully authenticated

Enumerator

KS_AUTH_FALSE

Key state is not authenticated

KS_AUTH_DEFERRED

Key state authentication is being deferred, by async auth.

KS_AUTH_TRUE

Key state is authenticated.

TLS and user/pass succeeded. This includes AUTH_PENDING/OOB authentication as those hold the connection artificially in KS_AUTH_DEFERRED

Definition at line 146 of file ssl_common.h.

◆ multi_status

enum multi_status

Enumerator
CAS_NOT_CONNECTED
CAS_WAITING_AUTH	Initial TLS connection established but deferred auth is not yet finished.
CAS_PENDING	Options import (Connect script/plugin, ccd,...)
CAS_PENDING_DEFERRED	Waiting on an async option import handler.
CAS_PENDING_DEFERRED_PARTIAL	at least handler succeeded but another is still pending
CAS_FAILED	Option import failed or explicitly denied the client.
CAS_WAITING_OPTIONS_IMPORT	client with pull or p2p waiting for first time options import
CAS_RECONNECT_PENDING	session has already successful established (CAS_CONNECT_DONE) but has a reconnect and needs to redo some initialisation, this state is similar CAS_WAITING_OPTIONS_IMPORT but skips a few things. The normal connection skips this step.
CAS_CONNECT_DONE

Definition at line 561 of file ssl_common.h.

Function Documentation

◆ get_key_scan()

static struct key_state* get_key_scan	(	struct tls_multi *	multi,
		int	index
	)

inlinestatic

gets an item of key_state objects in the order they should be scanned by data channel modules.

Definition at line 699 of file ssl_common.h.

References ASSERT, tls_session::key, KS_LAME_DUCK, KS_PRIMARY, tls_multi::session, TM_ACTIVE, and TM_LAME_DUCK.

Referenced by handle_data_channel_packet(), print_key_id(), print_key_id_not_found_reason(), tls_authenticate_key(), tls_authentication_status(), tls_multi_process(), tls_rec_payload(), and tls_select_encryption_key().

◆ get_primary_key()

static const struct key_state* get_primary_key ( const struct tls_multi * multi )