2
* OpenVPN -- An application to securely tunnel IP networks
3
* over a single TCP/UDP port, with support for SSL/TLS-based
4
* session authentication and key exchange,
5
* packet encryption, packet authentication, and
8
* Copyright (C) 2002-2010 OpenVPN Technologies, Inc. <sales@openvpn.net>
9
* Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com>
11
* This program is free software; you can redistribute it and/or modify
12
* it under the terms of the GNU General Public License version 2
13
* as published by the Free Software Foundation.
15
* This program is distributed in the hope that it will be useful,
16
* but WITHOUT ANY WARRANTY; without even the implied warranty of
17
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18
* GNU General Public License for more details.
20
* You should have received a copy of the GNU General Public License
21
* along with this program (see the file COPYING included with this
22
* distribution); if not, write to the Free Software Foundation, Inc.,
23
* 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
27
* @file Control Channel Common Data Structures
33
#include "session_id.h"
35
#include "packet_id.h"
39
#include "ssl_backend.h"
42
#define UP_TYPE_AUTH "Auth"
43
#define UP_TYPE_PRIVATE_KEY "Private Key"
45
/** @addtogroup control_processor
48
* @name Control channel negotiation states
50
* These states represent the different phases of control channel
51
* negotiation between OpenVPN peers. OpenVPN servers and clients
52
* progress through the states in a different order, because of their
53
* different roles during exchange of random material. The references to
54
* the \c key_source2 structure in the list below is only valid if %key
55
* method 2 is being used. See the \link key_generation data channel key
56
* generation\endlink related page for more information.
58
* Clients follow this order:
59
* -# \c S_INITIAL, ready to begin three-way handshake and control
60
* channel negotiation.
61
* -# \c S_PRE_START, have started three-way handshake, waiting for
62
* acknowledgment from remote.
63
* -# \c S_START, initial three-way handshake complete.
64
* -# \c S_SENT_KEY, have sent local part of \c key_source2 random
66
* -# \c S_GOT_KEY, have received remote part of \c key_source2 random
68
* -# \c S_ACTIVE, normal operation during remaining handshake window.
69
* -# \c S_NORMAL_OP, normal operation.
71
* Servers follow the same order, except for \c S_SENT_KEY and \c
72
* S_GOT_KEY being reversed, because the server first receives the
73
* client's \c key_source2 random material before generating and sending
78
#define S_ERROR -1 /**< Error state. */
79
#define S_UNDEF 0 /**< Undefined state, used after a \c
80
* key_state is cleaned up. */
81
#define S_INITIAL 1 /**< Initial \c key_state state after
82
* initialization by \c key_state_init()
83
* before start of three-way handshake. */
84
#define S_PRE_START 2 /**< Waiting for the remote OpenVPN peer
85
* to acknowledge during the initial
86
* three-way handshake. */
87
#define S_START 3 /**< Three-way handshake is complete,
88
* start of key exchange. */
89
#define S_SENT_KEY 4 /**< Local OpenVPN process has sent its
90
* part of the key material. */
91
#define S_GOT_KEY 5 /**< Local OpenVPN process has received
92
* the remote's part of the key
94
#define S_ACTIVE 6 /**< Operational \c key_state state
95
* immediately after negotiation has
96
* completed while still within the
97
* handshake window. */
98
/* ready to exchange data channel packets */
99
#define S_NORMAL_OP 7 /**< Normal operational \c key_state
101
/** @} name Control channel negotiation states */
102
/** @} addtogroup control_processor */
105
* Container for one half of random material to be used in %key method 2
106
* \ref key_generation "data channel key generation".
107
* @ingroup control_processor
110
uint8_t pre_master[48]; /**< Random used for master secret
111
* generation, provided only by client
113
uint8_t random1[32]; /**< Seed used for master secret
114
* generation, provided by both client
116
uint8_t random2[32]; /**< Seed used for key expansion, provided
117
* by both client and server. */
122
* Container for both halves of random material to be used in %key method
123
* 2 \ref key_generation "data channel key generation".
124
* @ingroup control_processor
127
struct key_source client; /**< Random provided by client. */
128
struct key_source server; /**< Random provided by server. */
132
* Security parameter state of one TLS and data channel %key session.
133
* @ingroup control_processor
135
* This structure represents one security parameter session between
136
* OpenVPN peers. It includes the control channel TLS state and the data
137
* channel crypto state. It also contains the reliability layer
138
* structures used for control channel messages.
140
* A new \c key_state structure is initialized for each hard or soft
144
* - This structure should be initialized using the \c key_state_init()
146
* - This structure should be cleaned up using the \c key_state_free()
152
int key_id; /* inherited from struct tls_session below */
154
struct key_state_ssl ks_ssl; /* contains SSL object and BIOs for the control channel */
156
time_t established; /* when our state went S_ACTIVE */
157
time_t must_negotiate; /* key negotiation times out if not finished before this time */
158
time_t must_die; /* this object is destroyed at this time */
160
int initial_opcode; /* our initial P_ opcode */
161
struct session_id session_id_remote; /* peer's random session ID */
162
struct link_socket_actual remote_addr; /* peer's IP addr */
163
struct packet_id packet_id; /* for data channel, to prevent replay attacks */
165
struct key_ctx_bi key; /* data channel keys for encrypt/decrypt/hmac */
167
struct key_source2 *key_src; /* source entropy for key expansion */
169
struct buffer plaintext_read_buf;
170
struct buffer plaintext_write_buf;
171
struct buffer ack_write_buf;
173
struct reliable *send_reliable; /* holds a copy of outgoing packets until ACK received */
174
struct reliable *rec_reliable; /* order incoming ciphertext packets before we pass to TLS */
175
struct reliable_ack *rec_ack; /* buffers all packet IDs we want to ACK back to sender */
177
struct buffer_list *paybuf;
179
counter_type n_bytes; /* how many bytes sent/recvd since last key exchange */
180
counter_type n_packets; /* how many packets sent/recvd since last key exchange */
183
* If bad username/password, TLS connection will come up but 'authenticated' will be false.
186
time_t auth_deferred_expire;
188
#ifdef ENABLE_DEF_AUTH
189
/* If auth_deferred is true, authentication is being deferred */
191
#ifdef MANAGEMENT_DEF_AUTH
192
unsigned int mda_key_id;
193
unsigned int mda_status;
195
#ifdef PLUGIN_DEF_AUTH
196
unsigned int auth_control_status;
198
char *auth_control_file;
204
* Our const options, obtained directly or derived from
205
* command line options.
209
/* our master TLS context from which all SSL objects derived */
210
struct tls_root_ctx ssl_ctx;
212
/* data channel cipher, hmac, and key lengths */
213
struct key_type key_type;
215
/* true if we are a TLS server, client otherwise */
218
/* if true, don't xmit until first packet from peer is received */
222
/* local and remote options strings
223
that must match between client and server */
224
const char *local_options;
225
const char *remote_options;
228
/* from command line */
235
#ifdef ENABLE_PUSH_PEER_INFO
238
int transition_window;
239
int handshake_window;
240
interval_t packet_timeout;
241
int renegotiate_bytes;
242
int renegotiate_packets;
243
interval_t renegotiate_seconds;
245
/* cert verification parms */
246
const char *verify_command;
247
const char *verify_export_cert;
248
int verify_x509_type;
249
const char *verify_x509_name;
250
const char *crl_file;
252
unsigned remote_cert_ku[MAX_PARMS];
253
const char *remote_cert_eku;
254
uint8_t *verify_hash;
255
char *x509_username_field;
257
/* allow openvpn config info to be
258
passed over control channel */
259
bool pass_config_info;
261
/* struct crypto_option flags */
262
unsigned int crypto_flags_and;
263
unsigned int crypto_flags_or;
265
int replay_window; /* --replay-window parm */
266
int replay_time; /* --replay-window parm */
269
/* packet authentication for TLS handshake */
270
struct crypto_options tls_auth;
271
struct key_ctx_bi tls_auth_key;
273
/* frame parameters for TLS control channel */
276
/* used for username/password authentication */
277
const char *auth_user_pass_verify_script;
278
bool auth_user_pass_verify_script_via_file;
281
/* use the client-config-dir as a positive authenticator */
282
const char *client_config_dir_exclusive;
284
/* instance-wide environment variable set */
286
const struct plugin_list *plugins;
288
/* configuration file boolean options */
289
# define SSLF_CLIENT_CERT_NOT_REQUIRED (1<<0)
290
# define SSLF_USERNAME_AS_COMMON_NAME (1<<1)
291
# define SSLF_AUTH_USER_PASS_OPTIONAL (1<<2)
292
# define SSLF_OPT_VERIFY (1<<4)
293
# define SSLF_CRL_VERIFY_DIR (1<<5)
294
unsigned int ssl_flags;
296
#ifdef MANAGEMENT_DEF_AUTH
297
struct man_def_auth_context *mda_context;
300
#ifdef ENABLE_X509_TRACK
301
const struct x509_track *x509_track;
304
#ifdef ENABLE_CLIENT_CR
305
const struct static_challenge_info *sci;
312
/** @addtogroup control_processor
314
/** @name Index of key_state objects within a tls_session structure
316
* This is the index of \c tls_session.key
319
#define KS_PRIMARY 0 /**< Primary %key state index. */
320
#define KS_LAME_DUCK 1 /**< %Key state index that will retire
322
#define KS_SIZE 2 /**< Size of the \c tls_session.key array. */
323
/** @} name Index of key_state objects within a tls_session structure */
324
/** @} addtogroup control_processor */
328
* Security parameter state of a single session within a VPN tunnel.
329
* @ingroup control_processor
331
* This structure represents an OpenVPN peer-to-peer control channel
334
* A \c tls_session remains over soft resets, but a new instance is
335
* initialized for each hard reset.
338
* - This structure should be initialized using the \c tls_session_init()
340
* - This structure should be cleaned up using the \c tls_session_free()
345
/* const options and config info */
346
struct tls_options *opt;
348
/* during hard reset used to control burst retransmit */
351
/* authenticate control packets */
352
struct crypto_options tls_auth;
353
struct packet_id tls_auth_pid;
355
int initial_opcode; /* our initial P_ opcode */
356
struct session_id session_id; /* our random session ID */
357
int key_id; /* increments with each soft reset (for key renegotiation) */
359
int limit_next; /* used for traffic shaping on the control channel */
365
struct cert_hash_set *cert_hash_set;
368
uint32_t common_name_hashval;
371
bool verified; /* true if peer certificate was verified against CA */
373
/* not-yet-authenticated incoming client */
374
struct link_socket_actual untrusted_addr;
376
struct key_state key[KS_SIZE];
379
/** @addtogroup control_processor
381
/** @name Index of tls_session objects within a tls_multi structure
383
* This is the index of \c tls_multi.session
385
* Normally three tls_session objects are maintained by an active openvpn
386
* session. The first is the current, TLS authenticated session, the
387
* second is used to process connection requests from a new client that
388
* would usurp the current session if successfully authenticated, and the
389
* third is used as a repository for a "lame-duck" %key in the event that
390
* the primary session resets due to error while the lame-duck %key still
391
* has time left before its expiration. Lame duck keys are used to
392
* maintain the continuity of the data channel connection while a new %key
393
* is being negotiated.
396
#define TM_ACTIVE 0 /**< Active \c tls_session. */
397
#define TM_UNTRUSTED 1 /**< As yet un-trusted \c tls_session
398
* being negotiated. */
399
#define TM_LAME_DUCK 2 /**< Old \c tls_session. */
400
#define TM_SIZE 3 /**< Size of the \c tls_multi.session
402
/** @} name Index of tls_session objects within a tls_multi structure */
403
/** @} addtogroup control_processor */
407
* The number of keys we will scan on encrypt or decrypt. The first
408
* is the "active" key. The second is the lame_duck or retiring key
409
* associated with the active key's session ID. The third is a detached
410
* lame duck session that only occurs in situations where a key renegotiate
411
* failed on the active key, but a lame duck key was still valid. By
412
* preserving the lame duck session, we can be assured of having a data
413
* channel key available even when network conditions are so bad that
414
* we can't negotiate a new key within the time allotted.
416
#define KEY_SCAN_SIZE 3
420
* Security parameter state for a single VPN tunnel.
421
* @ingroup control_processor
423
* An active VPN tunnel running with TLS enabled has one \c tls_multi
424
* object, in which it stores all control channel and data channel
425
* security parameter state. This structure can contain multiple,
426
* possibly simultaneously active, \c tls_context objects to allow for
427
* interruption-less transitions during session renegotiations. Each \c
428
* tls_context represents one control channel session, which can span
429
* multiple data channel security parameter sessions stored in \c
430
* key_state structures.
434
/* used to coordinate access between main thread and TLS thread */
435
/*MUTEX_PTR_DEFINE (mutex);*/
437
/* const options and config info */
438
struct tls_options opt;
440
struct key_state* key_scan[KEY_SCAN_SIZE];
441
/**< List of \c key_state objects in the
442
* order they should be scanned by data
443
* channel modules. */
446
* used by tls_pre_encrypt to communicate the encrypt key
447
* to tls_post_encrypt()
449
struct key_state *save_ks; /* temporary pointer used between pre/post routines */
452
* Used to return outgoing address from
455
struct link_socket_actual to_link_addr;
457
int n_sessions; /**< Number of sessions negotiated thus
463
int n_hard_errors; /* errors due to TLS negotiation failure */
464
int n_soft_errors; /* errors due to unrecognized or failed-to-authenticate incoming packets */
467
* Our locked common name, username, and cert hashes (cannot change during the life of this tls_multi object)
470
char *locked_username;
471
struct cert_hash_set *locked_cert_hash_set;
473
#ifdef ENABLE_DEF_AUTH
475
* An error message to send to client on AUTH_FAILED
480
* A multi-line string of general-purpose info received from peer
481
* over control channel.
485
/* Time of last call to tls_authentication_status */
490
* Our session objects.
492
struct tls_session session[TM_SIZE];
493
/**< Array of \c tls_session objects
494
* representing control channel
495
* sessions with the remote peer. */
499
#endif /* SSL_COMMON_H_ */
added
removed
src/openvpn/ssl_common.h
