OpenVPN
ssl_common.h
Go to the documentation of this file.
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-2021 OpenVPN Inc <sales@openvpn.net>
9  * Copyright (C) 2010-2021 Fox Crypto B.V. <openvpn@foxcrypto.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 along
21  * with this program; if not, write to the Free Software Foundation, Inc.,
22  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
23  */
24 
29 #ifndef SSL_COMMON_H_
30 #define SSL_COMMON_H_
31 
32 #include "session_id.h"
33 #include "socket.h"
34 #include "packet_id.h"
35 #include "crypto.h"
36 #include "options.h"
37 
38 #include "ssl_backend.h"
39 
40 /* passwords */
41 #define UP_TYPE_AUTH "Auth"
42 #define UP_TYPE_PRIVATE_KEY "Private Key"
43 
77 #define S_ERROR -1
78 #define S_UNDEF 0
80 #define S_INITIAL 1
83 #define S_PRE_START 2
86 #define S_START 3
88 #define S_SENT_KEY 4
90 #define S_GOT_KEY 5
93 #define S_ACTIVE 6
98 #define S_GENERATED_KEYS 7
102 /* Note that earlier versions also had a S_OP_NORMAL state that was
103  * virtually identical with S_ACTIVE and the code still assumes everything
104  * >= S_ACTIVE to be fully operational */
105 
113 struct key_source {
114  uint8_t pre_master[48];
117  uint8_t random1[32];
120  uint8_t random2[32];
122 };
123 
124 
130 struct key_source2 {
131  struct key_source client;
132  struct key_source server;
133 };
134 
143 enum ks_auth_state {
144  KS_AUTH_FALSE,
152 };
153 
155 {
156  char *auth_control_file;
157  char *auth_pending_file;
158  unsigned int auth_control_status;
159 };
161 /* key_state_test_auth_control_file return values, these specify the
162  * current status of a deferred authentication */
164  ACF_PENDING,
165  ACF_SUCCEEDED,
166  ACF_DISABLED,
167  ACF_FAILED
168 };
188 struct key_state
189 {
190  int state;
192  int auth_token_state_flags;
193 
198  int key_id;
199 
200  struct key_state_ssl ks_ssl; /* contains SSL object and BIOs for the control channel */
201 
202  time_t initial; /* when we created this session */
203  time_t established; /* when our state went S_ACTIVE */
204  time_t must_negotiate; /* key negotiation times out if not finished before this time */
205  time_t must_die; /* this object is destroyed at this time */
206  time_t peer_last_packet; /* Last time we received a packet in this control session */
208  int initial_opcode; /* our initial P_ opcode */
209  struct session_id session_id_remote; /* peer's random session ID */
210  struct link_socket_actual remote_addr; /* peer's IP addr */
211 
212  struct crypto_options crypto_options;/* data channel crypto options */
214  struct key_source2 *key_src; /* source entropy for key expansion */
216  struct buffer plaintext_read_buf;
217  struct buffer plaintext_write_buf;
218  struct buffer ack_write_buf;
220  struct reliable *send_reliable; /* holds a copy of outgoing packets until ACK received */
221  struct reliable *rec_reliable; /* order incoming ciphertext packets before we pass to TLS */
222  struct reliable_ack *rec_ack; /* buffers all packet IDs we want to ACK back to sender */
224  struct buffer_list *paybuf;
226  counter_type n_bytes; /* how many bytes sent/recvd since last key exchange */
227  counter_type n_packets; /* how many packets sent/recvd since last key exchange */
228 
229  /*
230  * If bad username/password, TLS connection will come up but 'authenticated' will be false.
231  */
232  enum ks_auth_state authenticated;
233  time_t auth_deferred_expire;
234 
235 #ifdef ENABLE_MANAGEMENT
236  unsigned int mda_key_id;
237  enum auth_deferred_result mda_status;
238 #endif
239  time_t acf_last_mod;
240 
241  struct auth_deferred_status plugin_auth;
242  struct auth_deferred_status script_auth;
243 };
244 
246 struct tls_wrap_ctx
247 {
248  enum {
249  TLS_WRAP_NONE = 0,
250  TLS_WRAP_AUTH,
251  TLS_WRAP_CRYPT,
252  } mode;
253  struct crypto_options opt;
254  struct buffer work;
255  struct key_ctx tls_crypt_v2_server_key;
256  const struct buffer *tls_crypt_v2_wkc;
258  struct buffer tls_crypt_v2_metadata;
259  bool cleanup_key_ctx;
261 };
262 
263 /*
264  * Our const options, obtained directly or derived from
265  * command line options.
266  */
267 struct tls_options
268 {
269  /* our master TLS context from which all SSL objects derived */
270  struct tls_root_ctx ssl_ctx;
272  /* data channel cipher, hmac, and key lengths */
275  /* true if we are a TLS server, client otherwise */
276  bool server;
277 
278  /* if true, don't xmit until first packet from peer is received */
279  bool xmit_hold;
280 
281  /* local and remote options strings
282  * that must match between client and server */
283  const char *local_options;
284  const char *remote_options;
286  /* from command line */
287  bool replay;
288  bool single_session;
289  bool disable_occ;
290  int mode;
291  bool pull;
302  int push_peer_info_detail;
303  int transition_window;
304  int handshake_window;
305  interval_t packet_timeout;
306  int renegotiate_bytes;
307  int renegotiate_packets;
308  interval_t renegotiate_seconds;
309 
310  /* cert verification parms */
311  const char *verify_command;
312  const char *verify_export_cert;
313  int verify_x509_type;
314  const char *verify_x509_name;
315  const char *crl_file;
316  bool crl_file_inline;
317  int ns_cert_type;
318  unsigned remote_cert_ku[MAX_PARMS];
319  const char *remote_cert_eku;
320  struct verify_hash_list *verify_hash;
321  int verify_hash_depth;
322  bool verify_hash_no_ca;
323  hash_algo_type verify_hash_algo;
324 #ifdef ENABLE_X509ALTUSERNAME
325  char *x509_username_field[MAX_PARMS];
326 #else
327  char *x509_username_field[2];
328 #endif
330  /* struct crypto_option flags */
331  unsigned int crypto_flags;
333  int replay_window; /* --replay-window parm */
334  int replay_time; /* --replay-window parm */
335  bool tcp_mode;
337  const char *config_ciphername;
338  const char *config_ncp_ciphers;
339 
340  bool tls_crypt_v2;
341  const char *tls_crypt_v2_verify_script;
344  struct tls_wrap_ctx tls_wrap;
345 
346  struct frame frame;
347 
348  /* used for username/password authentication */
349  const char *auth_user_pass_verify_script;
350  bool auth_user_pass_verify_script_via_file;
351  const char *tmp_dir;
352  const char *auth_user_pass_file;
354  bool auth_token_generate;
357  bool auth_token_call_auth;
358  unsigned int auth_token_lifetime;
360  struct key_ctx auth_token_key;
362  /* use the client-config-dir as a positive authenticator */
363  const char *client_config_dir_exclusive;
365  /* instance-wide environment variable set */
366  struct env_set *es;
368  const struct plugin_list *plugins;
370  /* compression parms */
371 #ifdef USE_COMP
372  struct compress_options comp_options;
373 #endif
374 
375  /* configuration file SSL-related boolean and low-permutation options */
376 #define SSLF_CLIENT_CERT_NOT_REQUIRED (1<<0)
377 #define SSLF_CLIENT_CERT_OPTIONAL (1<<1)
378 #define SSLF_USERNAME_AS_COMMON_NAME (1<<2)
379 #define SSLF_AUTH_USER_PASS_OPTIONAL (1<<3)
380 #define SSLF_OPT_VERIFY (1<<4)
381 #define SSLF_CRL_VERIFY_DIR (1<<5)
382 #define SSLF_TLS_VERSION_MIN_SHIFT 6
383 #define SSLF_TLS_VERSION_MIN_MASK 0xF /* (uses bit positions 6 to 9) */
384 #define SSLF_TLS_VERSION_MAX_SHIFT 10
385 #define SSLF_TLS_VERSION_MAX_MASK 0xF /* (uses bit positions 10 to 13) */
386 #define SSLF_TLS_DEBUG_ENABLED (1<<14)
387  unsigned int ssl_flags;
388 
389 #ifdef ENABLE_MANAGEMENT
390  struct man_def_auth_context *mda_context;
391 #endif
393  const struct x509_track *x509_track;
395 #ifdef ENABLE_MANAGEMENT
396  const struct static_challenge_info *sci;
397 #endif
399  /* --gremlin bits */
400  int gremlin;
402  /* Keying Material Exporter [RFC 5705] parameters */
403  const char *ekm_label;
404  size_t ekm_label_size;
405  size_t ekm_size;
406 };
407 
415 #define KS_PRIMARY 0
416 #define KS_LAME_DUCK 1
418 #define KS_SIZE 2
438 struct tls_session
439 {
440  /* const options and config info */
441  struct tls_options *opt;
442 
443  /* during hard reset used to control burst retransmit */
444  bool burst;
445 
446  /* authenticate control packets */
447  struct tls_wrap_ctx tls_wrap;
448 
449  int initial_opcode; /* our initial P_ opcode */
450  struct session_id session_id; /* our random session ID */
451 
457  int key_id;
458 
459  int limit_next; /* used for traffic shaping on the control channel */
461  int verify_maxlevel;
462 
463  char *common_name;
464 
467  bool verified; /* true if peer certificate was verified against CA */
468 
469  /* not-yet-authenticated incoming client */
470  struct link_socket_actual untrusted_addr;
471 
472  struct key_state key[KS_SIZE];
473 };
474 
492 #define TM_ACTIVE 0
493 #define TM_UNTRUSTED 1
495 #define TM_LAME_DUCK 2
496 #define TM_SIZE 3
502 /*
503  * The number of keys we will scan on encrypt or decrypt. The first
504  * is the "active" key. The second is the lame_duck or retiring key
505  * associated with the active key's session ID. The third is a detached
506  * lame duck session that only occurs in situations where a key renegotiate
507  * failed on the active key, but a lame duck key was still valid. By
508  * preserving the lame duck session, we can be assured of having a data
509  * channel key available even when network conditions are so bad that
510  * we can't negotiate a new key within the time allotted.
511  */
512 #define KEY_SCAN_SIZE 3
514 
515 /* client authentication state, CAS_SUCCEEDED must be 0 since
516  * non multi code path still checks this variable but does not initialise it
517  * so the code depends on zero initialisation */
518 
519 /* CAS_NOT_CONNECTED is the initial state for every context. When the *first*
520  * tls_session reaches S_ACTIVE, this state machine moves to CAS_PENDING (server)
521  * or CAS_CONNECT_DONE (client/p2p) as clients skip the stages associated with
522  * connect scripts/plugins */
523 enum multi_status {
526  CAS_PENDING,
529  CAS_FAILED,
532 };
533 
534 
548 struct tls_multi
549 {
550  /* used to coordinate access between main thread and TLS thread */
551  /*MUTEX_PTR_DEFINE (mutex);*/
552 
553  /* const options and config info */
554  struct tls_options opt;
555 
556  /*
557  * used by tls_pre_encrypt to communicate the encrypt key
558  * to tls_post_encrypt()
559  */
560  struct key_state *save_ks; /* temporary pointer used between pre/post routines */
561 
562  /*
563  * Used to return outgoing address from
564  * tls_multi_process.
565  */
566  struct link_socket_actual to_link_addr;
567 
568  int n_sessions;
570  enum multi_status multi_state;
571 
572  /*
573  * Number of errors.
574  */
575  int n_hard_errors; /* errors due to TLS negotiation failure */
576  int n_soft_errors; /* errors due to unrecognized or failed-to-authenticate incoming packets */
577 
578  /*
579  * Our locked common name, username, and cert hashes (cannot change during the life of this tls_multi object)
580  */
581  char *locked_cn;
582  char *locked_username;
583  struct cert_hash_set *locked_cert_hash_set;
587  time_t tas_cache_last_update;
590  unsigned int tas_cache_num_updates;
591 
592  /*
593  * An error message to send to client on AUTH_FAILED
594  */
595  char *client_reason;
596 
597  /*
598  * A multi-line string of general-purpose info received from peer
599  * over control channel.
600  */
601  char *peer_info;
602  char *auth_token;
606  char *auth_token_initial;
610 #define AUTH_TOKEN_HMAC_OK (1<<0)
611 
612 #define AUTH_TOKEN_EXPIRED (1<<1)
614 #define AUTH_TOKEN_VALID_EMPTYUSER (1<<2)
615 
623  /* For P_DATA_V2 */
624  uint32_t peer_id;
625  bool use_peer_id;
626 
627  char *remote_ciphername;
628  bool remote_usescomp;
630  /*
631  * Our session objects.
632  */
633  struct tls_session session[TM_SIZE];
637 };
638 
642 static inline struct key_state *
643 get_key_scan(struct tls_multi *multi, int index)
644 {
645  switch (index)
646  {
647  case 0:
648  return &multi->session[TM_ACTIVE].key[KS_PRIMARY];
649  case 1:
650  return &multi->session[TM_ACTIVE].key[KS_LAME_DUCK];
651  case 2:
652  return &multi->session[TM_LAME_DUCK].key[KS_LAME_DUCK];
653  default:
654  ASSERT(false);
655  return NULL; /* NOTREACHED */
656  }
657 }
658 
662 static inline const struct key_state *
663 get_primary_key(const struct tls_multi *multi)
664 {
665  return &multi->session[TM_ACTIVE].key[KS_PRIMARY];
666 }
667 
668 #endif /* SSL_COMMON_H_ */
Security parameter state for processing data channel packets.
Definition: crypto.h:232
#define TM_ACTIVE
Active tls_session.
Definition: ssl_common.h:508
Security parameter state of one TLS and data channel key session.
Definition: ssl_common.h:203
struct key_state key[KS_SIZE]
Definition: ssl_common.h:488
Container for both halves of random material to be used in key method 2 data channel key generation...
Definition: ssl_common.h:145
Packet geometry parameters.
Definition: mtu.h:93
client with pull or p2p waiting for first time options import
Definition: ssl_common.h:548
static const struct key_state * get_primary_key(const struct tls_multi *multi)
gets an item of key_state objects in the order they should be scanned by data channel modules...
Definition: ssl_common.h:681
Security parameter state for a single VPN tunnel.
Definition: ssl_common.h:566
Key state is authenticated.
Definition: ssl_common.h:162
hash_algo_type
Types referencing specific message digest hashing algorithms.
#define MAX_PARMS
Definition: options.h:51
void * openvpn_net_ctx_t
Definition: networking.h:26
#define ASSERT(x)
Definition: error.h:204
uint8_t random1[32]
Seed used for master secret generation, provided by both client and server.
Definition: ssl_common.h:132
struct tls_session session[TM_SIZE]
Array of tls_session objects representing control channel sessions with the remote peer...
Definition: ssl_common.h:651
Structure containing the hashes for a full certificate chain.
Definition: ssl_verify.h:59
at least handler succeeded, no result yet
Definition: ssl_common.h:546
Control channel wrapping (–tls-auth/–tls-crypt) context.
Definition: ssl_common.h:261
uint8_t random2[32]
Seed used for key expansion, provided by both client and server.
Definition: ssl_common.h:135
deferred auth still pending
Definition: ssl_common.h:179
Key state authentication is being deferred, by async auth.
Definition: ssl_common.h:160
#define KS_SIZE
Size of the tls_session.key array.
Definition: ssl_common.h:434
Container for one half of random material to be used in key method 2 data channel key generation...
Definition: ssl_common.h:128
#define KS_PRIMARY
Primary key state index.
Definition: ssl_common.h:430
Key state is not authenticated.
Definition: ssl_common.h:159
deferred auth has failed
Definition: ssl_common.h:182
ks_auth_state
This reflects the (server side) authentication state after the TLS session has been established and k...
Definition: ssl_common.h:158
uint64_t counter_type
Definition: common.h:30
static struct user_pass auth_token
Definition: ssl.c:390
Container for one set of cipher and/or HMAC contexts.
Definition: crypto.h:164
static struct key_state * get_key_scan(struct tls_multi *multi, int index)
gets an item of key_state objects in the order they should be scanned by data channel modules...
Definition: ssl_common.h:661
#define TM_SIZE
Size of the tls_multi.session array.
Definition: ssl_common.h:513
deferred auth is not used
Definition: ssl_common.h:181
Structure that wraps the TLS context.
Definition: ssl_mbedtls.h:104
#define KS_LAME_DUCK
Key state index that will retire soon.
Definition: ssl_common.h:431
Security parameter state of a single session within a VPN tunnel.
Definition: ssl_common.h:454
The acknowledgment structure in which packet IDs are stored for later acknowledgment.
Definition: reliable.h:70
Wrapper structure for dynamically allocated memory.
Definition: buffer.h:60
deferred auth has suceeded
Definition: ssl_common.h:180
The reliability layer storage structure for one VPN tunnel&#39;s control channel in one direction...
Definition: reliable.h:97
#define TM_LAME_DUCK
Old tls_session.
Definition: ssl_common.h:512
multi_status
Definition: ssl_common.h:541
int interval_t
Definition: common.h:36
TLS connection established but deferred auth not finished.
Definition: ssl_common.h:543
uint8_t pre_master[48]
Random used for master secret generation, provided only by client OpenVPN peer.
Definition: ssl_common.h:129
auth_deferred_result
Definition: ssl_common.h:178
Container for unidirectional cipher and HMAC key material.
Definition: crypto.h:151