OpenVPN
Macros | Functions
auth_token.h File Reference
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros

#define SESSION_ID_PREFIX   "SESS_ID_AT_"
 The prefix given to auth tokens start with, this prefix is special cased to not show up in log files in OpenVPN 2 and 3. More...
 

Functions

void generate_auth_token (const struct user_pass *up, struct tls_multi *multi)
 Generate an auth token based on username and timestamp. More...
 
unsigned verify_auth_token (struct user_pass *up, struct tls_multi *multi, struct tls_session *session)
 Verifies the auth token to be in the format that generate_auth_token create and checks if the token is valid. More...
 
void auth_token_init_secret (struct key_ctx *key_ctx, const char *key_file, bool key_inline)
 Loads an HMAC secret from a file or if no file is present generates a epheremal secret for the run time of the server and stores it into ctx. More...
 
void auth_token_write_server_key_file (const char *filename)
 Generate a auth-token server secret key, and write to file. More...
 
void add_session_token_env (struct tls_session *session, struct tls_multi *multi, const struct user_pass *up)
 Put the session id, and auth token status into the environment if auth-token is enabled. More...
 
void wipe_auth_token (struct tls_multi *multi)
 Wipes the authentication token out of the memory, frees and cleans up related buffers and flags. More...
 
static bool is_auth_token (const char *password)
 Return if the password string has the format of a password. More...
 

Macro Definition Documentation

◆ SESSION_ID_PREFIX

#define SESSION_ID_PREFIX   "SESS_ID_AT_"

The prefix given to auth tokens start with, this prefix is special cased to not show up in log files in OpenVPN 2 and 3.

We also prefix this with AT to only act on auth token generated by us.

Definition at line 115 of file auth_token.h.

Referenced by add_session_token_env(), generate_auth_token(), is_auth_token(), verify_auth_token(), and zerohmac().

Function Documentation

◆ add_session_token_env()

void add_session_token_env ( struct tls_session session,
struct tls_multi multi,
const struct user_pass up 
)

◆ auth_token_init_secret()

void auth_token_init_secret ( struct key_ctx key_ctx,
const char *  key_file,
bool  key_inline 
)

Loads an HMAC secret from a file or if no file is present generates a epheremal secret for the run time of the server and stores it into ctx.

Definition at line 137 of file auth_token.c.

References alloc_buf(), auth_token_kt(), auth_token_pem_name, buf_read(), free_buf(), generate_ephemeral_key(), init_key_ctx(), M_FATAL, msg, and read_pem_key_file().

Referenced by auth_token_test_key_load(), auth_token_test_random_keys(), and do_init_auth_token_key().

◆ auth_token_write_server_key_file()

void auth_token_write_server_key_file ( const char *  filename)

Generate a auth-token server secret key, and write to file.

Parameters
filenameFilename of the server key file to create.

Definition at line 131 of file auth_token.c.

References auth_token_pem_name, and write_pem_key_file().

Referenced by do_genkey().

◆ generate_auth_token()

void generate_auth_token ( const struct user_pass up,
struct tls_multi multi 
)

Generate an auth token based on username and timestamp.

The idea of auth token is to be stateless, so that we can verify use it even after we have forgotten about it or server has been restarted.

To achieve this even though we cannot trust the client we use HMAC to be able to verify the information.

Format of the auth-token (before base64 encode)

session id(12 bytes)|uint64 timestamp (8 bytes)| uint64 timestamp (8 bytes)|sha256-hmac(32 bytes)

The first timestamp is the time the token was initially created and is used to determine the maximum renewable time of the token. We always include this even if tokens do not expire (this value is not used) to keep the code cleaner.

The second timestamp is the time the token was renewed/regenerated and is used to determine if this token has been renewed in the acceptable time range (2 * renogiation timeout)

The session id is a random string of 12 byte (or 16 in base64) that is not used by OpenVPN itself but kept intact so that external logging/managment can track the session multiple reconnects/servers. It is delibrately chosen be a multiple of 3 bytes to have a base64 encoding without padding.

The hmac is calculated over the username contactinated with the raw auth-token bytes to include authentication of the username in the token

We encode the auth-token with base64 and then prepend "SESS_ID_" before sending it to the client.

This function will free() an existing multi->auth_token and keep the existing initial timestamp and session id contained in that token.

Definition at line 174 of file auth_token.c.

References alloc_buf_gc(), ASSERT, tls_multi::auth_token, tls_options::auth_token_key, AUTH_TOKEN_SESSION_ID_LEN, tls_multi::auth_token_state_flags, AUTH_TOKEN_VALID_EMPTYUSER, BLEN, BPTR, buf_write(), buf_write_u8(), D_SHOW_KEYS, dmsg, free, gc_free(), gc_new(), key_ctx::hmac, hmac_ctx_final(), hmac_ctx_reset(), hmac_ctx_size(), hmac_ctx_update(), htonll, M_FATAL, msg, now, openvpn_base64_decode(), openvpn_base64_encode(), tls_multi::opt, rand_bytes(), SESSION_ID_PREFIX, and user_pass::username.

Referenced by add_session_token_env(), auth_token_basic_test(), auth_token_fail_invalid_key(), auth_token_test_empty_user(), auth_token_test_known_keys(), auth_token_test_random_keys(), auth_token_test_timeout(), and verify_user_pass().

◆ is_auth_token()

static bool is_auth_token ( const char *  password)
inlinestatic

Return if the password string has the format of a password.

This fuction will always read as many bytes as SESSION_ID_PREFIX is longer the caller needs ensure that password memory is at least that long (true for calling with struct user_pass)

Parameters
password
Returns
whether the password string starts with the session token prefix

Definition at line 127 of file auth_token.h.

References memcmp_constant_time(), and SESSION_ID_PREFIX.

Referenced by add_session_token_env(), and verify_user_pass().

◆ verify_auth_token()

unsigned verify_auth_token ( struct user_pass up,
struct tls_multi multi,
struct tls_session session 
)

◆ wipe_auth_token()

void wipe_auth_token ( struct tls_multi multi)

Wipes the authentication token out of the memory, frees and cleans up related buffers and flags.

Parameters
multiPointer to a multi object holding the auth_token variables

Definition at line 390 of file auth_token.c.

References tls_multi::auth_token, tls_multi::auth_token_initial, free, and secure_memzero().

Referenced by teardown(), tls_deauthenticate(), tls_multi_free(), verify_final_auth_checks(), and verify_user_pass().