ssl_verify.h File Reference

Control Channel Verification Module. More...

#include "syshead.h"
#include "misc.h"
#include "ssl_common.h"
#include "ssl_verify_openssl.h"
#include "ssl_verify_backend.h"

Include dependency graph for ssl_verify.h:

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

Go to the source code of this file.

Data Structures
struct	cert_hash
	Structure containing the hash for a single certificate. More...
struct	cert_hash_set
	Structure containing the hashes for a full certificate chain. More...
struct	x509_track

Macros
#define	MAX_CERT_DEPTH   16
	Maximum certificate depth we will allow.
#define	TLS_USERNAME_LEN   64
	Maximum length of common name.
#define	VERIFY_X509_NONE   0
#define	VERIFY_X509_SUBJECT_DN   1
#define	VERIFY_X509_SUBJECT_RDN   2
#define	VERIFY_X509_SUBJECT_RDN_PREFIX   3
#define	TLS_AUTHENTICATED(multi, ks)   ((ks)->state >= (S_GOT_KEY - (multi)->opt.server))
	Check whether the ks key_state has finished the key exchange part of the OpenVPN hand shake.
#define	XT_FULL_CHAIN   (1<<0)
#define	NS_CERT_CHECK_NONE   (0)
	Do not perform Netscape certificate type verification.
#define	NS_CERT_CHECK_SERVER   (1<<0)
	Do not perform Netscape certificate type verification.
#define	NS_CERT_CHECK_CLIENT   (1<<1)
	Do not perform Netscape certificate type verification.
#define	OPENVPN_KU_REQUIRED   (0xFFFF)
	Require keyUsage to be present in cert (0xFFFF is an invalid KU value)

Enumerations
enum	tls_auth_status { TLS_AUTHENTICATION_SUCCEEDED =0 , TLS_AUTHENTICATION_FAILED =1 , TLS_AUTHENTICATION_DEFERRED =2 }

Functions
enum tls_auth_status	tls_authentication_status (struct tls_multi *multi)
	Return current session authentication state of the tls_multi structure This will return TLS_AUTHENTICATION_SUCCEEDED only if the session is fully authenticated, i.e.
void	key_state_rm_auth_control_files (struct auth_deferred_status *ads)
	Remove the given key state's auth deferred status auth control file, if it exists.
void	cert_hash_free (struct cert_hash_set *chs)
	Frees the given set of certificate hashes.
void	tls_lock_cert_hash_set (struct tls_multi *multi)
	Locks the certificate hash set used in the given tunnel.
void	tls_lock_common_name (struct tls_multi *multi)
	Locks the common name field for the given tunnel.
const char *	tls_common_name (const struct tls_multi *multi, const bool null)
	Returns the common name field for the given tunnel.
void	set_common_name (struct tls_session *session, const char *common_name)
	Sets the common name field for the given tunnel.
const char *	tls_username (const struct tls_multi *multi, const bool null)
	Returns the username field for the given tunnel.
bool	cert_hash_compare (const struct cert_hash_set *chs1, const struct cert_hash_set *chs2)
	Compares certificates hashes, returns true if hashes are equal.
void	verify_user_pass (struct user_pass *up, struct tls_multi *multi, struct tls_session *session)
	Verify the given username and password, using either an external script, a plugin, or the management interface.
bool	ssl_verify_username_length (struct tls_session *session, const char *username)
	Checks if the username length is valid to use.
void	verify_crresponse_script (struct tls_multi *multi, const char *cr_response)
	Runs the –client-crresponse script if one is defined.
void	verify_crresponse_plugin (struct tls_multi *multi, const char *cr_response)
	Call the plugin OPENVPN_PLUGIN_CLIENT_CRRESPONSE.
void	verify_final_auth_checks (struct tls_multi *multi, struct tls_session *session)
	Perform final authentication checks, including locking of the cn, the allowed certificate hashes, and whether a client config entry exists in the client config directory.
bool	tls_authenticate_key (struct tls_multi *multi, const unsigned int mda_key_id, const bool auth, const char *client_reason)
void	auth_set_client_reason (struct tls_multi *multi, const char *client_reason)
	Sets the reason why authentication of a client failed.
static const char *	tls_client_reason (struct tls_multi *multi)
void	tls_x509_clear_env (struct env_set *es)
	Remove any X509_ env variables from env_set es.

Detailed Description

Control Channel Verification Module.

Definition in file ssl_verify.h.

Macro Definition Documentation

MAX_CERT_DEPTH

#define MAX_CERT_DEPTH   16

Maximum certificate depth we will allow.

Definition at line 52 of file ssl_verify.h.

NS_CERT_CHECK_CLIENT

