2 * Routines for WireGuard dissection
3 * Copyright 2018, Peter Wu <peter@lekensteyn.nl>
5 * Wireshark - Network traffic analyzer
6 * By Gerald Combs <gerald@wireshark.org>
7 * Copyright 1998 Gerald Combs
9 * SPDX-License-Identifier: GPL-2.0-or-later
13 * Protocol details: https://www.wireguard.com/protocol/
18 #include <epan/packet.h>
19 #include <epan/expert.h>
20 #include <epan/prefs.h>
21 #include <epan/proto_data.h>
23 void proto_reg_handoff_wg(void);
24 void proto_register_wg(void);
26 static int proto_wg = -1;
27 static int hf_wg_type = -1;
28 static int hf_wg_reserved = -1;
29 static int hf_wg_sender = -1;
30 static int hf_wg_ephemeral = -1;
31 static int hf_wg_encrypted_static = -1;
32 static int hf_wg_encrypted_timestamp = -1;
33 static int hf_wg_mac1 = -1;
34 static int hf_wg_mac2 = -1;
35 static int hf_wg_receiver = -1;
36 static int hf_wg_encrypted_empty = -1;
37 static int hf_wg_nonce = -1;
38 static int hf_wg_encrypted_cookie = -1;
39 static int hf_wg_counter = -1;
40 static int hf_wg_encrypted_packet = -1;
41 static int hf_wg_stream = -1;
42 static int hf_wg_response_in = -1;
43 static int hf_wg_response_to = -1;
45 static gint ett_wg = -1;
47 static expert_field ei_wg_bad_packet_length = EI_INIT;
48 static expert_field ei_wg_keepalive = EI_INIT;
51 // Length of AEAD authentication tag
52 #define AUTH_TAG_LENGTH 16
55 WG_TYPE_HANDSHAKE_INITIATION = 1,
56 WG_TYPE_HANDSHAKE_RESPONSE = 2,
57 WG_TYPE_COOKIE_REPLY = 3,
58 WG_TYPE_TRANSPORT_DATA = 4
61 static const value_string wg_type_names[] = {
62 { 0x01, "Handshake Initiation" },
63 { 0x02, "Handshake Response" },
64 { 0x03, "Cookie Reply" },
65 { 0x04, "Transport Data" },
70 * Information required to process and link messages as required on the first
71 * sequential pass. After that it can be erased.
74 address initiator_address;
75 address responder_address;
76 guint16 initiator_port;
77 guint16 responder_port;
81 * A "session" between two peer is identified by a "sender" id as independently
82 * chosen by each side. In case both peer IDs collide, the source IP and UDP
83 * port number could be used to distinguish sessions. As IDs can be recycled
84 * over time, lookups should use the most recent initiation (or response).
86 * XXX record timestamps (time since last message, for validating timers).
89 guint32 stream; /* Session identifier (akin to udp.stream). */
90 guint32 initiator_frame;
91 guint32 response_frame; /* Responder or Cookie Reply message. */
92 wg_initial_info_t initial; /* Valid only on the first pass. */
95 /* Per-packet state. */
97 wg_session_t *session;
100 /* Map from Sender/Receiver IDs to a list of session information. */
101 static wmem_map_t *sessions;
102 static guint32 wg_session_count;
106 wg_sessions_insert(guint32 id, wg_session_t *session)
108 wmem_list_t *list = (wmem_list_t *)wmem_map_lookup(sessions, GUINT_TO_POINTER(id));
110 list = wmem_list_new(wmem_file_scope());
111 wmem_map_insert(sessions, GUINT_TO_POINTER(id), list);
113 wmem_list_append(list, session);
116 static wg_session_t *
119 wg_session_t *session = wmem_new0(wmem_file_scope(), wg_session_t);
120 session->stream = wg_session_count++;
124 /* Updates the peer address based on the source address. */
126 wg_session_update_address(wg_session_t *session, packet_info *pinfo, gboolean sender_is_initiator)
128 DISSECTOR_ASSERT(!PINFO_FD_VISITED(pinfo));
130 if (sender_is_initiator) {
131 copy_address_wmem(wmem_file_scope(), &session->initial.initiator_address, &pinfo->src);
132 session->initial.initiator_port = (guint16)pinfo->srcport;
134 copy_address_wmem(wmem_file_scope(), &session->initial.responder_address, &pinfo->src);
135 session->initial.responder_port = (guint16)pinfo->srcport;
139 /* Finds an initiation message based on the given Receiver ID that was not
140 * previously associated with a responder message. Returns the session if a
141 * matching initation message can be found or NULL otherwise.
143 static wg_session_t *
144 wg_sessions_lookup_initiation(packet_info *pinfo, guint32 receiver_id)
146 DISSECTOR_ASSERT(!PINFO_FD_VISITED(pinfo));
148 /* Look for the initiation message matching this Receiver ID. */
149 wmem_list_t *list = (wmem_list_t *)wmem_map_lookup(sessions, GUINT_TO_POINTER(receiver_id));
154 /* Walk backwards to find the most recent message first. All packets are
155 * guaranteed to arrive before this frame because this is the first pass. */
156 for (wmem_list_frame_t *item = wmem_list_tail(list); item; item = wmem_list_frame_prev(item)) {
157 wg_session_t *session = (wg_session_t *)wmem_list_frame_data(item);
158 if (session->initial.initiator_port != pinfo->destport ||
159 !addresses_equal(&session->initial.initiator_address, &pinfo->dst)) {
160 /* Responder messages are expected to be sent to the initiator. */
163 if (session->response_frame && session->response_frame != pinfo->num) {
164 /* This session was linked elsewhere. */
168 /* This assumes no malicious messages and no contrived sequences:
169 * Any initiator or responder message is not duplicated nor are these
170 * mutated. If this must be detected, the caller could decrypt or check
171 * mac1 to distinguish valid messages.
179 /* Finds a session with a completed handshake that matches the Receiver ID. */
180 static wg_session_t *
181 wg_sessions_lookup(packet_info *pinfo, guint32 receiver_id, gboolean *receiver_is_initiator)
183 DISSECTOR_ASSERT(!PINFO_FD_VISITED(pinfo));
185 wmem_list_t *list = (wmem_list_t *)wmem_map_lookup(sessions, GUINT_TO_POINTER(receiver_id));
190 /* Walk backwards to find the most recent message first. */
191 for (wmem_list_frame_t *item = wmem_list_tail(list); item; item = wmem_list_frame_prev(item)) {
192 wg_session_t *session = (wg_session_t *)wmem_list_frame_data(item);
193 if (!session->response_frame) {
194 /* Ignore sessions that are not fully established. */
197 if (session->initial.initiator_port == pinfo->destport &&
198 addresses_equal(&session->initial.initiator_address, &pinfo->dst)) {
199 *receiver_is_initiator = TRUE;
200 } else if (session->initial.responder_port == pinfo->destport &&
201 addresses_equal(&session->initial.responder_address, &pinfo->dst)) {
202 *receiver_is_initiator = FALSE;
204 /* Both peers do not match the destination, ignore. */
215 wg_dissect_pubkey(proto_tree *tree, tvbuff_t *tvb, int offset, gboolean is_ephemeral)
217 const guint8 *pubkey = tvb_get_ptr(tvb, offset, 32);
218 gchar *str = g_base64_encode(pubkey, 32);
219 gchar *key_str = wmem_strdup(wmem_packet_scope(), str);
222 int hf_id = is_ephemeral ? hf_wg_ephemeral : -1; // TODO extend for static keys
223 proto_tree_add_string(tree, hf_id, tvb, offset, 32, key_str);
227 wg_dissect_handshake_initiation(tvbuff_t *tvb, packet_info *pinfo, proto_tree *wg_tree, wg_packet_info_t *wg_pinfo)
232 proto_tree_add_item_ret_uint(wg_tree, hf_wg_sender, tvb, 4, 4, ENC_LITTLE_ENDIAN, &sender_id);
233 col_append_fstr(pinfo->cinfo, COL_INFO, ", sender=0x%08X", sender_id);
234 wg_dissect_pubkey(wg_tree, tvb, 8, TRUE);
235 proto_tree_add_item(wg_tree, hf_wg_encrypted_static, tvb, 40, 32 + AUTH_TAG_LENGTH, ENC_NA);
236 proto_tree_add_item(wg_tree, hf_wg_encrypted_timestamp, tvb, 88, 12 + AUTH_TAG_LENGTH, ENC_NA);
237 proto_tree_add_item(wg_tree, hf_wg_mac1, tvb, 116, 16, ENC_NA);
238 proto_tree_add_item(wg_tree, hf_wg_mac2, tvb, 132, 16, ENC_NA);
240 if (!PINFO_FD_VISITED(pinfo)) {
241 /* XXX should an initiation message with the same contents (except MAC2) be
242 * considered part of the same "session"? */
243 wg_session_t *session = wg_session_new();
244 session->initiator_frame = pinfo->num;
245 wg_session_update_address(session, pinfo, TRUE);
246 wg_sessions_insert(sender_id, session);
247 wg_pinfo->session = session;
249 wg_session_t *session = wg_pinfo->session;
251 ti = proto_tree_add_uint(wg_tree, hf_wg_stream, tvb, 0, 0, session->stream);
252 PROTO_ITEM_SET_GENERATED(ti);
254 if (session && session->response_frame) {
255 ti = proto_tree_add_uint(wg_tree, hf_wg_response_in, tvb, 0, 0, session->response_frame);
256 PROTO_ITEM_SET_GENERATED(ti);
263 wg_dissect_handshake_response(tvbuff_t *tvb, packet_info *pinfo, proto_tree *wg_tree, wg_packet_info_t *wg_pinfo)
265 guint32 sender_id, receiver_id;
268 proto_tree_add_item_ret_uint(wg_tree, hf_wg_sender, tvb, 4, 4, ENC_LITTLE_ENDIAN, &sender_id);
269 col_append_fstr(pinfo->cinfo, COL_INFO, ", sender=0x%08X", sender_id);
270 proto_tree_add_item_ret_uint(wg_tree, hf_wg_receiver, tvb, 8, 4, ENC_LITTLE_ENDIAN, &receiver_id);
271 col_append_fstr(pinfo->cinfo, COL_INFO, ", receiver=0x%08X", receiver_id);
272 wg_dissect_pubkey(wg_tree, tvb, 12, TRUE);
273 proto_tree_add_item(wg_tree, hf_wg_encrypted_empty, tvb, 44, 16, ENC_NA);
274 proto_tree_add_item(wg_tree, hf_wg_mac1, tvb, 60, 16, ENC_NA);
275 proto_tree_add_item(wg_tree, hf_wg_mac2, tvb, 76, 16, ENC_NA);
277 wg_session_t *session;
278 if (!PINFO_FD_VISITED(pinfo)) {
279 session = wg_sessions_lookup_initiation(pinfo, receiver_id);
280 /* XXX should probably check whether decryption succeeds before linking
281 * and somehow mark that this response is related but not correct. */
283 session->response_frame = pinfo->num;
284 wg_session_update_address(session, pinfo, FALSE);
285 wg_sessions_insert(sender_id, session);
286 wg_pinfo->session = session;
289 session = wg_pinfo->session;
292 ti = proto_tree_add_uint(wg_tree, hf_wg_stream, tvb, 0, 0, session->stream);
293 PROTO_ITEM_SET_GENERATED(ti);
294 ti = proto_tree_add_uint(wg_tree, hf_wg_response_to, tvb, 0, 0, session->initiator_frame);
295 PROTO_ITEM_SET_GENERATED(ti);
302 wg_dissect_handshake_cookie(tvbuff_t *tvb, packet_info *pinfo, proto_tree *wg_tree, wg_packet_info_t *wg_pinfo)
307 proto_tree_add_item_ret_uint(wg_tree, hf_wg_receiver, tvb, 4, 4, ENC_LITTLE_ENDIAN, &receiver_id);
308 col_append_fstr(pinfo->cinfo, COL_INFO, ", receiver=0x%08X", receiver_id);
309 proto_tree_add_item(wg_tree, hf_wg_nonce, tvb, 8, 24, ENC_NA);
310 proto_tree_add_item(wg_tree, hf_wg_encrypted_cookie, tvb, 32, 16 + AUTH_TAG_LENGTH, ENC_NA);
312 wg_session_t *session;
313 if (!PINFO_FD_VISITED(pinfo)) {
314 /* Check for Cookie Reply from Responder to Initiator. */
315 session = wg_sessions_lookup_initiation(pinfo, receiver_id);
317 session->response_frame = pinfo->num;
318 wg_session_update_address(session, pinfo, FALSE);
319 wg_pinfo->session = session;
321 /* XXX check for cookie reply from Initiator to Responder */
323 session = wg_pinfo->session;
326 ti = proto_tree_add_uint(wg_tree, hf_wg_stream, tvb, 0, 0, session->stream);
327 PROTO_ITEM_SET_GENERATED(ti);
328 /* XXX check for cookie reply from Initiator to Responder */
329 ti = proto_tree_add_uint(wg_tree, hf_wg_response_to, tvb, 0, 0, session->initiator_frame);
330 PROTO_ITEM_SET_GENERATED(ti);
337 wg_dissect_data(tvbuff_t *tvb, packet_info *pinfo, proto_tree *wg_tree, wg_packet_info_t *wg_pinfo)
343 proto_tree_add_item_ret_uint(wg_tree, hf_wg_receiver, tvb, 4, 4, ENC_LITTLE_ENDIAN, &receiver_id);
344 col_append_fstr(pinfo->cinfo, COL_INFO, ", receiver=0x%08X", receiver_id);
345 proto_tree_add_item_ret_uint64(wg_tree, hf_wg_counter, tvb, 8, 8, ENC_LITTLE_ENDIAN, &counter);
346 col_append_fstr(pinfo->cinfo, COL_INFO, ", counter=%" G_GUINT64_FORMAT, counter);
348 gint packet_length = tvb_captured_length_remaining(tvb, 16);
349 if (packet_length < AUTH_TAG_LENGTH) {
350 proto_tree_add_expert(wg_tree, pinfo, &ei_wg_bad_packet_length, tvb, 16, packet_length);
351 return 16 + packet_length;
352 } else if (packet_length != AUTH_TAG_LENGTH) {
353 /* Keepalive messages are already marked, no need to append data length. */
354 col_append_fstr(pinfo->cinfo, COL_INFO, ", datalen=%d", packet_length - AUTH_TAG_LENGTH);
356 ti = proto_tree_add_item(wg_tree, hf_wg_encrypted_packet, tvb, 16, packet_length, ENC_NA);
358 if (packet_length == AUTH_TAG_LENGTH) {
359 expert_add_info(pinfo, ti, &ei_wg_keepalive);
362 wg_session_t *session;
363 if (!PINFO_FD_VISITED(pinfo)) {
364 gboolean receiver_is_initiator;
365 session = wg_sessions_lookup(pinfo, receiver_id, &receiver_is_initiator);
367 wg_session_update_address(session, pinfo, !receiver_is_initiator);
368 wg_pinfo->session = session;
371 session = wg_pinfo->session;
374 ti = proto_tree_add_uint(wg_tree, hf_wg_stream, tvb, 0, 0, session->stream);
375 PROTO_ITEM_SET_GENERATED(ti);
378 return 16 + packet_length;
382 dissect_wg(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void *data _U_)
386 guint32 message_type;
387 const char *message_type_str;
388 wg_packet_info_t *wg_pinfo;
390 /* Heuristics check: check for reserved bits (zeros) and message type. */
391 if (tvb_reported_length(tvb) < 4 || tvb_get_ntoh24(tvb, 1) != 0)
394 message_type = tvb_get_guint8(tvb, 0);
395 message_type_str = try_val_to_str(message_type, wg_type_names);
396 if (!message_type_str)
399 /* Special case: zero-length data message is a Keepalive message. */
400 if (message_type == WG_TYPE_TRANSPORT_DATA && tvb_reported_length(tvb) == 32) {
401 message_type_str = "Keepalive";
404 col_set_str(pinfo->cinfo, COL_PROTOCOL, "WireGuard");
405 col_set_str(pinfo->cinfo, COL_INFO, message_type_str);
407 ti = proto_tree_add_item(tree, proto_wg, tvb, 0, -1, ENC_NA);
408 wg_tree = proto_item_add_subtree(ti, ett_wg);
410 proto_tree_add_item(wg_tree, hf_wg_type, tvb, 0, 1, ENC_NA);
411 proto_tree_add_item(wg_tree, hf_wg_reserved, tvb, 1, 3, ENC_NA);
413 if (!PINFO_FD_VISITED(pinfo)) {
414 wg_pinfo = wmem_new0(wmem_file_scope(), wg_packet_info_t);
415 p_add_proto_data(wmem_file_scope(), pinfo, proto_wg, 0, wg_pinfo);
417 wg_pinfo = (wg_packet_info_t *)p_get_proto_data(wmem_file_scope(), pinfo, proto_wg, 0);
420 switch ((wg_message_type)message_type) {
421 case WG_TYPE_HANDSHAKE_INITIATION:
422 return wg_dissect_handshake_initiation(tvb, pinfo, wg_tree, wg_pinfo);
423 case WG_TYPE_HANDSHAKE_RESPONSE:
424 return wg_dissect_handshake_response(tvb, pinfo, wg_tree, wg_pinfo);
425 case WG_TYPE_COOKIE_REPLY:
426 return wg_dissect_handshake_cookie(tvb, pinfo, wg_tree, wg_pinfo);
427 case WG_TYPE_TRANSPORT_DATA:
428 return wg_dissect_data(tvb, pinfo, wg_tree, wg_pinfo);
431 DISSECTOR_ASSERT_NOT_REACHED();
437 wg_session_count = 0;
441 proto_register_wg(void)
443 expert_module_t *expert_wg;
445 static hf_register_info hf[] = {
446 /* Initiation message */
449 FT_UINT8, BASE_DEC, VALS(wg_type_names), 0x0,
453 { "Reserved", "wg.reserved",
454 FT_NONE, BASE_NONE, NULL, 0x0,
458 { "Sender", "wg.sender",
459 FT_UINT32, BASE_HEX, NULL, 0x0,
460 "Identifier as chosen by the sender", HFILL }
463 { "Ephemeral", "wg.ephemeral",
464 FT_STRING, BASE_NONE, NULL, 0x0,
465 "Ephemeral public key of sender", HFILL }
467 { &hf_wg_encrypted_static,
468 { "Encrypted Static", "wg.encrypted_static",
469 FT_NONE, BASE_NONE, NULL, 0x0,
470 "Encrypted long-term static public key of sender", HFILL }
472 { &hf_wg_encrypted_timestamp,
473 { "Encrypted Timestamp", "wg.encrypted_timestamp",
474 FT_NONE, BASE_NONE, NULL, 0x0,
479 FT_BYTES, BASE_NONE, NULL, 0x0,
484 FT_BYTES, BASE_NONE, NULL, 0x0,
488 /* Response message */
490 { "Receiver", "wg.receiver",
491 FT_UINT32, BASE_HEX, NULL, 0x0,
492 "Identifier as chosen by receiver", HFILL }
494 { &hf_wg_encrypted_empty,
495 { "Encrypted Empty", "wg.encrypted_empty",
496 FT_NONE, BASE_NONE, NULL, 0x0,
497 "Authenticated encryption of an empty string", HFILL }
502 { "Nonce", "wg.nonce",
503 FT_BYTES, BASE_NONE, NULL, 0x0,
506 { &hf_wg_encrypted_cookie,
507 { "Encrypted Cookie", "wg.encrypted_cookie",
508 FT_BYTES, BASE_NONE, NULL, 0x0,
511 /* TODO decrypted cookie field. */
515 { "Counter", "wg.counter",
516 FT_UINT64, BASE_DEC, NULL, 0x0,
519 { &hf_wg_encrypted_packet,
520 { "Encrypted Packet", "wg.encrypted_packet",
521 FT_NONE, BASE_NONE, NULL, 0x0,
525 /* Association tracking. */
527 { "Stream index", "wg.stream",
528 FT_UINT32, BASE_DEC, NULL, 0x0,
529 "Identifies a session in this capture file", HFILL }
531 { &hf_wg_response_in,
532 { "Response in Frame", "wg.response_in",
533 FT_FRAMENUM, BASE_NONE, FRAMENUM_TYPE(FT_FRAMENUM_RESPONSE), 0x0,
534 "The response to this initiation message is in this frame", HFILL }
536 { &hf_wg_response_to,
537 { "Response to Frame", "wg.response_to",
538 FT_FRAMENUM, BASE_NONE, FRAMENUM_TYPE(FT_FRAMENUM_REQUEST), 0x0,
539 "This is a response to the initiation message in this frame", HFILL }
543 static gint *ett[] = {
547 static ei_register_info ei[] = {
548 { &ei_wg_bad_packet_length,
549 { "wg.bad_packet_length", PI_MALFORMED, PI_ERROR,
550 "Packet length is too small", EXPFILL }
553 { "wg.keepalive", PI_SEQUENCE, PI_CHAT,
554 "This is a Keepalive message", EXPFILL }
558 proto_wg = proto_register_protocol("WireGuard Protocol", "WireGuard", "wg");
560 proto_register_field_array(proto_wg, hf, array_length(hf));
561 proto_register_subtree_array(ett, array_length(ett));
563 expert_wg = expert_register_protocol(proto_wg);
564 expert_register_field_array(expert_wg, ei, array_length(ei));
566 register_dissector("wg", dissect_wg, proto_wg);
568 register_init_routine(wg_init);
569 sessions = wmem_map_new_autoreset(wmem_epan_scope(), wmem_file_scope(), g_direct_hash, g_direct_equal);
573 proto_reg_handoff_wg(void)
575 heur_dissector_add("udp", dissect_wg, "WireGuard", "wg", proto_wg, HEURISTIC_ENABLE);
579 * Editor modelines - https://www.wireshark.org/tools/modelines.html
584 * indent-tabs-mode: nil
587 * vi: set shiftwidth=4 tabstop=8 expandtab:
588 * :indentSize=4:tabSize=8:noTabs=true: