OpenVPN
ssl.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-2018 OpenVPN Inc <sales@openvpn.net>
9  * Copyright (C) 2010-2018 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 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 OPENVPN_SSL_H
30 #define OPENVPN_SSL_H
31 
32 #include "basic.h"
33 #include "common.h"
34 #include "crypto.h"
35 #include "packet_id.h"
36 #include "session_id.h"
37 #include "reliable.h"
38 #include "socket.h"
39 #include "mtu.h"
40 #include "options.h"
41 #include "plugin.h"
42 
43 #include "ssl_common.h"
44 #include "ssl_backend.h"
45 
46 /* Used in the TLS PRF function */
47 #define KEY_EXPANSION_ID "OpenVPN"
48 
49 /* packet opcode (high 5 bits) and key-id (low 3 bits) are combined in one byte */
50 #define P_KEY_ID_MASK 0x07
51 #define P_OPCODE_SHIFT 3
52 
53 /* packet opcodes -- the V1 is intended to allow protocol changes in the future */
54 #define P_CONTROL_HARD_RESET_CLIENT_V1 1 /* initial key from client, forget previous state */
55 #define P_CONTROL_HARD_RESET_SERVER_V1 2 /* initial key from server, forget previous state */
56 #define P_CONTROL_SOFT_RESET_V1 3 /* new key, graceful transition from old to new key */
57 #define P_CONTROL_V1 4 /* control channel packet (usually TLS ciphertext) */
58 #define P_ACK_V1 5 /* acknowledgement for packets received */
59 #define P_DATA_V1 6 /* data channel packet */
60 #define P_DATA_V2 9 /* data channel packet with peer-id */
61 
62 /* indicates key_method >= 2 */
63 #define P_CONTROL_HARD_RESET_CLIENT_V2 7 /* initial key from client, forget previous state */
64 #define P_CONTROL_HARD_RESET_SERVER_V2 8 /* initial key from server, forget previous state */
65 
66 /* define the range of legal opcodes */
67 #define P_FIRST_OPCODE 1
68 #define P_LAST_OPCODE 9
69 
70 /*
71  * Set the max number of acknowledgments that can "hitch a ride" on an outgoing
72  * non-P_ACK_V1 control packet.
73  */
74 #define CONTROL_SEND_ACK_MAX 4
75 
76 /*
77  * Define number of buffers for send and receive in the reliability layer.
78  */
79 #define TLS_RELIABLE_N_SEND_BUFFERS 4 /* also window size for reliability layer */
80 #define TLS_RELIABLE_N_REC_BUFFERS 8
81 
82 /*
83  * Various timeouts
84  */
85 #define TLS_MULTI_REFRESH 15 /* call tls_multi_process once every n seconds */
86 #define TLS_MULTI_HORIZON 2 /* call tls_multi_process frequently for n seconds after
87  * every packet sent/received action */
88 
89 /*
90  * The SSL/TLS worker thread will wait at most this many seconds for the
91  * interprocess communication pipe to the main thread to be ready to accept
92  * writes.
93  */
94 #define TLS_MULTI_THREAD_SEND_TIMEOUT 5
95 
96 /* Interval that tls_multi_process should call tls_authentication_status */
97 #define TLS_MULTI_AUTH_STATUS_INTERVAL 10
98 
99 /*
100  * Buffer sizes (also see mtu.h).
101  */
102 
103 /* Maximum length of OCC options string passed as part of auth handshake */
104 #define TLS_OPTIONS_LEN 512
105 
106 /* Default field in X509 to be username */
107 #define X509_USERNAME_FIELD_DEFAULT "CN"
108 
109 /*
110  * Range of key exchange methods
111  */
112 #define KEY_METHOD_MIN 1
113 #define KEY_METHOD_MAX 2
114 
115 /* key method taken from lower 4 bits */
116 #define KEY_METHOD_MASK 0x0F
117 
118 /*
119  * Measure success rate of TLS handshakes, for debugging only
120  */
121 /* #define MEASURE_TLS_HANDSHAKE_STATS */
122 
123 /*
124  * Used in --mode server mode to check tls-auth signature on initial
125  * packets received from new clients.
126  */
128 {
130  struct frame frame;
131 };
132 
133 /*
134  * Prepare the SSL library for use
135  */
136 void init_ssl_lib(void);
137 
138 /*
139  * Free any internal state that the SSL library might have
140  */
141 void free_ssl_lib(void);
142 
147 void init_ssl(const struct options *options, struct tls_root_ctx *ctx);
148 
170 
185 void tls_multi_init_finalize(struct tls_multi *multi,
186  const struct frame *frame);
187 
188 /*
189  * Initialize a standalone tls-auth verification object.
190  */
192  struct gc_arena *gc);
193 
194 /*
195  * Finalize a standalone tls-auth verification object.
196  */
198  const struct frame *frame);
199 
200 /*
201  * Set local and remote option compatibility strings.
202  * Used to verify compatibility of local and remote option
203  * sets.
204  */
205 void tls_multi_init_set_options(struct tls_multi *multi,
206  const char *local,
207  const char *remote);
208 
221 void tls_multi_free(struct tls_multi *multi, bool clear);
222 
227 #define TLSMP_INACTIVE 0
228 #define TLSMP_ACTIVE 1
229 #define TLSMP_KILL 2
230 
231 /*
232  * Called by the top-level event loop.
233  *
234  * Basically decides if we should call tls_process for
235  * the active or untrusted sessions.
236  */
237 int tls_multi_process(struct tls_multi *multi,
238  struct buffer *to_link,
239  struct link_socket_actual **to_link_addr,
240  struct link_socket_info *to_link_socket_info,
241  interval_t *wakeup);
242 
243 
244 /**************************************************************************/
296 bool tls_pre_decrypt(struct tls_multi *multi,
297  const struct link_socket_actual *from,
298  struct buffer *buf,
299  struct crypto_options **opt,
300  bool floated,
301  const uint8_t **ad_start);
302 
303 
304 /**************************************************************************/
339 bool tls_pre_decrypt_lite(const struct tls_auth_standalone *tas,
340  const struct link_socket_actual *from,
341  const struct buffer *buf);
342 
343 
357 void tls_pre_encrypt(struct tls_multi *multi,
358  struct buffer *buf, struct crypto_options **opt);
359 
360 
373 void
374 tls_prepend_opcode_v1(const struct tls_multi *multi, struct buffer *buf);
375 
392 void
393 tls_prepend_opcode_v2(const struct tls_multi *multi, struct buffer *buf);
394 
402 void tls_post_encrypt(struct tls_multi *multi, struct buffer *buf);
403 
406 /*
407  * Setup private key file password. If auth_file is given, use the
408  * credentials stored in the file.
409  */
410 void pem_password_setup(const char *auth_file);
411 
412 /*
413  * Setup authentication username and password. If auth_file is given, use the
414  * credentials stored in the file.
415  */
416 void auth_user_pass_setup(const char *auth_file, const struct static_challenge_info *sc_info);
417 
418 /*
419  * Ensure that no caching is performed on authentication information
420  */
421 void ssl_set_auth_nocache(void);
422 
423 /*
424  * Purge any stored authentication information, both for key files and tunnel
425  * authentication. If PCKS #11 is enabled, purge authentication for that too.
426  */
427 void ssl_purge_auth(const bool auth_user_pass_only);
428 
429 void ssl_set_auth_token(const char *token);
430 
431 #ifdef ENABLE_MANAGEMENT
432 /*
433  * ssl_get_auth_challenge will parse the server-pushed auth-failed
434  * reason string and return a dynamically allocated
435  * auth_challenge_info struct.
436  */
437 void ssl_purge_auth_challenge(void);
438 
439 void ssl_put_auth_challenge(const char *cr_str);
440 
441 #endif
442 
443 /*
444  * Reserve any extra space required on frames.
445  */
446 void tls_adjust_frame_parameters(struct frame *frame);
447 
448 /*
449  * Send a payload over the TLS control channel
450  */
451 bool tls_send_payload(struct tls_multi *multi,
452  const uint8_t *data,
453  int size);
454 
455 /*
456  * Receive a payload through the TLS control channel
457  */
458 bool tls_rec_payload(struct tls_multi *multi,
459  struct buffer *buf);
460 
467 void tls_update_remote_addr(struct tls_multi *multi,
468  const struct link_socket_actual *addr);
469 
482  struct options *options, struct frame *frame);
483 
491 void tls_poor_mans_ncp(struct options *o, const char *remote_ciphername);
492 
493 #ifdef MANAGEMENT_DEF_AUTH
494 static inline char *
495 tls_get_peer_info(const struct tls_multi *multi)
496 {
497  return multi->peer_info;
498 }
499 #endif
500 
505 int tls_peer_info_ncp_ver(const char *peer_info);
506 
514 bool tls_check_ncp_cipher_list(const char *list);
515 
520 bool tls_item_in_cipher_list(const char *item, const char *list);
521 
522 
523 /*
524  * inline functions
525  */
526 
527 static inline bool
529 {
530  return multi->n_sessions > 0;
531 }
532 
533 static inline bool
535 {
536  if (multi)
537  {
538  const struct key_state *ks = &multi->session[TM_ACTIVE].key[KS_PRIMARY];
539  return now < ks->auth_deferred_expire;
540  }
541  return false;
542 }
543 
544 static inline int
545 tls_test_payload_len(const struct tls_multi *multi)
546 {
547  if (multi)
548  {
549  const struct key_state *ks = &multi->session[TM_ACTIVE].key[KS_PRIMARY];
550  if (ks->state >= S_ACTIVE)
551  {
552  return BLEN(&ks->plaintext_read_buf);
553  }
554  }
555  return 0;
556 }
557 
558 static inline void
560 {
561  if (multi)
562  {
563  multi->opt.single_session = true;
564  }
565 }
566 
567 /*
568  * protocol_dump() flags
569  */
570 #define PD_TLS_AUTH_HMAC_SIZE_MASK 0xFF
571 #define PD_SHOW_DATA (1<<8)
572 #define PD_TLS (1<<9)
573 #define PD_VERBOSE (1<<10)
574 
575 const char *protocol_dump(struct buffer *buffer,
576  unsigned int flags,
577  struct gc_arena *gc);
578 
579 /*
580  * debugging code
581  */
582 
583 #ifdef MEASURE_TLS_HANDSHAKE_STATS
584 void show_tls_performance_stats(void);
585 
586 #endif
587 
588 /*#define EXTRACT_X509_FIELD_TEST*/
589 void extract_x509_field_test(void);
590 
597 bool is_hard_reset(int op, int key_method);
598 
599 void delayed_auth_pass_purge(void);
600 
601 
602 /*
603  * Show the TLS ciphers that are available for us to use in the SSL
604  * library with headers hinting their usage and warnings about usage.
605  *
606  * @param cipher_list list of allowed TLS cipher, or NULL.
607  * @param cipher_list_tls13 list of allowed TLS 1.3+ cipher, or NULL
608  * @param tls_cert_profile TLS certificate crypto profile name.
609  */
610 void
611 show_available_tls_ciphers(const char *cipher_list,
612  const char *cipher_list_tls13,
613  const char *tls_cert_profile);
614 
615 #endif /* ifndef OPENVPN_SSL_H */
void ssl_put_auth_challenge(const char *cr_str)
Definition: ssl.c:498
bool tls_session_update_crypto_params(struct tls_session *session, struct options *options, struct frame *frame)
Update TLS session crypto parameters (cipher and auth) and derive data channel keys based on the supp...
Definition: ssl.c:1950
Security parameter state for processing data channel packets.
Definition: crypto.h:232
#define TM_ACTIVE
Active tls_session.
Definition: ssl_common.h:456
Security parameter state of one TLS and data channel key session.
Definition: ssl_common.h:161
struct key_state key[KS_SIZE]
Definition: ssl_common.h:436
struct buffer plaintext_read_buf
Definition: ssl_common.h:185
int n_sessions
Number of sessions negotiated thus far.
Definition: ssl_common.h:519
void tls_auth_standalone_finalize(struct tls_auth_standalone *tas, const struct frame *frame)
Definition: ssl.c:1310
void ssl_set_auth_token(const char *token)
Definition: ssl.c:456
void delayed_auth_pass_purge(void)
Definition: ssl.c:4266
bool tls_send_payload(struct tls_multi *multi, const uint8_t *data, int size)
Definition: ssl.c:3983
Packet geometry parameters.
Definition: mtu.h:93
char * peer_info
Definition: ssl_common.h:550
void pem_password_setup(const char *auth_file)
Definition: ssl.c:372
void tls_post_encrypt(struct tls_multi *multi, struct buffer *buf)
Perform some accounting for the key state used.
Definition: ssl.c:3963
Security parameter state for a single VPN tunnel.
Definition: ssl_common.h:494
bool tls_item_in_cipher_list(const char *item, const char *list)
Return true iff item is present in the colon-separated zero-terminated cipher list.
Definition: ssl.c:1881
static int tls_test_payload_len(const struct tls_multi *multi)
Definition: ssl.h:545
void tls_multi_free(struct tls_multi *multi, bool clear)
Cleanup a tls_multi structure and free associated memory allocations.
Definition: ssl.c:1337
bool is_hard_reset(int op, int key_method)
Given a key_method, return true if opcode represents the required form of hard_reset.
Definition: ssl.c:848
static bool tls_test_auth_deferred_interval(const struct tls_multi *multi)
Definition: ssl.h:534
void tls_prepend_opcode_v2(const struct tls_multi *multi, struct buffer *buf)
Prepend an OpenVPN data channel P_DATA_V2 header to the packet.
Definition: ssl.c:3948
void show_available_tls_ciphers(const char *cipher_list, const char *cipher_list_tls13, const char *tls_cert_profile)
Definition: ssl.c:4120
bool tls_pre_decrypt_lite(const struct tls_auth_standalone *tas, const struct link_socket_actual *from, const struct buffer *buf)
Inspect an incoming packet for which no VPN tunnel is active, and determine whether a new VPN tunnel ...
Definition: ssl.c:3785
struct tls_session session[TM_SIZE]
Array of tls_session objects representing control channel sessions with the remote peer...
Definition: ssl_common.h:569
void tls_pre_encrypt(struct tls_multi *multi, struct buffer *buf, struct crypto_options **opt)
Choose the appropriate security parameters with which to process an outgoing packet.
Definition: ssl.c:3882
void tls_update_remote_addr(struct tls_multi *multi, const struct link_socket_actual *addr)
Updates remote address in TLS sessions.
Definition: ssl.c:4051
void ssl_purge_auth(const bool auth_user_pass_only)
Definition: ssl.c:473
list flags
#define S_ACTIVE
Operational key_state state immediately after negotiation has completed while still within the handsh...
Definition: ssl_common.h:102
void extract_x509_field_test(void)
static void tls_set_single_session(struct tls_multi *multi)
Definition: ssl.h:559
bool tls_check_ncp_cipher_list(const char *list)
Check whether the ciphers in the supplied list are supported.
Definition: ssl.c:4097
bool tls_rec_payload(struct tls_multi *multi, struct buffer *buf)
Definition: ssl.c:4022
struct tls_auth_standalone * tls_auth_standalone_init(struct tls_options *tls_options, struct gc_arena *gc)
Definition: ssl.c:1287
Control channel wrapping (–tls-auth/–tls-crypt) context.
Definition: ssl_common.h:220
void tls_prepend_opcode_v1(const struct tls_multi *multi, struct buffer *buf)
Prepend a one-byte OpenVPN data channel P_DATA_V1 opcode to the packet.
Definition: ssl.c:3934
void auth_user_pass_setup(const char *auth_file, const struct static_challenge_info *sc_info)
Definition: ssl.c:407
Reliability Layer module header file.
int tls_peer_info_ncp_ver(const char *peer_info)
Return the Negotiable Crypto Parameters version advertised in the peer info string, or 0 if none specified.
Definition: ssl.c:4081
#define KS_PRIMARY
Primary key state index.
Definition: ssl_common.h:368
bool single_session
Definition: ssl_common.h:259
time_t now
Definition: otime.c:36
struct tls_multi * tls_multi_init(struct tls_options *tls_options)
Allocate and initialize a tls_multi structure.
Definition: ssl.c:1246
void init_ssl_lib(void)
Definition: ssl.c:348
static bool tls_initial_packet_received(const struct tls_multi *multi)
Definition: ssl.h:528
struct tls_wrap_ctx tls_wrap
Definition: ssl.h:129
struct tls_options opt
Definition: ssl_common.h:500
void tls_multi_init_set_options(struct tls_multi *multi, const char *local, const char *remote)
Definition: ssl.c:1322
void free_ssl_lib(void)
Definition: ssl.c:356
#define BLEN(buf)
Definition: buffer.h:127
time_t auth_deferred_expire
Definition: ssl_common.h:202
unsigned __int8 uint8_t
Definition: config-msvc.h:123
bool tls_pre_decrypt(struct tls_multi *multi, const struct link_socket_actual *from, struct buffer *buf, struct crypto_options **opt, bool floated, const uint8_t **ad_start)
Determine whether an incoming packet is a data channel or control channel packet, and process accordi...
Definition: ssl.c:3307
Structure that wraps the TLS context.
Definition: ssl_mbedtls.h:90
const char * protocol_dump(struct buffer *buffer, unsigned int flags, struct gc_arena *gc)
Definition: ssl.c:4148
Security parameter state of a single session within a VPN tunnel.
Definition: ssl_common.h:398
Wrapper structure for dynamically allocated memory.
Definition: buffer.h:60
int tls_multi_process(struct tls_multi *multi, struct buffer *to_link, struct link_socket_actual **to_link_addr, struct link_socket_info *to_link_socket_info, interval_t *wakeup)
Definition: ssl.c:3112
void tls_multi_init_finalize(struct tls_multi *multi, const struct frame *frame)
Finalize initialization of a tls_multi structure.
Definition: ssl.c:1268
void ssl_purge_auth_challenge(void)
Definition: ssl.c:491
Garbage collection arena used to keep track of dynamically allocated memory.
Definition: buffer.h:116
int interval_t
Definition: common.h:45
void ssl_set_auth_nocache(void)
Definition: ssl.c:444
void tls_poor_mans_ncp(struct options *o, const char *remote_ciphername)
"Poor man&#39;s NCP": Use peer cipher if it is an allowed (NCP) cipher.
Definition: ssl.c:1901
void tls_adjust_frame_parameters(struct frame *frame)
Definition: ssl.c:315
void init_ssl(const struct options *options, struct tls_root_ctx *ctx)
Build master SSL context object that serves for the whole of OpenVPN instantiation.
Definition: ssl.c:596