OpenVPN
ssl_pkt.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  *
10  * This program is free software; you can redistribute it and/or modify
11  * it under the terms of the GNU General Public License version 2
12  * as published by the Free Software Foundation.
13  *
14  * This program is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17  * GNU General Public License for more details.
18  *
19  * You should have received a copy of the GNU General Public License along
20  * with this program; if not, write to the Free Software Foundation, Inc.,
21  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
22  */
23 
31 #ifndef SSL_PKT_H
32 #define SSL_PKT_H
33 
34 #include "buffer.h"
35 #include "ssl_backend.h"
36 #include "ssl_common.h"
37 
38 /* packet opcode (high 5 bits) and key-id (low 3 bits) are combined in one byte */
39 #define P_KEY_ID_MASK 0x07
40 #define P_OPCODE_SHIFT 3
41 
42 /* packet opcodes -- the V1 is intended to allow protocol changes in the future */
43 #define P_CONTROL_HARD_RESET_CLIENT_V1 1 /* initial key from client, forget previous state */
44 #define P_CONTROL_HARD_RESET_SERVER_V1 2 /* initial key from server, forget previous state */
45 #define P_CONTROL_SOFT_RESET_V1 3 /* new key, graceful transition from old to new key */
46 #define P_CONTROL_V1 4 /* control channel packet (usually TLS ciphertext) */
47 #define P_ACK_V1 5 /* acknowledgement for packets received */
48 #define P_DATA_V1 6 /* data channel packet */
49 #define P_DATA_V2 9 /* data channel packet with peer-id */
50 
51 /* indicates key_method >= 2 */
52 #define P_CONTROL_HARD_RESET_CLIENT_V2 7 /* initial key from client, forget previous state */
53 #define P_CONTROL_HARD_RESET_SERVER_V2 8 /* initial key from server, forget previous state */
54 
55 /* indicates key_method >= 2 and client-specific tls-crypt key */
56 #define P_CONTROL_HARD_RESET_CLIENT_V3 10 /* initial key from client, forget previous state */
57 
58 /* Variant of P_CONTROL_V1 but with appended wrapped key
59  * like P_CONTROL_HARD_RESET_CLIENT_V3 */
60 #define P_CONTROL_WKC_V1 11
61 
62 /* define the range of legal opcodes
63  * Since we do no longer support key-method 1 we consider
64  * the v1 op codes invalid */
65 #define P_FIRST_OPCODE 3
66 #define P_LAST_OPCODE 11
67 
68 /*
69  * Define number of buffers for send and receive in the reliability layer.
70  */
71 #define TLS_RELIABLE_N_SEND_BUFFERS 6 /* also window size for reliability layer */
72 #define TLS_RELIABLE_N_REC_BUFFERS 12
73 
74 /*
75  * Used in --mode server mode to check tls-auth signature on initial
76  * packets received from new clients.
77  */
79 {
81  struct buffer workbuf;
82  struct frame frame;
83 };
84 
99 };
100 
107  struct buffer newbuf;
110 };
111 
117 
152 tls_pre_decrypt_lite(const struct tls_auth_standalone *tas,
153  struct tls_pre_decrypt_state *state,
154  const struct link_socket_actual *from,
155  const struct buffer *buf);
156 
157 /* Creates an SHA256 HMAC context with a random key that is used for the
158  * session id.
159  *
160  * We do not support loading this from a config file since continuing session
161  * between restarts of OpenVPN has never been supported and that includes
162  * early session setup.
163  */
165 
177 struct session_id
178 calculate_session_id_hmac(struct session_id client_sid,
179  const struct openvpn_sockaddr *from,
180  hmac_ctx_t *hmac,
181  int handwindow, int offset);
182 
192 bool
194  const struct openvpn_sockaddr *from,
195  hmac_ctx_t *hmac,
196  int handwindow);
197 
198 /*
199  * Write a control channel authentication record.
200  */
201 void
203  struct key_state *ks,
204  struct buffer *buf,
205  struct link_socket_actual **to_link_addr,
206  int opcode,
207  int max_ack,
208  bool prepend_ack);
209 
210 
211 /*
212  * Read a control channel authentication record.
213  */
214 bool
215 read_control_auth(struct buffer *buf,
216  struct tls_wrap_ctx *ctx,
217  const struct link_socket_actual *from,
218  const struct tls_options *opt);
219 
220 
226 struct buffer
228  struct tls_auth_standalone *tas,
229  struct session_id *own_sid,
230  struct session_id *remote_sid,
231  uint8_t header,
232  bool request_resend_wkc);
233 
234 
245 struct buffer
246 extract_command_buffer(struct buffer *buf, struct gc_arena *gc);
247 
248 static inline const char *
250 {
251  switch (op)
252  {
254  return "P_CONTROL_HARD_RESET_CLIENT_V1";
255 
257  return "P_CONTROL_HARD_RESET_SERVER_V1";
258 
260  return "P_CONTROL_HARD_RESET_CLIENT_V2";
261 
263  return "P_CONTROL_HARD_RESET_SERVER_V2";
264 
266  return "P_CONTROL_HARD_RESET_CLIENT_V3";
267 
269  return "P_CONTROL_SOFT_RESET_V1";
270 
271  case P_CONTROL_V1:
272  return "P_CONTROL_V1";
273 
274  case P_CONTROL_WKC_V1:
275  return "P_CONTROL_WKC_V1";
276 
277  case P_ACK_V1:
278  return "P_ACK_V1";
279 
280  case P_DATA_V1:
281  return "P_DATA_V1";
282 
283  case P_DATA_V2:
284  return "P_DATA_V2";
285 
286  default:
287  return "P_???";
288  }
289 }
290 
299 static inline struct tls_wrap_ctx *
301 {
302  /* OpenVPN has the hardcoded assumption in its protocol that
303  * key-id 0 is always first session and renegotiations use key-id
304  * 1 to 7 and wrap around to 1 after that. So key-id > 0 is equivalent
305  * to "this is a renegotiation"
306  */
307  if (key_id > 0 && session->tls_wrap_reneg.mode == TLS_WRAP_CRYPT)
308  {
309  return &session->tls_wrap_reneg;
310  }
311  else
312  {
313  return &session->tls_wrap;
314  }
315 }
316 
317 /* initial packet id (instead of 0) that indicates that the peer supports
318  * early protocol negotiation. This will make the packet id turn a bit faster
319  * but the network time part of the packet id takes care of that. And
320  * this is also a rather theoretical scenario as it still needs more than
321  * 2^31 control channel packets to happen */
322 #define EARLY_NEG_MASK 0xff000000
323 #define EARLY_NEG_START 0x0f000000
324 
325 
326 /* Early negotiation that part of the server response in the RESET_V2 packet.
327  * Since clients that announce early negotiation support will treat the payload
328  * of reset packets special and parse it as TLV messages.
329  * as TLV (type, length, value) */
330 #define TLV_TYPE_EARLY_NEG_FLAGS 0x0001
331 #define EARLY_NEG_FLAG_RESEND_WKC 0x0001
332 #endif /* ifndef SSL_PKT_H */
tls_wrap_ctx::TLS_WRAP_CRYPT
@ TLS_WRAP_CRYPT
Control channel encryption and authentication.
Definition: ssl_common.h:272
VERDICT_VALID_RESET_V2
@ VERDICT_VALID_RESET_V2
This packet is a valid reset packet from the peer (all but tls-crypt-v2)
Definition: ssl_pkt.h:87
tls_reset_standalone
struct buffer tls_reset_standalone(struct tls_wrap_ctx *ctx, struct tls_auth_standalone *tas, struct session_id *own_sid, struct session_id *remote_sid, uint8_t header, bool request_resend_wkc)
This function creates a reset packet using the information from the tls pre decrypt state.
Definition: ssl_pkt.c:428
P_DATA_V2
#define P_DATA_V2
Definition: ssl_pkt.h:49
session_id_hmac_init
hmac_ctx_t * session_id_hmac_init(void)
Definition: ssl_pkt.c:473
ssl_backend.h
VERDICT_INVALID
@ VERDICT_INVALID
the packet failed on of the various checks
Definition: ssl_pkt.h:98
hmac_ctx_t
mbedtls_md_context_t hmac_ctx_t
Generic HMAC context.
Definition: crypto_mbedtls.h:48
P_CONTROL_HARD_RESET_CLIENT_V1
#define P_CONTROL_HARD_RESET_CLIENT_V1
Definition: ssl_pkt.h:43
P_CONTROL_HARD_RESET_CLIENT_V2
#define P_CONTROL_HARD_RESET_CLIENT_V2
Definition: ssl_pkt.h:52
first_packet_verdict
first_packet_verdict
Definition: ssl_pkt.h:85
tls_pre_decrypt_lite
enum first_packet_verdict tls_pre_decrypt_lite(const struct tls_auth_standalone *tas, struct tls_pre_decrypt_state *state, 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_pkt.c:307
P_CONTROL_WKC_V1
#define P_CONTROL_WKC_V1
Definition: ssl_pkt.h:60
VERDICT_VALID_CONTROL_V1
@ VERDICT_VALID_CONTROL_V1
This packet is a valid control packet from the peer.
Definition: ssl_pkt.h:91
openvpn_sockaddr
Definition: socket.h:65
free_tls_pre_decrypt_state
void free_tls_pre_decrypt_state(struct tls_pre_decrypt_state *state)
Definition: ssl_pkt.c:285
tls_auth_standalone::workbuf
struct buffer workbuf
Definition: ssl_pkt.h:81
frame
Packet geometry parameters.
Definition: mtu.h:98
tls_pre_decrypt_state::server_session_id
struct session_id server_session_id
Definition: ssl_pkt.h:109
key_state
Security parameter state of one TLS and data channel key session.
Definition: ssl_common.h:199
tls_pre_decrypt_state::tls_wrap_tmp
struct tls_wrap_ctx tls_wrap_tmp
Definition: ssl_pkt.h:106
session_id
Definition: session_id.h:38
write_control_auth
void write_control_auth(struct tls_session *session, struct key_state *ks, struct buffer *buf, struct link_socket_actual **to_link_addr, int opcode, int max_ack, bool prepend_ack)
Definition: ssl_pkt.c:168
P_CONTROL_HARD_RESET_CLIENT_V3
#define P_CONTROL_HARD_RESET_CLIENT_V3
Definition: ssl_pkt.h:56
P_CONTROL_SOFT_RESET_V1
#define P_CONTROL_SOFT_RESET_V1
Definition: ssl_pkt.h:45
tls_pre_decrypt_state::peer_session_id
struct session_id peer_session_id
Definition: ssl_pkt.h:108
tls_options
Definition: ssl_common.h:297
read_control_auth
bool read_control_auth(struct buffer *buf, struct tls_wrap_ctx *ctx, const struct link_socket_actual *from, const struct tls_options *opt)
Definition: ssl_pkt.c:200
tls_pre_decrypt_state::newbuf
struct buffer newbuf
Definition: ssl_pkt.h:107
tls_wrap_ctx
Control channel wrapping (–tls-auth/–tls-crypt) context.
Definition: ssl_common.h:267
tls_pre_decrypt_state
struct that stores the temporary data for the tls lite decrypt functions
Definition: ssl_pkt.h:105
calculate_session_id_hmac
struct session_id calculate_session_id_hmac(struct session_id client_sid, const struct openvpn_sockaddr *from, hmac_ctx_t *hmac, int handwindow, int offset)
Calculates the HMAC based server session id based on a client session id and socket addr.
Definition: ssl_pkt.c:487
buffer
Wrapper structure for dynamically allocated memory.
Definition: buffer.h:60
check_session_id_hmac
bool check_session_id_hmac(struct tls_pre_decrypt_state *state, const struct openvpn_sockaddr *from, hmac_ctx_t *hmac, int handwindow)
Checks if a control packet has a correct HMAC server session id.
Definition: ssl_pkt.c:529
tls_session
Security parameter state of a single session within a VPN tunnel.
Definition: ssl_common.h:479
buffer.h
gc_arena
Garbage collection arena used to keep track of dynamically allocated memory.
Definition: buffer.h:116
tls_auth_standalone::tls_wrap
struct tls_wrap_ctx tls_wrap
Definition: ssl_pkt.h:80
P_ACK_V1
#define P_ACK_V1
Definition: ssl_pkt.h:47
VERDICT_VALID_RESET_V3
@ VERDICT_VALID_RESET_V3
This is a valid v3 reset (tls-crypt-v2)
Definition: ssl_pkt.h:89
P_CONTROL_V1
#define P_CONTROL_V1
Definition: ssl_pkt.h:46
ssl_common.h
tls_session_get_tls_wrap
static struct tls_wrap_ctx * tls_session_get_tls_wrap(struct tls_session *session, int key_id)
Determines if the current session should use the renegotiation tls wrap struct instead the normal one...
Definition: ssl_pkt.h:300
session
Definition: keyingmaterialexporter.c:56
P_CONTROL_HARD_RESET_SERVER_V1
#define P_CONTROL_HARD_RESET_SERVER_V1
Definition: ssl_pkt.h:44
VERDICT_VALID_ACK_V1
@ VERDICT_VALID_ACK_V1
This packet is a valid ACK control packet from the peer, i.e.
Definition: ssl_pkt.h:94
VERDICT_VALID_WKC_V1
@ VERDICT_VALID_WKC_V1
The packet is a valid control packet with appended wrapped client key.
Definition: ssl_pkt.h:96
P_DATA_V1
#define P_DATA_V1
Definition: ssl_pkt.h:48
extract_command_buffer
struct buffer extract_command_buffer(struct buffer *buf, struct gc_arena *gc)
Extracts a control channel message from buf and adjusts the size of buf after the message has been ex...
Definition: ssl_pkt.c:562
P_CONTROL_HARD_RESET_SERVER_V2
#define P_CONTROL_HARD_RESET_SERVER_V2
Definition: ssl_pkt.h:53
packet_opcode_name
static const char * packet_opcode_name(int op)
Definition: ssl_pkt.h:249
gc
struct gc_arena gc
Definition: test_ssl.c:155
tls_auth_standalone
Definition: ssl_pkt.h:78