#define NS_CERT_CHECK_CLIENT   (1<<1)

Do not perform Netscape certificate type verification.

Definition at line 259 of file ssl_verify.h.

NS_CERT_CHECK_NONE

#define NS_CERT_CHECK_NONE   (0)

Do not perform Netscape certificate type verification.

Definition at line 255 of file ssl_verify.h.

NS_CERT_CHECK_SERVER

#define NS_CERT_CHECK_SERVER   (1<<0)

Do not perform Netscape certificate type verification.

Definition at line 257 of file ssl_verify.h.

OPENVPN_KU_REQUIRED

#define OPENVPN_KU_REQUIRED   (0xFFFF)

Require keyUsage to be present in cert (0xFFFF is an invalid KU value)

Definition at line 262 of file ssl_verify.h.

TLS_USERNAME_LEN

#define TLS_USERNAME_LEN   64

Maximum length of common name.

Definition at line 55 of file ssl_verify.h.

VERIFY_X509_NONE

#define VERIFY_X509_NONE   0

Definition at line 67 of file ssl_verify.h.

VERIFY_X509_SUBJECT_DN

#define VERIFY_X509_SUBJECT_DN   1

Definition at line 68 of file ssl_verify.h.

VERIFY_X509_SUBJECT_RDN

#define VERIFY_X509_SUBJECT_RDN   2

Definition at line 69 of file ssl_verify.h.

VERIFY_X509_SUBJECT_RDN_PREFIX

#define VERIFY_X509_SUBJECT_RDN_PREFIX   3

Definition at line 70 of file ssl_verify.h.

XT_FULL_CHAIN

#define XT_FULL_CHAIN   (1<<0)

Definition at line 246 of file ssl_verify.h.

Enumeration Type Documentation

tls_auth_status

enum tls_auth_status

Enumerator
TLS_AUTHENTICATION_SUCCEEDED
TLS_AUTHENTICATION_FAILED
TLS_AUTHENTICATION_DEFERRED

Definition at line 72 of file ssl_verify.h.

Function Documentation

auth_set_client_reason()

void auth_set_client_reason	(	struct tls_multi *	multi,
		const char *	client_reason
	)

Sets the reason why authentication of a client failed.

This be will send to the client when the AUTH_FAILED message is sent An example would be "SESSION: Token expired"

Parameters

multi	The multi tls struct
client_reason	The string to send to the client as part of AUTH_FAILED

Definition at line 805 of file ssl_verify.c.

References tls_multi::client_reason, and string_alloc().

Referenced by check_for_client_reason(), key_method_2_read(), key_state_check_auth_pending_file(), multi_client_set_protocol_options(), tls_authenticate_key(), tls_authentication_status(), tls_multi_free(), and verify_auth_token().

cert_hash_compare()

bool cert_hash_compare	(	const struct cert_hash_set *	chs1,
		const struct cert_hash_set *	chs2
	)

Compares certificates hashes, returns true if hashes are equal.

Parameters

chs1	cert 1 hash set
chs2	cert 2 hash set

Definition at line 229 of file ssl_verify.c.

References cert_hash_set::ch, MAX_CERT_DEPTH, and cert_hash::sha256_hash.

Referenced by multi_process_float(), and verify_final_auth_checks().

cert_hash_free()

void cert_hash_free

(

struct cert_hash_set *

chs

)

Frees the given set of certificate hashes.

Parameters

chs	The certificate hash set to free.

Definition at line 215 of file ssl_verify.c.

References cert_hash_set::ch, and MAX_CERT_DEPTH.

Referenced by tls_multi_free(), and tls_session_free().

key_state_rm_auth_control_files()

void key_state_rm_auth_control_files

(

struct auth_deferred_status *

ads

)

Remove the given key state's auth deferred status auth control file, if it exists.

Parameters

ads	The key state the remove the file for

Remove the given key state's auth deferred status auth control file, if it exists.

Definition at line 955 of file ssl_verify.c.

References key_state_rm_auth_pending_file(), buffer::len, and platform_unlink().

Referenced by key_state_free(), key_state_gen_auth_control_files(), verify_user_pass_plugin(), and verify_user_pass_script().

set_common_name()

void set_common_name	(	struct tls_session *	session,
		const char *	common_name
	)

Sets the common name field for the given tunnel.

Parameters

session	The session to set the common name for
common_name	The name to set the common name to

Definition at line 86 of file ssl_verify.c.

References setenv_str(), and string_alloc().

Referenced by override_locked_username(), verify_cert(), verify_final_auth_checks(), and verify_user_pass().

ssl_verify_username_length()

bool ssl_verify_username_length	(	struct tls_session *	session,
		const char *	username
	)

