OpenVPN
Data Structures | Macros | Enumerations | Functions
ssl_common.h File Reference
#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:

  1. S_INITIAL, ready to begin three-way handshake and control channel negotiation.
  2. S_PRE_START, have started three-way handshake, waiting for acknowledgment from remote.
  3. S_START, initial three-way handshake complete.
  4. S_SENT_KEY, have sent local part of key_source2 random material.
  5. S_GOT_KEY, have received remote part of key_source2 random material.
  6. S_ACTIVE, control channel successfully established
  7. 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   -1
 Error state. 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_stateget_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_stateget_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 651 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 649 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 653 of file ssl_common.h.

◆ KEY_SCAN_SIZE

#define KEY_SCAN_SIZE   3

Definition at line 546 of file ssl_common.h.

◆ SSLF_AUTH_USER_PASS_OPTIONAL

#define SSLF_AUTH_USER_PASS_OPTIONAL   (1<<3)

Definition at line 407 of file ssl_common.h.

◆ SSLF_CLIENT_CERT_NOT_REQUIRED

#define SSLF_CLIENT_CERT_NOT_REQUIRED   (1<<0)

Definition at line 404 of file ssl_common.h.

◆ SSLF_CLIENT_CERT_OPTIONAL

#define SSLF_CLIENT_CERT_OPTIONAL   (1<<1)

Definition at line 405 of file ssl_common.h.

◆ SSLF_CRL_VERIFY_DIR

#define SSLF_CRL_VERIFY_DIR   (1<<5)

Definition at line 409 of file ssl_common.h.

◆ SSLF_OPT_VERIFY

#define SSLF_OPT_VERIFY   (1<<4)

Definition at line 408 of file ssl_common.h.

◆ SSLF_TLS_DEBUG_ENABLED

#define SSLF_TLS_DEBUG_ENABLED   (1<<14)

Definition at line 414 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 413 of file ssl_common.h.

◆ SSLF_TLS_VERSION_MAX_SHIFT

#define SSLF_TLS_VERSION_MAX_SHIFT   10

Definition at line 412 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 411 of file ssl_common.h.

◆ SSLF_TLS_VERSION_MIN_SHIFT

#define SSLF_TLS_VERSION_MIN_SHIFT   6

Definition at line 410 of file ssl_common.h.

◆ SSLF_USERNAME_AS_COMMON_NAME

#define SSLF_USERNAME_AS_COMMON_NAME   (1<<2)

Definition at line 406 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

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 164 of file ssl_common.h.

◆ dco_key_status

Enumerator
DCO_NOT_INSTALLED 
DCO_INSTALLED_PRIMARY 
DCO_INSTALLED_SECONDARY 

Definition at line 171 of file ssl_common.h.

◆ 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 143 of file ssl_common.h.

◆ 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 558 of file ssl_common.h.

Function Documentation

◆ get_key_scan()

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

◆ get_primary_key()

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