release/src/router/openvpn/src/openvpn/ssl_common.h

   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  */
 109 struct 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  */
 126 struct 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  */
 149 struct 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  */
 207 struct 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   int push_peer_info_detail;
 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  */
 343 struct 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  */
 432 struct 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_ */