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-2025 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, see <https://www.gnu.org/licenses/>.
21 */
22
30#ifndef SSL_PKT_H
31#define SSL_PKT_H
32
33#include "buffer.h"
34#include "ssl_backend.h"
35#include "ssl_common.h"
36
37/* packet opcode (high 5 bits) and key-id (low 3 bits) are combined in one byte */
38#define P_KEY_ID_MASK 0x07
39#define P_OPCODE_SHIFT 3
40
41/* packet opcodes -- the V1 is intended to allow protocol changes in the future */
42#define P_CONTROL_HARD_RESET_CLIENT_V1 1 /* initial key from client, forget previous state */
43#define P_CONTROL_HARD_RESET_SERVER_V1 2 /* initial key from server, forget previous state */
44#define P_CONTROL_SOFT_RESET_V1 3 /* new key, graceful transition from old to new key */
45#define P_CONTROL_V1 4 /* control channel packet (usually TLS ciphertext) */
46#define P_ACK_V1 5 /* acknowledgement for packets received */
47#define P_DATA_V1 6 /* data channel packet */
48#define P_DATA_V2 9 /* data channel packet with peer-id */
49
50/* indicates key_method >= 2 */
51#define P_CONTROL_HARD_RESET_CLIENT_V2 7 /* initial key from client, forget previous state */
52#define P_CONTROL_HARD_RESET_SERVER_V2 8 /* initial key from server, forget previous state */
53
54/* indicates key_method >= 2 and client-specific tls-crypt key */
55#define P_CONTROL_HARD_RESET_CLIENT_V3 10 /* initial key from client, forget previous state */
56
57/* Variant of P_CONTROL_V1 but with appended wrapped key
58 * like P_CONTROL_HARD_RESET_CLIENT_V3 */
59#define P_CONTROL_WKC_V1 11
60
61/* define the range of legal opcodes
62 * Since we do no longer support key-method 1 we consider
63 * the v1 op codes invalid */
64#define P_FIRST_OPCODE 3
65#define P_LAST_OPCODE 11
66
67/*
68 * Define number of buffers for send and receive in the reliability layer.
69 */
70#define TLS_RELIABLE_N_SEND_BUFFERS 6 /* also window size for reliability layer */
71#define TLS_RELIABLE_N_REC_BUFFERS 12
72
73/*
74 * Used in --mode server mode to check tls-auth signature on initial
75 * packets received from new clients.
76 */
83
100
112
114
150 struct tls_pre_decrypt_state *state,
151 const struct link_socket_actual *from,
152 const struct buffer *buf);
153
154/* Creates an SHA256 HMAC context with a random key that is used for the
155 * session id.
156 *
157 * We do not support loading this from a config file since continuing session
158 * between restarts of OpenVPN has never been supported and that includes
159 * early session setup.
160 */
162
174struct session_id calculate_session_id_hmac(struct session_id client_sid,
175 const struct openvpn_sockaddr *from, hmac_ctx_t *hmac,
176 int handwindow, int offset);
177
193bool check_session_hmac_and_pkt_id(struct tls_pre_decrypt_state *state, const struct openvpn_sockaddr *from,
194 hmac_ctx_t *hmac, int handwindow, bool pkt_is_ack);
195
196/*
197 * Write a control channel authentication record.
198 */
199void write_control_auth(struct tls_session *session, struct key_state *ks, struct buffer *buf,
200 struct link_socket_actual **to_link_addr, int opcode, int max_ack,
201 bool prepend_ack);
202
203
213bool read_control_auth(struct buffer *buf, struct tls_wrap_ctx *ctx,
214 const struct link_socket_actual *from, const struct tls_options *opt,
215 bool initial_packet);
216
217
224 struct session_id *own_sid, struct session_id *remote_sid,
225 uint8_t header, bool request_resend_wkc);
226
227
239
240static inline const char *
242{
243 switch (op)
244 {
246 return "P_CONTROL_HARD_RESET_CLIENT_V1";
247
249 return "P_CONTROL_HARD_RESET_SERVER_V1";
250
252 return "P_CONTROL_HARD_RESET_CLIENT_V2";
253
255 return "P_CONTROL_HARD_RESET_SERVER_V2";
256
258 return "P_CONTROL_HARD_RESET_CLIENT_V3";
259
261 return "P_CONTROL_SOFT_RESET_V1";
262
263 case P_CONTROL_V1:
264 return "P_CONTROL_V1";
265
266 case P_CONTROL_WKC_V1:
267 return "P_CONTROL_WKC_V1";
268
269 case P_ACK_V1:
270 return "P_ACK_V1";
271
272 case P_DATA_V1:
273 return "P_DATA_V1";
274
275 case P_DATA_V2:
276 return "P_DATA_V2";
277
278 default:
279 return "P_???";
280 }
281}
282
291static inline struct tls_wrap_ctx *
293{
294 /* OpenVPN has the hardcoded assumption in its protocol that
295 * key-id 0 is always first session and renegotiations use key-id
296 * 1 to 7 and wrap around to 1 after that. So key-id > 0 is equivalent
297 * to "this is a renegotiation"
298 */
299 if (key_id > 0 && session->tls_wrap_reneg.mode == TLS_WRAP_CRYPT)
300 {
301 return &session->tls_wrap_reneg;
302 }
303 else
304 {
305 return &session->tls_wrap;
306 }
307}
308
309/* initial packet id (instead of 0) that indicates that the peer supports
310 * early protocol negotiation. This will make the packet id turn a bit faster
311 * but the network time part of the packet id takes care of that. And
312 * this is also a rather theoretical scenario as it still needs more than
313 * 2^31 control channel packets to happen */
314#define EARLY_NEG_MASK 0xff000000
315#define EARLY_NEG_START 0x0f000000
316
317
318/* Early negotiation that part of the server response in the RESET_V2 packet.
319 * Since clients that announce early negotiation support will treat the payload
320 * of reset packets special and parse it as TLV messages.
321 * as TLV (type, length, value) */
322#define TLV_TYPE_EARLY_NEG_FLAGS 0x0001
323#define EARLY_NEG_FLAG_RESEND_WKC 0x0001
324#endif /* ifndef SSL_PKT_H */
mbedtls_md_context_t hmac_ctx_t
Generic HMAC context.
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:293
Control Channel SSL library backend module.
Control Channel Common Data Structures.
#define P_DATA_V1
Definition ssl_pkt.h:47
#define P_DATA_V2
Definition ssl_pkt.h:48
#define P_ACK_V1
Definition ssl_pkt.h:46
#define P_CONTROL_WKC_V1
Definition ssl_pkt.h:59
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:459
void free_tls_pre_decrypt_state(struct tls_pre_decrypt_state *state)
Definition ssl_pkt.c:271
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:164
#define P_CONTROL_HARD_RESET_CLIENT_V1
Definition ssl_pkt.h:42
hmac_ctx_t * session_id_hmac_init(void)
Definition ssl_pkt.c:445
static const char * packet_opcode_name(int op)
Definition ssl_pkt.h:241
#define P_CONTROL_HARD_RESET_SERVER_V2
Definition ssl_pkt.h:52
#define P_CONTROL_SOFT_RESET_V1
Definition ssl_pkt.h:44
#define P_CONTROL_V1
Definition ssl_pkt.h:45
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:563
first_packet_verdict
Definition ssl_pkt.h:85
@ 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
The packet is a valid control packet with appended wrapped client key.
Definition ssl_pkt.h:96
@ VERDICT_VALID_RESET_V2
This packet is a valid reset packet from the peer (all but tls-crypt-v2)
Definition ssl_pkt.h:87
@ VERDICT_INVALID
the packet failed on of the various checks
Definition ssl_pkt.h:98
@ VERDICT_VALID_RESET_V3
This is a valid v3 reset (tls-crypt-v2)
Definition ssl_pkt.h:89
@ VERDICT_VALID_CONTROL_V1
This packet is a valid control packet from the peer.
Definition ssl_pkt.h:91
bool read_control_auth(struct buffer *buf, struct tls_wrap_ctx *ctx, const struct link_socket_actual *from, const struct tls_options *opt, bool initial_packet)
Read a control channel authentication record.
Definition ssl_pkt.c:192
bool check_session_hmac_and_pkt_id(struct tls_pre_decrypt_state *state, const struct openvpn_sockaddr *from, hmac_ctx_t *hmac, int handwindow, bool pkt_is_ack)
Checks if a control packet has a correct HMAC server session id.
Definition ssl_pkt.c:499
#define P_CONTROL_HARD_RESET_CLIENT_V2
Definition ssl_pkt.h:51
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:403
#define P_CONTROL_HARD_RESET_SERVER_V1
Definition ssl_pkt.h:43
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:292
#define P_CONTROL_HARD_RESET_CLIENT_V3
Definition ssl_pkt.h:55
Wrapper structure for dynamically allocated memory.
Definition buffer.h:60
int len
Length in bytes of the actual content within the allocated memory.
Definition buffer.h:65
Packet geometry parameters.
Definition mtu.h:103
Garbage collection arena used to keep track of dynamically allocated memory.
Definition buffer.h:116
Security parameter state of one TLS and data channel key session.
Definition ssl_common.h:208
struct buffer workbuf
Definition ssl_pkt.h:80
struct tls_wrap_ctx tls_wrap
Definition ssl_pkt.h:79
struct that stores the temporary data for the tls lite decrypt functions
Definition ssl_pkt.h:106
struct session_id peer_session_id
Definition ssl_pkt.h:109
struct session_id server_session_id
Definition ssl_pkt.h:110
struct buffer newbuf
Definition ssl_pkt.h:108
struct tls_wrap_ctx tls_wrap_tmp
Definition ssl_pkt.h:107
Security parameter state of a single session within a VPN tunnel.
Definition ssl_common.h:490
Control channel wrapping (–tls-auth/–tls-crypt) context.
Definition ssl_common.h:276
@ TLS_WRAP_CRYPT
Control channel encryption and authentication.
Definition ssl_common.h:281
struct gc_arena gc
Definition test_ssl.c:154