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_UNTRUSTED   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  multi_status {
  CAS_NOT_CONNECTED, CAS_WAITING_AUTH, CAS_PENDING, CAS_PENDING_DEFERRED,
  CAS_PENDING_DEFERRED_PARTIAL, CAS_FAILED, CAS_WAITING_OPTIONS_IMPORT, 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 630 of file ssl_common.h.

Referenced by add_session_token_env(), auth_token_test_empty_user(), auth_token_test_env(), auth_token_test_timeout(), verify_auth_token(), and verify_user_pass().

◆ AUTH_TOKEN_HMAC_OK

#define AUTH_TOKEN_HMAC_OK   (1<<0)

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

Referenced by add_session_token_env(), auth_token_test_empty_user(), auth_token_test_env(), generate_auth_token(), and verify_auth_token().

◆ KEY_SCAN_SIZE

#define KEY_SCAN_SIZE   3

◆ SSLF_AUTH_USER_PASS_OPTIONAL

#define SSLF_AUTH_USER_PASS_OPTIONAL   (1<<3)

◆ SSLF_CLIENT_CERT_NOT_REQUIRED

#define SSLF_CLIENT_CERT_NOT_REQUIRED   (1<<0)

Definition at line 391 of file ssl_common.h.

Referenced by add_option(), options_postprocess_verify_ce(), and tls_ctx_set_options().

◆ SSLF_CLIENT_CERT_OPTIONAL

#define SSLF_CLIENT_CERT_OPTIONAL   (1<<1)

Definition at line 392 of file ssl_common.h.

Referenced by add_option(), options_postprocess_verify_ce(), and tls_ctx_set_options().

◆ SSLF_CRL_VERIFY_DIR

#define SSLF_CRL_VERIFY_DIR   (1<<5)

◆ SSLF_OPT_VERIFY

#define SSLF_OPT_VERIFY   (1<<4)

Definition at line 395 of file ssl_common.h.

Referenced by add_option(), key_method_2_read(), and options_postprocess_verify_ce().

◆ SSLF_TLS_DEBUG_ENABLED

#define SSLF_TLS_DEBUG_ENABLED   (1<<14)

Definition at line 401 of file ssl_common.h.

Referenced by add_option().

◆ SSLF_TLS_VERSION_MAX_MASK

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

◆ SSLF_TLS_VERSION_MAX_SHIFT

#define SSLF_TLS_VERSION_MAX_SHIFT   10

◆ SSLF_TLS_VERSION_MIN_MASK

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

◆ SSLF_TLS_VERSION_MIN_SHIFT

#define SSLF_TLS_VERSION_MIN_SHIFT   6

◆ SSLF_USERNAME_AS_COMMON_NAME

#define SSLF_USERNAME_AS_COMMON_NAME   (1<<2)

Definition at line 393 of file ssl_common.h.

Referenced by add_option(), options_postprocess_verify_ce(), and verify_user_pass().

◆ UP_TYPE_AUTH

#define UP_TYPE_AUTH   "Auth"

Definition at line 41 of file ssl_common.h.

Referenced by auth_user_pass_setup(), and receive_auth_failed().

◆ UP_TYPE_PRIVATE_KEY

#define UP_TYPE_PRIVATE_KEY   "Private Key"

Definition at line 42 of file ssl_common.h.

Referenced by pem_password_setup(), tls_ctx_load_pkcs12(), and tls_ctx_load_priv_file().

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

◆ multi_status

Enumerator
CAS_NOT_CONNECTED 
CAS_WAITING_AUTH 

TLS connection established but deferred auth not finished.

CAS_PENDING 
CAS_PENDING_DEFERRED 
CAS_PENDING_DEFERRED_PARTIAL 

at least handler succeeded, no result yet

CAS_FAILED 
CAS_WAITING_OPTIONS_IMPORT 

client with pull or p2p waiting for first time options import

CAS_CONNECT_DONE 

Definition at line 541 of file ssl_common.h.

Function Documentation

◆ get_key_scan()

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

◆ get_primary_key()

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

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

Definition at line 681 of file ssl_common.h.

Referenced by multi_client_set_protocol_options(), receive_auth_pending(), receive_cr_response(), send_push_request(), tls_pre_decrypt(), and tls_test_payload_len().