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-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 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 /* indicates key_method >= 2 and client-specific tls-crypt key */
67 #define P_CONTROL_HARD_RESET_CLIENT_V3 10 /* initial key from client, forget previous state */
68 
69 /* define the range of legal opcodes
70  * Since we do no longer support key-method 1 we consider
71  * the v1 op codes invalid */
72 #define P_FIRST_OPCODE 3
73 #define P_LAST_OPCODE 10
74 
75 /*
76  * Set the max number of acknowledgments that can "hitch a ride" on an outgoing
77  * non-P_ACK_V1 control packet.
78  */
79 #define CONTROL_SEND_ACK_MAX 4
80 
81 /*
82  * Define number of buffers for send and receive in the reliability layer.
83  */
84 #define TLS_RELIABLE_N_SEND_BUFFERS 4 /* also window size for reliability layer */
85 #define TLS_RELIABLE_N_REC_BUFFERS 8
86 
87 /*
88  * Various timeouts
89  */
90 #define TLS_MULTI_REFRESH 15 /* call tls_multi_process once every n seconds */
91 #define TLS_MULTI_HORIZON 2 /* call tls_multi_process frequently for n seconds after
92  * every packet sent/received action */
93 
94 /*
95  * Buffer sizes (also see mtu.h).
96  */
97 
98 /* Maximum length of OCC options string passed as part of auth handshake */
99 #define TLS_OPTIONS_LEN 512
100 
101 /* Definitions of the bits in the IV_PROTO bitfield
102  *
103  * In older OpenVPN versions this used in a comparison
104  * IV_PROTO >= 2 to determine if DATA_V2 is supported.
105  * Therefore any client announcing any of the flags must
106  * also announce IV_PROTO_DATA_V2. We also treat bit 0
107  * as reserved for this reason */
108 
110 #define IV_PROTO_DATA_V2 (1<<1)
111 
114 #define IV_PROTO_REQUEST_PUSH (1<<2)
115 
117 #define IV_PROTO_TLS_KEY_EXPORT (1<<3)
118 
120 #define IV_PROTO_AUTH_PENDING_KW (1<<4)
121 
125 #define IV_PROTO_NCP_P2P (1<<5)
126 
127 /* Default field in X509 to be username */
128 #define X509_USERNAME_FIELD_DEFAULT "CN"
129 
130 #define KEY_METHOD_2 2
131 
132 /* key method taken from lower 4 bits */
133 #define KEY_METHOD_MASK 0x0F
134 
135 /*
136  * Measure success rate of TLS handshakes, for debugging only
137  */
138 /* #define MEASURE_TLS_HANDSHAKE_STATS */
139 
140 /*
141  * Used in --mode server mode to check tls-auth signature on initial
142  * packets received from new clients.
143  */
145 {
147  struct frame frame;
148 };
149 
150 /*
151  * Prepare the SSL library for use
152  */
153 void init_ssl_lib(void);
154 
155 /*
156  * Free any internal state that the SSL library might have
157  */
158 void free_ssl_lib(void);
159 
164 void init_ssl(const struct options *options, struct tls_root_ctx *ctx, bool in_chroot);
165 
187 
202 void tls_multi_init_finalize(struct tls_multi *multi,
203  const struct frame *frame);
204 
205 /*
206  * Initialize a standalone tls-auth verification object.
207  */
209  struct gc_arena *gc);
210 
211 /*
212  * Finalize a standalone tls-auth verification object.
213  */
215  const struct frame *frame);
216 
217 /*
218  * Set local and remote option compatibility strings.
219  * Used to verify compatibility of local and remote option
220  * sets.
221  */
222 void tls_multi_init_set_options(struct tls_multi *multi,
223  const char *local,
224  const char *remote);
225 
238 void tls_multi_free(struct tls_multi *multi, bool clear);
239 
244 #define TLSMP_INACTIVE 0
245 #define TLSMP_ACTIVE 1
246 #define TLSMP_KILL 2
247 
248 /*
249  * Called by the top-level event loop.
250  *
251  * Basically decides if we should call tls_process for
252  * the active or untrusted sessions.
253  */
254 int tls_multi_process(struct tls_multi *multi,
255  struct buffer *to_link,
256  struct link_socket_actual **to_link_addr,
257  struct link_socket_info *to_link_socket_info,
258  interval_t *wakeup);
259 
260 
261 /**************************************************************************/
313 bool tls_pre_decrypt(struct tls_multi *multi,
314  const struct link_socket_actual *from,
315  struct buffer *buf,
316  struct crypto_options **opt,
317  bool floated,
318  const uint8_t **ad_start);
319 
320 
321 /**************************************************************************/
356 bool tls_pre_decrypt_lite(const struct tls_auth_standalone *tas,
357  const struct link_socket_actual *from,
358  const struct buffer *buf);
359 
360 
374 void tls_pre_encrypt(struct tls_multi *multi,
375  struct buffer *buf, struct crypto_options **opt);
376 
386 struct key_state *tls_select_encryption_key(struct tls_multi *multi);
387 
400 void
401 tls_prepend_opcode_v1(const struct tls_multi *multi, struct buffer *buf);
402 
419 void
420 tls_prepend_opcode_v2(const struct tls_multi *multi, struct buffer *buf);
421 
429 void tls_post_encrypt(struct tls_multi *multi, struct buffer *buf);
430 
433 /*
434  * Setup private key file password. If auth_file is given, use the
435  * credentials stored in the file.
436  */
437 void pem_password_setup(const char *auth_file);
438 
439 /*
440  * Setup authentication username and password. If auth_file is given, use the
441  * credentials stored in the file.
442  */
443 void auth_user_pass_setup(const char *auth_file, const struct static_challenge_info *sc_info);
444 
445 /*
446  * Ensure that no caching is performed on authentication information
447  */
448 void ssl_set_auth_nocache(void);
449 
450 /*
451  * Purge any stored authentication information, both for key files and tunnel
452  * authentication. If PCKS #11 is enabled, purge authentication for that too.
453  */
454 void ssl_purge_auth(const bool auth_user_pass_only);
455 
456 void ssl_set_auth_token(const char *token);
457 
458 void ssl_set_auth_token_user(const char *username);
459 
460 bool ssl_clean_auth_token(void);
461 
462 #ifdef ENABLE_MANAGEMENT
463 /*
464  * ssl_get_auth_challenge will parse the server-pushed auth-failed
465  * reason string and return a dynamically allocated
466  * auth_challenge_info struct.
467  */
468 void ssl_purge_auth_challenge(void);
469 
470 void ssl_put_auth_challenge(const char *cr_str);
471 
472 #endif
473 
474 /*
475  * Reserve any extra space required on frames.
476  */
477 void tls_adjust_frame_parameters(struct frame *frame);
478 
479 /*
480  * Send a payload over the TLS control channel
481  */
482 bool tls_send_payload(struct tls_multi *multi,
483  const uint8_t *data,
484  int size);
485 
486 /*
487  * Receive a payload through the TLS control channel
488  */
489 bool tls_rec_payload(struct tls_multi *multi,
490  struct buffer *buf);
491 
498 void tls_update_remote_addr(struct tls_multi *multi,
499  const struct link_socket_actual *addr);
500 
515  struct options *options,
516  struct frame *frame,
517  struct frame *frame_fragment);
518 
519 /*
520  * inline functions
521  */
522 
524 static inline void
526 {
527  if (packet_id_initialized(&tls_wrap->opt.packet_id))
528  {
529  packet_id_free(&tls_wrap->opt.packet_id);
530  }
531 
532  if (tls_wrap->cleanup_key_ctx)
533  {
534  free_key_ctx_bi(&tls_wrap->opt.key_ctx_bi);
535  }
536 
537  free_buf(&tls_wrap->tls_crypt_v2_metadata);
538  free_buf(&tls_wrap->work);
539 }
540 
541 static inline bool
543 {
544  return multi->n_sessions > 0;
545 }
546 
547 static inline int
548 tls_test_payload_len(const struct tls_multi *multi)
549 {
550  if (multi)
551  {
552  const struct key_state *ks = get_primary_key(multi);
553  if (ks->state >= S_ACTIVE)
554  {
555  return BLEN(&ks->plaintext_read_buf);
556  }
557  }
558  return 0;
559 }
560 
561 static inline void
563 {
564  if (multi)
565  {
566  multi->opt.single_session = true;
567  }
568 }
569 
570 /*
571  * protocol_dump() flags
572  */
573 #define PD_TLS_AUTH_HMAC_SIZE_MASK 0xFF
574 #define PD_SHOW_DATA (1<<8)
575 #define PD_TLS (1<<9)
576 #define PD_VERBOSE (1<<10)
577 
578 const char *protocol_dump(struct buffer *buffer,
579  unsigned int flags,
580  struct gc_arena *gc);
581 
582 /*
583  * debugging code
584  */
585 
586 #ifdef MEASURE_TLS_HANDSHAKE_STATS
587 void show_tls_performance_stats(void);
588 
589 #endif
590 
591 /*#define EXTRACT_X509_FIELD_TEST*/
592 void extract_x509_field_test(void);
593 
599 bool is_hard_reset_method2(int op);
600 
604 void ssl_clean_user_pass(void);
605 
606 
607 /*
608  * Show the TLS ciphers that are available for us to use in the SSL
609  * library with headers hinting their usage and warnings about usage.
610  *
611  * @param cipher_list list of allowed TLS cipher, or NULL.
612  * @param cipher_list_tls13 list of allowed TLS 1.3+ cipher, or NULL
613  * @param tls_cert_profile TLS certificate crypto profile name.
614  */
615 void
616 show_available_tls_ciphers(const char *cipher_list,
617  const char *cipher_list_tls13,
618  const char *tls_cert_profile);
619 
620 
627 bool
629 
630 #endif /* ifndef OPENVPN_SSL_H */
void ssl_put_auth_challenge(const char *cr_str)
Definition: ssl.c:495
bool ssl_clean_auth_token(void)
Definition: ssl.c:459
Security parameter state for processing data channel packets.
Definition: crypto.h:232
static void tls_wrap_free(struct tls_wrap_ctx *tls_wrap)
Free the elements of a tls_wrap_ctx structure.
Definition: ssl.h:525
Security parameter state of one TLS and data channel key session.
Definition: ssl_common.h:203
struct buffer work
Work buffer (only for –tls-crypt)
Definition: ssl_common.h:269
struct packet_id packet_id
Current packet ID state for both sending and receiving directions.
Definition: crypto.h:238
struct buffer plaintext_read_buf
Definition: ssl_common.h:231
int n_sessions
Number of sessions negotiated thus far.
Definition: ssl_common.h:586
void tls_auth_standalone_finalize(struct tls_auth_standalone *tas, const struct frame *frame)
Definition: ssl.c:1314
void free_buf(struct buffer *buf)
Definition: buffer.c:185
void ssl_set_auth_token(const char *token)
Definition: ssl.c:444
struct buffer tls_crypt_v2_metadata
Received from client.
Definition: ssl_common.h:273
bool tls_send_payload(struct tls_multi *multi, const uint8_t *data, int size)
Definition: ssl.c:3986
Packet geometry parameters.
Definition: mtu.h:93
void pem_password_setup(const char *auth_file)
Definition: ssl.c:361
void tls_post_encrypt(struct tls_multi *multi, struct buffer *buf)
Perform some accounting for the key state used.
Definition: ssl.c:3966
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
static int tls_test_payload_len(const struct tls_multi *multi)
Definition: ssl.h:548
void tls_multi_free(struct tls_multi *multi, bool clear)
Cleanup a tls_multi structure and free associated memory allocations.
Definition: ssl.c:1339
struct crypto_options opt
Crypto state.
Definition: ssl_common.h:268
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:3951
void ssl_clean_user_pass(void)
Cleans the saved user/password unless auth-nocache is in use.
Definition: ssl.c:4222
bool tls_session_update_crypto_params(struct tls_session *session, struct options *options, struct frame *frame, struct frame *frame_fragment)
Update TLS session crypto parameters (cipher and auth) and derive data channel keys based on the supp...
Definition: ssl.c:1940
void show_available_tls_ciphers(const char *cipher_list, const char *cipher_list_tls13, const char *tls_cert_profile)
Definition: ssl.c:4077
struct key_state * tls_select_encryption_key(struct tls_multi *multi)
Selects the primary encryption that should be used to encrypt data of an outgoing packet...
Definition: ssl.c:3876
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:3784
static bool packet_id_initialized(const struct packet_id *pid)
Is this struct packet_id initialized?
Definition: packet_id.h:274
void packet_id_free(struct packet_id *p)
Definition: packet_id.c:101
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:3904
void tls_update_remote_addr(struct tls_multi *multi, const struct link_socket_actual *addr)
Updates remote address in TLS sessions.
Definition: ssl.c:4049
bool tls_session_generate_data_channel_keys(struct tls_session *session)
Generate data channel keys for the supplied TLS session.
Definition: ssl.c:1847
void ssl_purge_auth(const bool auth_user_pass_only)
Definition: ssl.c:470
list flags
#define S_ACTIVE
Operational key_state state immediately after negotiation has completed while still within the handsh...
Definition: ssl_common.h:102
bool cleanup_key_ctx
opt.key_ctx_bi is owned by this context
Definition: ssl_common.h:274
void extract_x509_field_test(void)
static void tls_set_single_session(struct tls_multi *multi)
Definition: ssl.h:562
bool tls_rec_payload(struct tls_multi *multi, struct buffer *buf)
Definition: ssl.c:4023
struct tls_auth_standalone * tls_auth_standalone_init(struct tls_options *tls_options, struct gc_arena *gc)
Definition: ssl.c:1291
Control channel wrapping (–tls-auth/–tls-crypt) context.
Definition: ssl_common.h:261
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:3937
void auth_user_pass_setup(const char *auth_file, const struct static_challenge_info *sc_info)
Definition: ssl.c:397
Reliability Layer module header file.
bool single_session
Definition: ssl_common.h:303
struct tls_multi * tls_multi_init(struct tls_options *tls_options)
Allocate and initialize a tls_multi structure.
Definition: ssl.c:1259
void init_ssl_lib(void)
Definition: ssl.c:337
static bool tls_initial_packet_received(const struct tls_multi *multi)
Definition: ssl.h:542
struct tls_wrap_ctx tls_wrap
Definition: ssl.h:146
struct tls_options opt
Definition: ssl_common.h:572
void free_key_ctx_bi(struct key_ctx_bi *ctx)
Definition: crypto.c:904
bool is_hard_reset_method2(int op)
Given a key_method, return true if opcode represents the one of the hard_reset op codes for key-metho...
Definition: ssl.c:895
void tls_multi_init_set_options(struct tls_multi *multi, const char *local, const char *remote)
Definition: ssl.c:1326
void free_ssl_lib(void)
Definition: ssl.c:345
#define BLEN(buf)
Definition: buffer.h:127
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:3380
Structure that wraps the TLS context.
Definition: ssl_mbedtls.h:104
struct key_ctx_bi key_ctx_bi
OpenSSL cipher and HMAC contexts for both sending and receiving directions.
Definition: crypto.h:234
const char * protocol_dump(struct buffer *buffer, unsigned int flags, struct gc_arena *gc)
Definition: ssl.c:4104
Security parameter state of a single session within a VPN tunnel.
Definition: ssl_common.h:454
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:3064
void tls_multi_init_finalize(struct tls_multi *multi, const struct frame *frame)
Finalize initialization of a tls_multi structure.
Definition: ssl.c:1272
void ssl_purge_auth_challenge(void)
Definition: ssl.c:488
void ssl_set_auth_token_user(const char *username)
Definition: ssl.c:450
Garbage collection arena used to keep track of dynamically allocated memory.
Definition: buffer.h:116
int interval_t
Definition: common.h:36
void ssl_set_auth_nocache(void)
Definition: ssl.c:434
void tls_adjust_frame_parameters(struct frame *frame)
Definition: ssl.c:304
void init_ssl(const struct options *options, struct tls_root_ctx *ctx, bool in_chroot)
Build master SSL context object that serves for the whole of OpenVPN instantiation.
Definition: ssl.c:601