1/* 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 6 * packet compression. 7 * 8 * Copyright (C) 2002-2010 OpenVPN Technologies, Inc. <sales@openvpn.net> 9 * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com> 10 * 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. 14 * 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. 19 * 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 24 */ 25 26/** 27 * @file Control Channel Common Data Structures 28 */ 29 30#ifndef SSL_COMMON_H_ 31#define SSL_COMMON_H_ 32 33#include "session_id.h" 34#include "socket.h" 35#include "packet_id.h" 36#include "crypto.h" 37#include "options.h" 38 39#include "ssl_backend.h" 40 41/* passwords */ 42#define UP_TYPE_AUTH "Auth" 43#define UP_TYPE_PRIVATE_KEY "Private Key" 44 45/** @addtogroup control_processor 46 * @{ */ 47/** 48 * @name Control channel negotiation states 49 * 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. 57 * 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 65 * material. 66 * -# \c S_GOT_KEY, have received remote part of \c key_source2 random 67 * material. 68 * -# \c S_ACTIVE, normal operation during remaining handshake window. 69 * -# \c S_NORMAL_OP, normal operation. 70 * 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 74 * its own. 75 * 76 * @{ 77 */ 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 93 * material. */ 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 100 * state. */ 101/** @} name Control channel negotiation states */ 102/** @} addtogroup control_processor */ 103 104/** 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 108 */ 109struct key_source { 110 uint8_t pre_master[48]; /**< Random used for master secret 111 * generation, provided only by client 112 * OpenVPN peer. */ 113 uint8_t random1[32]; /**< Seed used for master secret 114 * generation, provided by both client 115 * and server. */ 116 uint8_t random2[32]; /**< Seed used for key expansion, provided 117 * by both client and server. */ 118}; 119 120 121/** 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 125 */ 126struct key_source2 { 127 struct key_source client; /**< Random provided by client. */ 128 struct key_source server; /**< Random provided by server. */ 129}; 130 131/** 132 * Security parameter state of one TLS and data channel %key session. 133 * @ingroup control_processor 134 * 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. 139 * 140 * A new \c key_state structure is initialized for each hard or soft 141 * reset. 142 * 143 * @see 144 * - This structure should be initialized using the \c key_state_init() 145 * function. 146 * - This structure should be cleaned up using the \c key_state_free() 147 * function. 148 */ 149struct key_state 150{ 151 int state; 152 int key_id; /* inherited from struct tls_session below */ 153 154 struct key_state_ssl ks_ssl; /* contains SSL object and BIOs for the control channel */ 155 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 */ 159 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 */ 164 165 struct key_ctx_bi key; /* data channel keys for encrypt/decrypt/hmac */ 166 167 struct key_source2 *key_src; /* source entropy for key expansion */ 168 169 struct buffer plaintext_read_buf; 170 struct buffer plaintext_write_buf; 171 struct buffer ack_write_buf; 172 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 */ 176 177 struct buffer_list *paybuf; 178 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 */ 181 182 /* 183 * If bad username/password, TLS connection will come up but 'authenticated' will be false. 184 */ 185 bool authenticated; 186 time_t auth_deferred_expire; 187 188#ifdef ENABLE_DEF_AUTH 189 /* If auth_deferred is true, authentication is being deferred */ 190 bool auth_deferred; 191#ifdef MANAGEMENT_DEF_AUTH 192 unsigned int mda_key_id; 193 unsigned int mda_status; 194#endif 195#ifdef PLUGIN_DEF_AUTH 196 unsigned int auth_control_status; 197 time_t acf_last_mod; 198 char *auth_control_file; 199#endif 200#endif 201}; 202 203/* 204 * Our const options, obtained directly or derived from 205 * command line options. 206 */ 207struct tls_options 208{ 209 /* our master TLS context from which all SSL objects derived */ 210 struct tls_root_ctx ssl_ctx; 211 212 /* data channel cipher, hmac, and key lengths */ 213 struct key_type key_type; 214 215 /* true if we are a TLS server, client otherwise */ 216 bool server; 217 218 /* if true, don't xmit until first packet from peer is received */ 219 bool xmit_hold; 220 221#ifdef ENABLE_OCC 222 /* local and remote options strings 223 that must match between client and server */ 224 const char *local_options; 225 const char *remote_options; 226#endif 227 228 /* from command line */ 229 int key_method; 230 bool replay; 231 bool single_session; 232#ifdef ENABLE_OCC 233 bool disable_occ; 234#endif 235#ifdef ENABLE_PUSH_PEER_INFO 236 bool push_peer_info; 237#endif 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; 244 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; 251 int ns_cert_type; 252 unsigned remote_cert_ku[MAX_PARMS]; 253 const char *remote_cert_eku; 254 uint8_t *verify_hash; 255 char *x509_username_field; 256 257 /* allow openvpn config info to be 258 passed over control channel */ 259 bool pass_config_info; 260 261 /* struct crypto_option flags */ 262 unsigned int crypto_flags_and; 263 unsigned int crypto_flags_or; 264 265 int replay_window; /* --replay-window parm */ 266 int replay_time; /* --replay-window parm */ 267 bool tcp_mode; 268 269 /* packet authentication for TLS handshake */ 270 struct crypto_options tls_auth; 271 struct key_ctx_bi tls_auth_key; 272 273 /* frame parameters for TLS control channel */ 274 struct frame frame; 275 276 /* used for username/password authentication */ 277 const char *auth_user_pass_verify_script; 278 bool auth_user_pass_verify_script_via_file; 279 const char *tmp_dir; 280 281 /* use the client-config-dir as a positive authenticator */ 282 const char *client_config_dir_exclusive; 283 284 /* instance-wide environment variable set */ 285 struct env_set *es; 286 const struct plugin_list *plugins; 287 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; 295 296#ifdef MANAGEMENT_DEF_AUTH 297 struct man_def_auth_context *mda_context; 298#endif 299 300#ifdef ENABLE_X509_TRACK 301 const struct x509_track *x509_track; 302#endif 303 304#ifdef ENABLE_CLIENT_CR 305 const struct static_challenge_info *sci; 306#endif 307 308 /* --gremlin bits */ 309 int gremlin; 310}; 311 312/** @addtogroup control_processor 313 * @{ */ 314/** @name Index of key_state objects within a tls_session structure 315 * 316 * This is the index of \c tls_session.key 317 * 318 * @{ */ 319#define KS_PRIMARY 0 /**< Primary %key state index. */ 320#define KS_LAME_DUCK 1 /**< %Key state index that will retire 321 * soon. */ 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 */ 325 326 327/** 328 * Security parameter state of a single session within a VPN tunnel. 329 * @ingroup control_processor 330 * 331 * This structure represents an OpenVPN peer-to-peer control channel 332 * session. 333 * 334 * A \c tls_session remains over soft resets, but a new instance is 335 * initialized for each hard reset. 336 * 337 * @see 338 * - This structure should be initialized using the \c tls_session_init() 339 * function. 340 * - This structure should be cleaned up using the \c tls_session_free() 341 * function. 342 */ 343struct tls_session 344{ 345 /* const options and config info */ 346 struct tls_options *opt; 347 348 /* during hard reset used to control burst retransmit */ 349 bool burst; 350 351 /* authenticate control packets */ 352 struct crypto_options tls_auth; 353 struct packet_id tls_auth_pid; 354 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) */ 358 359 int limit_next; /* used for traffic shaping on the control channel */ 360 361 int verify_maxlevel; 362 363 char *common_name; 364 365 struct cert_hash_set *cert_hash_set; 366 367#ifdef ENABLE_PF 368 uint32_t common_name_hashval; 369#endif 370 371 bool verified; /* true if peer certificate was verified against CA */ 372 373 /* not-yet-authenticated incoming client */ 374 struct link_socket_actual untrusted_addr; 375 376 struct key_state key[KS_SIZE]; 377}; 378 379/** @addtogroup control_processor 380 * @{ */ 381/** @name Index of tls_session objects within a tls_multi structure 382 * 383 * This is the index of \c tls_multi.session 384 * 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. 394 * 395 * @{ */ 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 401 * array. */ 402/** @} name Index of tls_session objects within a tls_multi structure */ 403/** @} addtogroup control_processor */ 404 405 406/* 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. 415 */ 416#define KEY_SCAN_SIZE 3 417 418 419/** 420 * Security parameter state for a single VPN tunnel. 421 * @ingroup control_processor 422 * 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. 431 */ 432struct tls_multi 433{ 434 /* used to coordinate access between main thread and TLS thread */ 435 /*MUTEX_PTR_DEFINE (mutex);*/ 436 437 /* const options and config info */ 438 struct tls_options opt; 439 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. */ 444 445 /* 446 * used by tls_pre_encrypt to communicate the encrypt key 447 * to tls_post_encrypt() 448 */ 449 struct key_state *save_ks; /* temporary pointer used between pre/post routines */ 450 451 /* 452 * Used to return outgoing address from 453 * tls_multi_process. 454 */ 455 struct link_socket_actual to_link_addr; 456 457 int n_sessions; /**< Number of sessions negotiated thus 458 * far. */ 459 460 /* 461 * Number of errors. 462 */ 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 */ 465 466 /* 467 * Our locked common name, username, and cert hashes (cannot change during the life of this tls_multi object) 468 */ 469 char *locked_cn; 470 char *locked_username; 471 struct cert_hash_set *locked_cert_hash_set; 472 473#ifdef ENABLE_DEF_AUTH 474 /* 475 * An error message to send to client on AUTH_FAILED 476 */ 477 char *client_reason; 478 479 /* 480 * A multi-line string of general-purpose info received from peer 481 * over control channel. 482 */ 483 char *peer_info; 484 485 /* Time of last call to tls_authentication_status */ 486 time_t tas_last; 487#endif 488 489 /* 490 * Our session objects. 491 */ 492 struct tls_session session[TM_SIZE]; 493 /**< Array of \c tls_session objects 494 * representing control channel 495 * sessions with the remote peer. */ 496}; 497 498 499#endif /* SSL_COMMON_H_ */ 500