Checks if the username length is valid to use.

This checks when username-as-common-name is active if the username is shorter than the maximum TLS common name length (64).

It will also display an error message if the name is too long

Parameters

session	current TLS session
username	username to check

Returns

true if name is under limit or username-as-common-name is not active

Definition at line 1572 of file ssl_verify.c.

References D_TLS_ERRORS, msg, SSLF_USERNAME_AS_COMMON_NAME, and TLS_USERNAME_LEN.

Referenced by override_locked_username(), and verify_user_pass().

tls_authenticate_key()

bool tls_authenticate_key	(	struct tls_multi *	multi,
		const unsigned int	mda_key_id,
		const bool	auth,
		const char *	client_reason
	)

Definition at line 1238 of file ssl_verify.c.

References ACF_FAILED, ACF_SUCCEEDED, auth_set_client_reason(), get_key_scan(), KEY_SCAN_SIZE, key_state::mda_key_id, and key_state::mda_status.

Referenced by management_client_auth().

tls_authentication_status()

enum tls_auth_status tls_authentication_status

(

struct tls_multi *

multi

)

Return current session authentication state of the tls_multi structure This will return TLS_AUTHENTICATION_SUCCEEDED only if the session is fully authenticated, i.e.

VPN traffic is allowed over it.

Checks the status of all active keys and checks if the deferred authentication has succeeded.

As a side effect this function will also transition ks->authenticated from KS_AUTH_DEFERRED to KS_AUTH_FALSE/KS_AUTH_TRUE if the deferred authentication has succeeded after last call.

Parameters

multi

the tls_multi struct to operate on

Returns

Current authentication status of the tls_multi

Definition at line 1141 of file ssl_verify.c.

References auth_set_client_reason(), key_state::authenticated, D_TLS_ERRORS, dmsg, gc, gc_free(), gc_new(), get_key_scan(), get_primary_key(), KEY_SCAN_SIZE, key_state_check_auth_failed_message_file(), KS_AUTH_DEFERRED, KS_AUTH_FALSE, KS_AUTH_TRUE, buffer::len, now, key_state::plugin_auth, key_state::script_auth, tls_multi::tas_cache_last_update, tls_multi::tas_cache_num_updates, TLS_AUTHENTICATED, TLS_AUTHENTICATION_DEFERRED, TLS_AUTHENTICATION_FAILED, tls_authentication_status_use_cache(), TLS_AUTHENTICATION_SUCCEEDED, and update_key_auth_status().

Referenced by process_incoming_push_request(), and tls_multi_process().

tls_client_reason()

static const char * tls_client_reason ( struct tls_multi *  multi )

inlinestatic

Definition at line 282 of file ssl_verify.h.

References tls_multi::client_reason.

Referenced by process_incoming_push_request().

tls_common_name()

const char * tls_common_name	(	const struct tls_multi *	multi,
		const bool	null
	)

Returns the common name field for the given tunnel.

Parameters

multi	The tunnel to return the common name for
null	Whether null may be returned. If not, "UNDEF" will be returned.

Definition at line 108 of file ssl_verify.c.

References tls_session::common_name, tls_multi::session, and TM_ACTIVE.

Referenced by format_common_name(), learn_address_script(), management_callback_kill_by_cn(), multi_client_connect_setenv(), multi_delete_dup(), multi_instance_string(), multi_print_status(), multi_process_float(), and multi_select_virtual_addr().

tls_lock_cert_hash_set()

void tls_lock_cert_hash_set

(

struct tls_multi *

multi

)

Locks the certificate hash set used in the given tunnel.

Parameters

multi

The tunnel to lock

Definition at line 287 of file ssl_verify.c.

References cert_hash_copy(), tls_session::cert_hash_set, tls_multi::locked_cert_hash_set, tls_multi::session, and TM_ACTIVE.

Referenced by multi_client_connect_early_setup().

tls_lock_common_name()

void tls_lock_common_name

(

struct tls_multi *

multi

)

Locks the common name field for the given tunnel.

Parameters

multi

The tunnel to lock

Definition at line 133 of file ssl_verify.c.

References tls_session::common_name, tls_multi::locked_cn, tls_multi::session, string_alloc(), and TM_ACTIVE.

Referenced by multi_client_connect_early_setup(), and override_locked_username().

tls_username()

const char * tls_username	(	const struct tls_multi *	multi,
		const bool	null
	)

Returns the username field for the given tunnel.

Parameters

multi	The tunnel to return the username for
null	Whether null may be returned. If not, "UNDEF" will be returned.

Definition at line 172 of file ssl_verify.c.

References tls_multi::locked_username.

