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-2024 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 #include "ssl_pkt.h"
46 #include "tls_crypt.h"
47 
48 /* Used in the TLS PRF function */
49 #define KEY_EXPANSION_ID "OpenVPN"
50 
51 /*
52  * Set the max number of acknowledgments that can "hitch a ride" on an outgoing
53  * non-P_ACK_V1 control packet.
54  */
55 #define CONTROL_SEND_ACK_MAX 4
56 
57 /*
58  * Various timeouts
59  */
60 #define TLS_MULTI_REFRESH 15 /* call tls_multi_process once every n seconds */
61 #define TLS_MULTI_HORIZON 2 /* call tls_multi_process frequently for n seconds after
62  * every packet sent/received action */
63 
64 /*
65  * Buffer sizes (also see mtu.h).
66  */
67 
68 /* Maximum length of OCC options string passed as part of auth handshake */
69 #define TLS_OPTIONS_LEN 512
70 
71 /* Definitions of the bits in the IV_PROTO bitfield
72  *
73  * In older OpenVPN versions this used in a comparison
74  * IV_PROTO >= 2 to determine if DATA_V2 is supported.
75  * Therefore any client announcing any of the flags must
76  * also announce IV_PROTO_DATA_V2. We also treat bit 0
77  * as reserved for this reason */
78 
80 #define IV_PROTO_DATA_V2 (1<<1)
81 
84 #define IV_PROTO_REQUEST_PUSH (1<<2)
85 
87 #define IV_PROTO_TLS_KEY_EXPORT (1<<3)
88 
90 #define IV_PROTO_AUTH_PENDING_KW (1<<4)
91 
95 #define IV_PROTO_NCP_P2P (1<<5)
96 
98 #define IV_PROTO_DNS_OPTION (1<<6)
99 
102 #define IV_PROTO_CC_EXIT_NOTIFY (1<<7)
103 
105 #define IV_PROTO_AUTH_FAIL_TEMP (1<<8)
106 
108 #define IV_PROTO_DYN_TLS_CRYPT (1<<9)
109 
110 /* Default field in X509 to be username */
111 #define X509_USERNAME_FIELD_DEFAULT "CN"
112 
113 #define KEY_METHOD_2 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  * Prepare the SSL library for use
125  */
126 void init_ssl_lib(void);
127 
128 /*
129  * Free any internal state that the SSL library might have
130  */
131 void free_ssl_lib(void);
132 
137 void init_ssl(const struct options *options, struct tls_root_ctx *ctx, bool in_chroot);
138 
160 
175 void tls_multi_init_finalize(struct tls_multi *multi, int tls_mtu);
176 
177 /*
178  * Initialize a standalone tls-auth verification object.
179  */
181  struct gc_arena *gc);
182 
188 
189 /*
190  * Setups the control channel frame size parameters from the data channel
191  * parameters
192  */
193 void tls_init_control_channel_frame_parameters(struct frame *frame, int tls_mtu);
194 
195 /*
196  * Set local and remote option compatibility strings.
197  * Used to verify compatibility of local and remote option
198  * sets.
199  */
200 void tls_multi_init_set_options(struct tls_multi *multi,
201  const char *local,
202  const char *remote);
203 
216 void tls_multi_free(struct tls_multi *multi, bool clear);
217 
222 #define TLSMP_INACTIVE 0
223 #define TLSMP_ACTIVE 1
224 #define TLSMP_KILL 2
225 #define TLSMP_RECONNECT 3
226 
227 /*
228  * Called by the top-level event loop.
229  *
230  * Basically decides if we should call tls_process for
231  * the active or untrusted sessions.
232  */
233 int tls_multi_process(struct tls_multi *multi,
234  struct buffer *to_link,
235  struct link_socket_actual **to_link_addr,
236  struct link_socket_info *to_link_socket_info,
237  interval_t *wakeup);
238 
239 
240 /**************************************************************************/
292 bool tls_pre_decrypt(struct tls_multi *multi,
293  const struct link_socket_actual *from,
294  struct buffer *buf,
295  struct crypto_options **opt,
296  bool floated,
297  const uint8_t **ad_start);
298 
299 
300 /**************************************************************************/
318 void tls_pre_encrypt(struct tls_multi *multi,
319  struct buffer *buf, struct crypto_options **opt);
320 
330 struct key_state *tls_select_encryption_key(struct tls_multi *multi);
331 
344 void
345 tls_prepend_opcode_v1(const struct tls_multi *multi, struct buffer *buf);
346 
363 void
364 tls_prepend_opcode_v2(const struct tls_multi *multi, struct buffer *buf);
365 
373 void tls_post_encrypt(struct tls_multi *multi, struct buffer *buf);
374 
377 /*
378  * Setup private key file password. If auth_file is given, use the
379  * credentials stored in the file.
380  */
381 void pem_password_setup(const char *auth_file);
382 
383 /* Enables the use of user/password authentication */
384 void enable_auth_user_pass(void);
385 
386 /*
387  * Setup authentication username and password. If auth_file is given, use the
388  * credentials stored in the file, however, if is_inline is true then auth_file
389  * contains the username/password inline.
390  */
391 void auth_user_pass_setup(const char *auth_file, bool is_inline,
392  const struct static_challenge_info *sc_info);
393 
394 /*
395  * Ensure that no caching is performed on authentication information
396  */
397 void ssl_set_auth_nocache(void);
398 
399 /*
400  * Getter method for retrieving the auth-nocache option.
401  */
402 bool ssl_get_auth_nocache(void);
403 
404 /*
405  * Purge any stored authentication information, both for key files and tunnel
406  * authentication. If PCKS #11 is enabled, purge authentication for that too.
407  * Note that auth_token is not cleared.
408  */
409 void ssl_purge_auth(const bool auth_user_pass_only);
410 
411 void ssl_set_auth_token(const char *token);
412 
413 void ssl_set_auth_token_user(const char *username);
414 
415 bool ssl_clean_auth_token(void);
416 
417 #ifdef ENABLE_MANAGEMENT
418 
419 void ssl_purge_auth_challenge(void);
420 
421 void ssl_put_auth_challenge(const char *cr_str);
422 
423 #endif
424 
425 /*
426  * Send a payload over the TLS control channel
427  */
428 bool tls_send_payload(struct key_state *ks,
429  const uint8_t *data,
430  int size);
431 
432 /*
433  * Receive a payload through the TLS control channel
434  */
435 bool tls_rec_payload(struct tls_multi *multi,
436  struct buffer *buf);
437 
444 void tls_update_remote_addr(struct tls_multi *multi,
445  const struct link_socket_actual *addr);
446 
464  struct tls_session *session,
465  struct options *options,
466  struct frame *frame,
467  struct frame *frame_fragment,
468  struct link_socket_info *lsi);
469 
470 /*
471  * inline functions
472  */
473 
475 static inline void
476 tls_wrap_free(struct tls_wrap_ctx *tls_wrap)
477 {
478  if (packet_id_initialized(&tls_wrap->opt.packet_id))
479  {
480  packet_id_free(&tls_wrap->opt.packet_id);
481  }
482 
483  if (tls_wrap->cleanup_key_ctx)
484  {
485  free_key_ctx_bi(&tls_wrap->opt.key_ctx_bi);
486  }
487 
488  free_buf(&tls_wrap->tls_crypt_v2_metadata);
489  free_buf(&tls_wrap->work);
490  secure_memzero(&tls_wrap->original_wrap_keydata, sizeof(tls_wrap->original_wrap_keydata));
491 }
492 
493 static inline bool
494 tls_initial_packet_received(const struct tls_multi *multi)
495 {
496  return multi->n_sessions > 0;
497 }
498 
499 static inline int
500 tls_test_payload_len(const struct tls_multi *multi)
501 {
502  if (multi)
503  {
504  const struct key_state *ks = get_primary_key(multi);
505  if (ks->state >= S_ACTIVE)
506  {
507  return BLEN(&ks->plaintext_read_buf);
508  }
509  }
510  return 0;
511 }
512 
513 static inline void
514 tls_set_single_session(struct tls_multi *multi)
515 {
516  if (multi)
517  {
518  multi->opt.single_session = true;
519  }
520 }
521 
522 /*
523  * protocol_dump() flags
524  */
525 #define PD_TLS_AUTH_HMAC_SIZE_MASK 0xFF
526 #define PD_SHOW_DATA (1<<8)
527 #define PD_TLS (1<<9)
528 #define PD_VERBOSE (1<<10)
529 #define PD_TLS_CRYPT (1<<11)
530 
531 const char *protocol_dump(struct buffer *buffer,
532  unsigned int flags,
533  struct gc_arena *gc);
534 
535 /*
536  * debugging code
537  */
538 
539 #ifdef MEASURE_TLS_HANDSHAKE_STATS
540 void show_tls_performance_stats(void);
541 
542 #endif
543 
549 bool is_hard_reset_method2(int op);
550 
551 /*
552  * Show the TLS ciphers that are available for us to use in the SSL
553  * library with headers hinting their usage and warnings about usage.
554  *
555  * @param cipher_list list of allowed TLS cipher, or NULL.
556  * @param cipher_list_tls13 list of allowed TLS 1.3+ cipher, or NULL
557  * @param tls_cert_profile TLS certificate crypto profile name.
558  */
559 void
560 show_available_tls_ciphers(const char *cipher_list,
561  const char *cipher_list_tls13,
562  const char *tls_cert_profile);
563 
564 
571 bool
573  struct tls_session *session);
574 
575 void
576 tls_session_soft_reset(struct tls_multi *multi);
577 
581 void
582 load_xkey_provider(void);
583 
584 /* Special method to skip the three way handshake RESET stages. This is
585  * used by the HMAC code when seeing a packet that matches the previous
586  * HMAC based stateless server state */
587 bool
590  struct link_socket_actual *from);
591 
592 #endif /* ifndef OPENVPN_SSL_H */
load_xkey_provider
void load_xkey_provider(void)
Load ovpn.xkey provider used for external key signing.
Definition: ssl_openssl.c:2442
tls_init_control_channel_frame_parameters
void tls_init_control_channel_frame_parameters(struct frame *frame, int tls_mtu)
Definition: ssl.c:135
ssl_set_auth_token_user
void ssl_set_auth_token_user(const char *username)
Definition: ssl.c:356
enable_auth_user_pass
void enable_auth_user_pass(void)
Definition: ssl.c:280
ssl_backend.h
tls_wrap_ctx::original_wrap_keydata
struct key2 original_wrap_keydata
original key data to be xored in to the key for dynamic tls-crypt.
Definition: ssl_common.h:289
tls_test_payload_len
static int tls_test_payload_len(const struct tls_multi *multi)
Definition: ssl.h:499
ssl_set_auth_nocache
void ssl_set_auth_nocache(void)
Definition: ssl.c:331
interval_t
int interval_t
Definition: common.h:36
ssl_get_auth_nocache
bool ssl_get_auth_nocache(void)
Definition: ssl.c:341
tls_rec_payload
bool tls_rec_payload(struct tls_multi *multi, struct buffer *buf)
Definition: ssl.c:4007
tls_options::single_session
bool single_session
Definition: ssl_common.h:316
get_primary_key
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:722
packet_id_initialized
static bool packet_id_initialized(const struct packet_id *pid)
Is this struct packet_id initialized?
Definition: packet_id.h:269
plugin.h
session_id.h
tls_send_payload
bool tls_send_payload(struct key_state *ks, const uint8_t *data, int size)
Definition: ssl.c:3973
options.h
tls_crypt.h
show_available_tls_ciphers
void show_available_tls_ciphers(const char *cipher_list, const char *cipher_list_tls13, const char *tls_cert_profile)
Definition: ssl.c:4061
frame
Packet geometry parameters.
Definition: mtu.h:98
tls_multi
Security parameter state for a single VPN tunnel.
Definition: ssl_common.h:590
tls_wrap_free
static void tls_wrap_free(struct tls_wrap_ctx *tls_wrap)
Free the elements of a tls_wrap_ctx structure.
Definition: ssl.h:475
key_state
Security parameter state of one TLS and data channel key session.
Definition: ssl_common.h:198
session_skip_to_pre_start
bool session_skip_to_pre_start(struct tls_session *session, struct tls_pre_decrypt_state *state, struct link_socket_actual *from)
Definition: ssl.c:2476
tls_set_single_session
static void tls_set_single_session(struct tls_multi *multi)
Definition: ssl.h:513
mtu.h
tls_session_soft_reset
void tls_session_soft_reset(struct tls_multi *multi)
Definition: ssl.c:1772
free_key_ctx_bi
void free_key_ctx_bi(struct key_ctx_bi *ctx)
Definition: crypto.c:906
ssl_purge_auth
void ssl_purge_auth(const bool auth_user_pass_only)
Definition: ssl.c:376
secure_memzero
static void secure_memzero(void *data, size_t len)
Securely zeroise memory.
Definition: buffer.h:414
tls_wrap_ctx::opt
struct crypto_options opt
Crypto state.
Definition: ssl_common.h:273
reliable.h
ssl_put_auth_challenge
void ssl_put_auth_challenge(const char *cr_str)
Definition: ssl.c:401
tls_options
Definition: ssl_common.h:296
packet_id.h
BLEN
#define BLEN(buf)
Definition: buffer.h:127
S_ACTIVE
#define S_ACTIVE
Operational key_state state immediately after negotiation has completed while still within the handsh...
Definition: ssl_common.h:96
tls_wrap_ctx
Control channel wrapping (–tls-auth/–tls-crypt) context.
Definition: ssl_common.h:266
tls_wrap_ctx::work
struct buffer work
Work buffer (only for –tls-crypt)
Definition: ssl_common.h:274
tls_multi::opt
struct tls_options opt
Definition: ssl_common.h:596
tls_multi_process
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:3126
tls_pre_decrypt_state
struct that stores the temporary data for the tls lite decrypt functions
Definition: ssl_pkt.h:104
init_ssl_lib
void init_ssl_lib(void)
Definition: ssl.c:221
tls_wrap_ctx::tls_crypt_v2_metadata
struct buffer tls_crypt_v2_metadata
Received from client.
Definition: ssl_common.h:278
options
Definition: options.h:236
crypto.h
ssl_set_auth_token
void ssl_set_auth_token(const char *token)
Definition: ssl.c:350
tls_prepend_opcode_v2
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:3938
protocol_dump
const char * protocol_dump(struct buffer *buffer, unsigned int flags, struct gc_arena *gc)
Definition: ssl.c:4088
buffer
Wrapper structure for dynamically allocated memory.
Definition: buffer.h:60
static_challenge_info
Definition: misc.h:92
tls_session
Security parameter state of a single session within a VPN tunnel.
Definition: ssl_common.h:471
key_state::state
int state
Definition: ssl_common.h:200
tls_session_generate_data_channel_keys
bool tls_session_generate_data_channel_keys(struct tls_multi *multi, struct tls_session *session)
Generate data channel keys for the supplied TLS session.
Definition: ssl.c:1550
tls_auth_standalone_free
void tls_auth_standalone_free(struct tls_auth_standalone *tas)
Frees a standalone tls-auth verification object.
Definition: ssl.c:1210
gc_arena
Garbage collection arena used to keep track of dynamically allocated memory.
Definition: buffer.h:116
is_hard_reset_method2
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:772
tls_auth_standalone_init
struct tls_auth_standalone * tls_auth_standalone_init(struct tls_options *tls_options, struct gc_arena *gc)
Definition: ssl.c:1184
tls_multi_free
void tls_multi_free(struct tls_multi *multi, bool clear)
Cleanup a tls_multi structure and free associated memory allocations.
Definition: ssl.c:1239
tls_initial_packet_received
static bool tls_initial_packet_received(const struct tls_multi *multi)
Definition: ssl.h:493
tls_session_update_crypto_params
bool tls_session_update_crypto_params(struct tls_multi *multi, struct tls_session *session, struct options *options, struct frame *frame, struct frame *frame_fragment, struct link_socket_info *lsi)
Update TLS session crypto parameters (cipher and auth) and derive data channel keys based on the supp...
Definition: ssl.c:1638
free_buf
void free_buf(struct buffer *buf)
Definition: buffer.c:183
common.h
tls_multi::n_sessions
int n_sessions
Number of sessions negotiated thus far.
Definition: ssl_common.h:610
pem_password_setup
void pem_password_setup(const char *auth_file)
Definition: ssl.c:244
tls_select_encryption_key
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:3864
tls_multi_init_finalize
void tls_multi_init_finalize(struct tls_multi *multi, int tls_mtu)
Finalize initialization of a tls_multi structure.
Definition: ssl.c:1170
basic.h
tls_multi_init
struct tls_multi * tls_multi_init(struct tls_options *tls_options)
Allocate and initialize a tls_multi structure.
Definition: ssl.c:1155
tls_prepend_opcode_v1
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:3924
tls_root_ctx
Structure that wraps the TLS context.
Definition: ssl_mbedtls.h:106
ssl_pkt.h
ssl_purge_auth_challenge
void ssl_purge_auth_challenge(void)
Definition: ssl.c:394
free_ssl_lib
void free_ssl_lib(void)
Definition: ssl.c:229
tls_update_remote_addr
void tls_update_remote_addr(struct tls_multi *multi, const struct link_socket_actual *addr)
Updates remote address in TLS sessions.
Definition: ssl.c:4033
init_ssl
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:507
socket.h
ssl_clean_auth_token
bool ssl_clean_auth_token(void)
Definition: ssl.c:365
crypto_options::key_ctx_bi
struct key_ctx_bi key_ctx_bi
OpenSSL cipher and HMAC contexts for both sending and receiving directions.
Definition: crypto.h:232
ssl_common.h
tls_post_encrypt
void tls_post_encrypt(struct tls_multi *multi, struct buffer *buf)
Perform some accounting for the key state used.
Definition: ssl.c:3953
tls_pre_encrypt
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:3891
session
Definition: keyingmaterialexporter.c:56
crypto_options::packet_id
struct packet_id packet_id
Current packet ID state for both sending and receiving directions.
Definition: crypto.h:236
key_state::plaintext_read_buf
struct buffer plaintext_read_buf
Definition: ssl_common.h:232
tls_multi_init_set_options
void tls_multi_init_set_options(struct tls_multi *multi, const char *local, const char *remote)
Definition: ssl.c:1226
packet_id_free
void packet_id_free(struct packet_id *p)
Definition: packet_id.c:102
auth_user_pass_setup
void auth_user_pass_setup(const char *auth_file, bool is_inline, const struct static_challenge_info *sc_info)
Definition: ssl.c:286
tls_wrap_ctx::cleanup_key_ctx
bool cleanup_key_ctx
opt.key_ctx_bi is owned by this context
Definition: ssl_common.h:279
crypto_options
Security parameter state for processing data channel packets.
Definition: crypto.h:230
tls_auth_standalone
Definition: ssl_pkt.h:77
tls_pre_decrypt
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:3499