3 --- Wireshark protocol dissector for TrIPE
5 --- (c) 2017 Straylight/Edgeware
8 -------- Licensing notice ---------------------------------------------------
10 --- This file is part of Trivial IP Encryption (TrIPE).
12 --- TrIPE is free software: you can redistribute it and/or modify it under
13 --- the terms of the GNU General Public License as published by the Free
14 --- Software Foundation; either version 3 of the License, or (at your
15 --- option) any later version.
17 --- TrIPE is distributed in the hope that it will be useful, but WITHOUT
18 --- ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
19 --- FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
22 --- You should have received a copy of the GNU General Public License
23 --- along with TrIPE. If not, see <https://www.gnu.org/licenses/>.
25 local tripe = Proto("tripe", "TrIPE VPN")
27 -----------------------------------------------------------------------------
28 --- Configuration handling.
31 -- Information about the configuration variables. This table, when it's
32 -- set up, maps the internal names, which are used to refer to
33 -- configuration variables in the rest of this code, to a little structure:
35 -- * `var' names the variable, and is the usual key for lookups;
37 -- * `name' is the label used in the dialogue box;
39 -- * `type' is the type of variable, currently either `enum' or `int';
41 -- * `descr' is a longer (but generally fairly useless) description for
44 -- * `allowed' is a sequence of allowed values for an `enum' variable;
47 -- * `min' and `max' are the limits on permitted values for an `int'
48 -- variable (and may be omitted).
50 -- More slots are added at runtime:
52 -- * `map' is a table mapping string values to their integer indices, as
53 -- stored in Wireshark's preferences database.
55 -- Initially, though, the table is given as a sequence, so that the
56 -- preferences can be populated in a consistent (and approximately logical)
59 { var = "bulk", name = "Bulk transform",
60 type = "enum", allowed = { "v0", "iiv", "naclbox" },
61 descr = "Bulk cryptographic transform", default = "v0" },
62 { var = "hashsz", name = "Hash length", type = "int", min = 0,
63 descr = "Hash length (bytes)", default = 20 },
64 { var = "tagsz", name = "Tag length", type = "int", min = 0,
65 descr = "Authentication tag length (bytes)", default = 10 },
66 { var = "ivsz", name = "IV length", type = "int", min = 0,
67 descr = "Initialization vector length (bytes)", default = 8 },
68 { var = "kx", name = "Key-exchange group",
69 type = "enum", allowed = { "dh", "ec", "x25519", "x448" },
70 descr = "Key-exchange group type", default = "dh" },
71 { var = "scsz", name = "Scalar length", type = "int", min = 1,
72 descr = "Scalar field-element length (bytes)", default = 32 },
75 local C = { } -- The working values of the configuration variables.
77 local function set_config(k, v)
78 -- Set configuration variable K to the value V.
80 -- K is a string naming the variable to set. V is the new value, which may
81 -- be a string or a number.
83 -- For `int' variables, V is converted to a number if necessary, and then
84 -- checked against the permitted bounds.
86 -- For `enum' variables, things are more complicated. If V is a string,
87 -- it's checked against the permitted values. If V is a number, it's
88 -- converted back into the corresponding string.
90 local info = CONFIG[k]
92 if info == nil then error("unknown config key `" .. k .. "'") end
94 if info.type == "enum" then
95 if type(v) == "number" then
96 local t = info.allowed[v]
98 error(string.format("bad index %d for `%s'", n, k))
102 if info.map[v] == nil then
103 error(string.format("bad value `%s' for `%s'", v, k))
107 elseif info.type == "int" then
108 local n = tonumber(v)
109 if n == nil then error("bad number `" .. v .. "'") end
110 if n ~= math.floor(n) then
111 error("value `" .. v .. "' is not an integer")
113 if (info.min ~= nil and n < info.min) or
114 (info.max ~= nil and n > info.max)
116 error(string.format("value %d out of range for `%s'", n, k))
124 -- Set up the configuration information. Configure preferences objects on
125 -- the dissector. For `enum' variables, build the `map' slots.
126 for i, v in ipairs(CONFIG) do
129 if v.type == "enum" then
132 for i, t in pairs(v.allowed) do
136 tripe.prefs[k] = Pref.enum(v.name, v.map[v.default], v.descr, tab)
137 elseif v.type == "int" then
138 tripe.prefs[k] = Pref.uint(v.name, v.default, v.descr)
142 local function prefs_changed()
143 -- Notice that the preferences have been changed and update `C'.
145 for k, _ in pairs(CONFIG) do
146 if type(k) == "string" then set_config(k, tripe.prefs[k]) end
149 tripe.prefs_changed = prefs_changed
151 -- Populate the configuration table from the stored preferences or their
155 -- Now work through arguments passed in on the command line. Annoyingly,
156 -- while one can set preferences on the Wireshark command line, these are
157 -- done /before/ Lua scripts are loaded, so the silly thing thinks the
158 -- preference slots don't exist. So we have to do it a different way.
159 for _, arg in ipairs({...}) do
160 local k, v = arg:match("(.+)=(.+)")
161 if k == nil or v == nil then error("bad option syntax `" .. arg .. "'") end
165 -----------------------------------------------------------------------------
166 --- Protocol dissection primitives.
168 local PF = { } -- The table of protocol fields, filled in later.
170 -- The `dissect_*' functions follow a common protocol. They parse a thing
171 -- from a packet buffer BUF, of size SZ, starting from POS, and store
172 -- interesting things in a given TREE; when they're done, they return the
173 -- updated index where the next interesting thing might be. As a result,
174 -- it's usually a simple matter to parse a packet by invoking the appropriate
175 -- primitive dissectors in the right order.
177 local function dissect_wtf(buf, tree, pos, sz)
178 -- If POS is not at the end of the buffer, note that there's unexpected
179 -- stuff in the packet.
181 if pos < sz then tree:add(PF["tripe.wtf"], buf(pos, sz - pos)) end
185 -- Dissect a ciphertext of some particular kind.
186 local dissect_ct = { }
187 function dissect_ct.naclbox(buf, tree, pos, sz)
188 tree:add(PF["tripe.ciphertext.tag"], buf(pos, 16)); pos = pos + 16
189 tree:add(PF["tripe.ciphertext.seq"], buf(pos, 4)); pos = pos + 4
190 tree:add(PF["tripe.ciphertext.body"], buf(pos, sz - pos))
192 function dissect_ct.iiv(buf, tree, pos, sz)
193 tree:add(PF["tripe.ciphertext.tag"], buf(pos, C.tagsz)); pos = pos + C.tagsz
194 tree:add(PF["tripe.ciphertext.seq"], buf(pos, 4)); pos = pos + 4
195 tree:add(PF["tripe.ciphertext.body"], buf(pos, sz - pos))
197 function dissect_ct.v0(buf, tree, pos, sz)
198 tree:add(PF["tripe.ciphertext.tag"], buf(pos, C.tagsz)); pos = pos + C.tagsz
199 tree:add(PF["tripe.ciphertext.seq"], buf(pos, 4)); pos = pos + 4
200 tree:add(PF["tripe.ciphertext.iv"], buf(pos, C.ivsz)); pos = pos + C.ivsz
201 tree:add(PF["tripe.ciphertext.body"], buf(pos, sz - pos))
204 local function dissect_ciphertext(buf, tree, label, pos, sz)
205 -- Dissect a ciphertext, making the whole thing be a little subtree with
208 local t = tree:add(PF[label], buf(pos, sz - pos))
209 dissect_ct[C.bulk](buf, t, pos, sz)
213 local function dissect_packet(buf, tree, pos, sz)
214 return dissect_ciphertext(buf, tree, "tripe.packet.payload", pos, sz)
217 -- Dissect a group element of some particular kind.
218 local dissect_ge = { }
219 function dissect_ge.dh(buf, tree, pos, sz)
220 tree:add(PF["tripe.dh.len"], buf(pos, 2))
221 xsz = buf(pos, 2):uint(); pos = pos + 2
222 tree:add(PF["tripe.dh.x"], buf(pos, xsz)); pos = pos + xsz
225 function dissect_ge.ec(buf, tree, pos, sz)
226 tree:add(PF["tripe.ec.xlen"], buf(pos, 2))
227 xsz = buf(pos, 2):uint(); pos = pos + 2
228 tree:add(PF["tripe.ec.x"], buf(pos, xsz)); pos = pos + xsz
229 tree:add(PF["tripe.ec.ylen"], buf(pos, 2))
230 ysz = buf(pos, 2):uint(); pos = pos + 2
231 tree:add(PF["tripe.ec.y"], buf(pos, ysz)); pos = pos + ysz
234 function dissect_ge.x25519(buf, tree, pos, sz)
235 tree:add(PF["tripe.x25519.x"], buf(pos, 32))
238 function dissect_ge.x448(buf, tree, pos, sz)
239 tree:add(PF["tripe.x448.x"], buf(pos, 56))
243 local function dissect_my_challenge(buf, tree, pos, sz)
244 -- We don't know how long the group element is going to be. We can set the
245 -- length later, but (at least in older versions) it doesn't work so well
246 -- to increase the length, so make it large to start out, and shrink it
248 local t = tree:add(PF["tripe.keyexch.mychal"], buf(pos, sz - pos))
249 local q = dissect_ge[C.kx](buf, t, pos, sz)
254 local function dissect_my_cookie(buf, tree, pos, sz)
255 tree:add(PF["tripe.keyexch.mycookie"], buf(pos, C.hashsz))
256 return pos + C.hashsz
259 local function dissect_your_cookie(buf, tree, pos, sz)
260 tree:add(PF["tripe.keyexch.yourcookie"], buf(pos, C.hashsz))
261 return pos + C.hashsz
264 local kx_scsz = { x25519 = 32, x448 = 56 } -- Hardwired scalar sizes.
265 local function dissect_check(buf, tree, pos, sz)
266 local scsz = kx_scsz[C.kx] or C.scsz
267 tree:add(PF["tripe.keyexch.check"], buf(pos, scsz))
271 local function dissect_reply(buf, tree, pos, sz)
272 return dissect_ciphertext(buf, tree, "tripe.keyexch.reply", pos, sz)
275 local function dissect_switch(buf, tree, pos, sz)
276 return dissect_ciphertext(buf, tree, "tripe.keyexch.switch", pos, sz)
279 local function dissect_switchok(buf, tree, pos, sz)
280 return dissect_ciphertext(buf, tree, "tripe.keyexch.switchok", pos, sz)
283 local function dissect_misc_payload(buf, tree, pos, sz)
284 tree:add(PF["tripe.misc.payload"], buf(pos, sz - pos))
288 local function dissect_misc_ciphertext(buf, tree, pos, sz)
289 return dissect_ciphertext(buf, tree, "tripe.misc.ciphertext", pos, sz)
292 local function dissect_chal(buf, tree, label, pos, sz)
293 local len = buf(pos, 2):uint()
294 local t = tree:add(PF[label], buf(pos, len + 2))
295 t:add(PF["tripe.chal.len"], buf(pos, 2)); pos = pos + 2
296 t:add(PF["tripe.chal.sequence"], buf(pos, 4)); pos = pos + 4; len = len - 4
297 t:add(PF["tripe.chal.tag"], buf(pos, len))
301 local function dissect_my_chal(buf, tree, pos, sz)
302 return dissect_chal(buf, tree, "tripe.knock.mychal", pos, sz)
305 local function dissect_your_chal(buf, tree, pos, sz)
306 return dissect_chal(buf, tree, "tripe.knock.yourchal", pos, sz)
309 local function dissect_keyid(buf, tree, pos, sz)
310 tree:add(PF["tripe.knock.keyid"], buf(pos, 4))
314 local function dissect_ies(buf, tree, pos, sz)
315 local len = buf(pos, 2):uint()
316 local lim = pos + len + 2
317 local t = tree:add(PF["tripe.knock.ies"], buf(pos, len + 2))
318 t:add(PF["tripe.ies.len"], buf(pos, 2)); pos = pos + 2
319 pos = dissect_ge[C.kx](buf, t, pos, sz)
320 return dissect_ciphertext(buf, t, "tripe.ies.ciphertext", pos, lim)
323 -----------------------------------------------------------------------------
324 --- The protocol information table.
327 -- This is the main table which describes the protocol. The top level maps
328 -- category codes to structures:
330 -- * `label' is the category code's symbolic name;
332 -- * `subtype' is the field name for the subtype code;
334 -- * `info' is a prefix for the information column display; and
336 -- * `sub' is a table describing the individual subtypes.
338 -- The subtype table similarly maps subtype codes to structures:
340 -- * `label' is the subtype code's symbolic name;
342 -- * `info' is the suffix for the information column display; and
344 -- * `dissect' is a sequence of primitive dissectors to run in order to
345 -- parse the rest of the packet.
348 label = "MSG_PACKET", subtype = "tripe.packet.type",
349 info = "Packet data",
351 [0] = { label = "PACKET_IP", info = "encapsulated IP datagram",
352 dissect = { dissect_packet} }
357 label = "MSG_KEYEXCH", subtype = "tripe.keyexch.type",
358 info = "Key exchange",
360 [0] = { label = "KX_PRECHAL", info = "pre-challenge",
361 dissect = { dissect_my_challenge,
363 [1] = { label = "KX_CHAL", info = "challenge",
364 dissect = { dissect_my_challenge,
368 [2] = { label = "KX_REPLY", info = "reply",
369 dissect = { dissect_my_challenge,
373 [3] = { label = "KX_SWITCH", info = "switch",
374 dissect = { dissect_my_cookie,
377 [4] = { label = "KX_SWITCHOK", info = "switch-ok",
378 dissect = { dissect_switchok } },
379 [5] = { label = "KX_TOKENRQ", info = "token-rq",
380 dissect = { dissect_my_chal,
383 [6] = { label = "KX_TOKEN", info = "token",
384 dissect = { dissect_your_chal,
387 [7] = { label = "KX_KNOCK", info = "knock",
388 dissect = { dissect_your_chal,
391 dissect_my_challenge } }
396 label = "MSG_MISC", subtype = "tripe.misc.type",
397 info = "Miscellaneous",
399 [0] = { label = "MISC_NOP", info = "no-operation (keepalive)",
400 dissect = { dissect_misc_payload } },
401 [1] = { label = "MISC_PING", info = "transport-level ping",
402 dissect = { dissect_misc_payload } },
403 [2] = { label = "MISC_PONG", info = "transport-level ping reply",
404 dissect = { dissect_misc_payload } },
405 [3] = { label = "MISC_EPING", info = "crypto-level ping",
406 dissect = { dissect_misc_ciphertext } },
407 [4] = { label = "MISC_EPONG", info = "crypto-level ping reply",
408 dissect = { dissect_misc_ciphertext } },
409 [5] = { label = "MISC_GREET", info = "greeting",
410 dissect = { dissect_misc_payload } },
411 [6] = { label = "MISC_BYE", info = "disconnect notification",
412 dissect = { dissect_misc_ciphertext } },
418 -- Work through the master table and build `cattab' and `subtab' tables,
419 -- mapping category and subtype codes to their symbolic names for
420 -- presentation. The `subtab' is a two-level table, needing two layers of
424 for i, v in pairs(PKTINFO) do
428 for j, w in pairs(v.sub) do
429 subtab[i][j] = w.label
435 -- The protocol fields. This table maps the field names to structures
436 -- used to build the fields, which are then stored in `PF' (declared way
439 -- * `name' is the field name to show in the dissector tree view;
441 -- * `type' is the field type;
443 -- * `base' is a tweak describing how the field should be formatted;
445 -- * `mask' is used to single out a piece of a larger bitfield; and
447 -- * `tab' names a mapping table used to convert numerical values to
451 name = "Message type", type = ftypes.UINT8, base = base.HEX
454 name = "Message category", type = ftypes.UINT8, base = base.DEC,
455 mask = 0xf0, tab = cattab
457 ["tripe.packet.type"] = {
458 name = "Packet subcode", type = ftypes.UINT8, base = base.DEC,
459 mask = 0x0f, tab = subtab[0]
461 ["tripe.packet.payload"] = {
462 name = "Encrypted packet", type = ftypes.NONE
464 ["tripe.knock.keyid"] = {
465 name = "Short key indicator", type = ftypes.UINT32, base = base.HEX
467 ["tripe.knock.mychal"] = {
468 name = "Sender's one-time challenge", type = ftypes.NONE
470 ["tripe.knock.yourchal"] = {
471 name = "Recipient's one-time challenge", type = ftypes.NONE
473 ["tripe.chal.len"] = {
474 name = "Challenge length", type = ftypes.UINT16, base = base.DEC
476 ["tripe.chal.sequence"] = {
477 name = "Challenge sequence number",
478 type = ftypes.UINT32, base = base.DEC
480 ["tripe.chal.tag"] = {
481 name = "Challenge tag", type = ftypes.BYTES, base = base.SPACE
483 ["tripe.knock.ies"] = {
484 name = "Encrypted message", type = ftypes.NONE
486 ["tripe.ies.len"] = {
487 name = "Encrypted message length",
488 type = ftypes.UINT16, base = base.DEC
490 ["tripe.ies.clue"] = {
491 name = "Encrypted message KEM clue",
492 type = ftypes.BYTES, base = base.SPACE
494 ["tripe.ies.ciphertext"] = {
495 name = "Encrypted message ciphertext",
496 type = ftypes.BYTES, base = base.SPACE
498 ["tripe.keyexch.type"] = {
499 name = "Key-exchange subcode", type = ftypes.UINT8, base = base.DEC,
500 mask = 0x0f, tab = subtab[1]
502 ["tripe.keyexch.mychal"] = {
503 name = "Sender's challenge R = r P", type = ftypes.NONE
505 ["tripe.keyexch.mycookie"] = {
506 name = "Hash of recipient's challenge = H(R, ...)",
507 type = ftypes.BYTES, base = base.SPACE
509 ["tripe.keyexch.yourcookie"] = {
510 name = "Hash of sender's challenge = H(R', ...)",
511 type = ftypes.BYTES, base = base.SPACE
513 ["tripe.keyexch.reply"] = {
514 name = "Encrypted reply = k R'", type = ftypes.NONE
516 ["tripe.keyexch.switch"] = {
517 name = "Encrypted reply and switch request = k R', H(...)",
520 ["tripe.keyexch.switchok"] = {
521 name = "Encrypted switch confirmation = H(...)", type = ftypes.NONE
523 ["tripe.misc.type"] = {
524 name = "Miscellenaous subcode", type = ftypes.UINT8, base = base.DEC,
525 mask = 0x0f, tab = subtab[2]
527 ["tripe.misc.payload"] = {
528 name = "Miscellaneous payload",
529 type = ftypes.BYTES, base = base.SPACE
531 ["tripe.misc.ciphertext"] = {
532 name = "Miscellaneous encrypted payload", type = ftypes.NONE
535 name = "Unexpected trailing data",
536 type = ftypes.BYTES, base = base.SPACE
538 ["tripe.keyexch.check"] = {
539 name = "Sender's challenge check value = r XOR H(r K', ...)",
540 type = ftypes.BYTES, base = base.SPACE
542 ["tripe.ciphertext.seq"] = {
543 name = "Sequence number", type = ftypes.UINT32, base = base.DEC
545 ["tripe.ciphertext.iv"] = {
546 name = "Initialization vector", type = ftypes.BYTES, base = base.SPACE
548 ["tripe.ciphertext.tag"] = {
549 name = "Authentication tag", type = ftypes.BYTES, base = base.SPACE
551 ["tripe.ciphertext.body"] = {
552 name = "Encrypted data", type = ftypes.BYTES, base = base.SPACE
555 name = "DH group element length",
556 type = ftypes.UINT16, base = base.DEC
559 name = "DH group element value",
560 type = ftypes.BYTES, base = base.SPACE
562 ["tripe.ec.xlen"] = {
563 name = "Elliptic curve x-coordinate length",
564 type = ftypes.UINT16, base = base.DEC
567 name = "Elliptic curve x-coordinate value",
568 type = ftypes.BYTES, base = base.SPACE
570 ["tripe.ec.ylen"] = {
571 name = "Elliptic curve y-coordinate length",
572 type = ftypes.UINT16, base = base.DEC
575 name = "Elliptic curve y-coordinate value",
576 type = ftypes.BYTES, base = base.SPACE
578 ["tripe.x25519.x"] = {
579 name = "X25519 x-coordinate",
580 type = ftypes.BYTES, base = base.SPACE
583 name = "X448 x-coordinate",
584 type = ftypes.BYTES, base = base.SPACE
588 -- Convert this table into the protocol fields, and populate `PF'.
592 -- Figure out whether we can use `none' fields (see below).
593 -- probe for this easily
594 local use_none_p = rawget(ProtoField, 'none') ~= nil
595 for abbr, args in pairs(ftab) do
597 -- An annoying hack. Older versions of Wireshark don't allow setting
598 -- fields with type `none', which is a shame because they're ideal as
599 -- internal tree nodes.
602 if ty == ftypes.NONE and not use_none_p then
607 -- Go make the field.
608 local f = ProtoField.new(args.name, abbr, ty,
609 args.tab, b, args.mask, args.descr)
616 -----------------------------------------------------------------------------
617 --- The main dissector.
619 function tripe.dissector(buf, pinfo, tree)
621 -- Fill in the obvious stuff.
622 pinfo.cols.protocol = "TrIPE"
624 local sz = buf:reported_length_remaining()
625 local sub = tree:add(tripe, buf(0, sz), "TrIPE packet")
628 -- Decode the packet type octet.
629 local tycode = buf(0, 1):uint()
630 local ty = sub:add(PF["tripe.type"], buf(0, 1))
631 ty:add(PF["tripe.cat"], buf(0, 1))
632 local cat = bit.rshift(bit.band(tycode, 0xf0), 4)
633 local subty = bit.band(tycode, 0x0f)
634 local info = PKTINFO[cat]
636 -- Dispatch using the master protocol table.
638 pinfo.cols.info = string.format("Unknown category code %u, " ..
639 "unknown type code %u",
642 ty:add(PF[info.subtype], buf(0, 1))
643 local subinfo = info.sub[subty]
644 if subinfo == nil then
645 pinfo.cols.info = string.format("%s, unknown type code %u",
648 pinfo.cols.info = string.format("%s, %s", info.info, subinfo.info)
650 for _, d in ipairs(subinfo.dissect) do p = d(buf, sub, p, sz) end
654 -- Return the final position we reached.
658 -- We're done. Register the dissector.
659 DissectorTable.get("udp.port"):add(4070, tripe)
661 -------- That's all, folks --------------------------------------------------