Referenced by multi_print_status().

tls_x509_clear_env()

void tls_x509_clear_env

(

struct env_set *

es

)

Remove any X509_ env variables from env_set es.

Definition at line 1850 of file ssl_verify.c.

References env_set_del(), es, env_set::list, env_item::next, and env_item::string.

Referenced by tls_process_state().

verify_crresponse_plugin()

void verify_crresponse_plugin	(	struct tls_multi *	multi,
		const char *	cr_response
	)

Call the plugin OPENVPN_PLUGIN_CLIENT_CRRESPONSE.

As with the management interface calling the plugin is stateless in the sense that it does not directly participate in the authentication but rather should set the files for the deferred auth like the management commands.

Definition at line 1394 of file ssl_verify.c.

References plugin_call(), tls_multi::session, setenv_del(), setenv_str(), and TM_ACTIVE.

Referenced by receive_cr_response().

verify_crresponse_script()

void verify_crresponse_script	(	struct tls_multi *	multi,
		const char *	cr_response
	)

Runs the –client-crresponse script if one is defined.

As with the management interface the script is stateless in the sense that it does not directly participate in the authentication but rather should set the files for the deferred auth like the management commands.

Definition at line 1407 of file ssl_verify.c.

References argv_free(), argv_new(), argv_parse_cmd(), argv_printf_cat(), D_TLS_ERRORS, gc, gc_free(), gc_new(), msg, openvpn_run_script(), platform_create_temp_file(), tls_multi::session, setenv_str(), status_close(), status_open(), STATUS_OUTPUT_WRITE, status_printf(), tls_deauthenticate(), and TM_ACTIVE.

Referenced by receive_cr_response().

verify_final_auth_checks()

void verify_final_auth_checks	(	struct tls_multi *	multi,
		struct tls_session *	session
	)

Perform final authentication checks, including locking of the cn, the allowed certificate hashes, and whether a client config entry exists in the client config directory.

Parameters

multi	The TLS multi structure to verify locked structures.
session	The current TLS session

Definition at line 1788 of file ssl_verify.c.

References key_state::authenticated, CCD_DEFAULT, cert_hash_compare(), D_TLS_ERRORS, gc, gc_free(), gc_new(), session::key, KS_AUTH_FALSE, KS_PRIMARY, tls_multi::locked_cert_hash_set, tls_multi::locked_cn, msg, platform_gen_path(), platform_test_file(), set_common_name(), tls_deauthenticate(), and wipe_auth_token().

Referenced by key_method_2_read().

verify_user_pass()

void verify_user_pass	(	struct user_pass *	up,
		struct tls_multi *	multi,
		struct tls_session *	session
	)

Verify the given username and password, using either an external script, a plugin, or the management interface.

If authentication succeeds, the appropriate state is filled into the session's primary key state's authenticated field. Authentication may also be deferred, in which case the key state's auth_deferred field is filled in.

Parameters

up	The username and password to verify.
multi	The TLS multi structure to verify usernames against.
session	The current TLS session

Verify the given username and password, using either an external script, a plugin, or the management interface.

Will set session->ks[KS_PRIMARY].authenticated according to result of the username/password verification

Definition at line 1596 of file ssl_verify.c.

References ACF_DISABLED, ASSERT, tls_multi::auth_token, AUTH_TOKEN_EXPIRED, AUTH_TOKEN_HMAC_OK, tls_multi::auth_token_initial, key_state::auth_token_state_flags, key_state::authenticated, CC_CRLF, CC_PRINT, D_HANDSHAKE, D_MULTI_LOW, D_TLS_ERRORS, ENABLE_MANAGEMENT, generate_auth_token(), is_auth_token(), session::key, KMDA_DEF, KMDA_ERROR, KMDA_UNDEF, KS_AUTH_DEFERRED, KS_AUTH_FALSE, KS_AUTH_TRUE, KS_PRIMARY, tls_multi::locked_original_username, tls_multi::locked_username, M_WARN, management_enable_def_auth(), key_state::mda_status, msg, OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY, OPENVPN_PLUGIN_FUNC_DEFERRED, OPENVPN_PLUGIN_FUNC_ERROR, OPENVPN_PLUGIN_FUNC_SUCCESS, user_pass::password, plugin_defined(), user_pass::protected, set_common_name(), set_verify_user_pass_env(), ssl_verify_username_length(), SSLF_USERNAME_AS_COMMON_NAME, string_mod(), string_mod_remap_name(), tls_lock_username(), user_pass::username, verify_auth_token(), verify_user_pass_management(), verify_user_pass_plugin(), verify_user_pass_script(), and wipe_auth_token().

Referenced by key_method_2_read().