epan/dissectors/packet-nts-ke.h

   1 /* packet-nts-ke.h
   2  *
   3  * Copyright (c) 2024 by Martin Mayer <martin.mayer@m2-it-solutions.de>
   4  *
   5  * Wireshark - Network traffic analyzer
   6  * By Gerald Combs <gerald@wireshark.org>
   7  * Copyright 1998 Gerald Combs
   8  *
   9  * SPDX-License-Identifier: GPL-2.0-or-later
  10  */
  11
  12 #ifndef __PACKET_NTS_KE_H__
  13 #define __PACKET_NTS_KE_H__
  14
  15 #include <wsutil/wsgcrypt.h>
  16
  17 #define NTS_KE_TLS13_KEY_MAX_LEN     64
  18
  19 typedef struct _nts_aead {
  20     uint16_t    id;             /* IANA assigned AEAD parameter ID */
  21     uint16_t    cipher;         /* gcrypt cipher */
  22     uint8_t     mode;           /* gcrypt cipher mode */
  23     uint16_t    key_len;        /* Length of key for this cipher */
  24     uint16_t    tag_len;        /* Length of authentication tag for this cipher */
  25 } nts_aead;
  26
  27 typedef struct _nts_cookie_t {
  28     uint32_t    frame_received;                    /* Frame no. which provided the cookie */
  29     wmem_list_t *frames_used;                      /* List of frame no. which used the cookie */
  30     wmem_list_t *frames_used_uid;                  /* List of request UIDs which used the cookie */
  31     uint16_t    aead;                              /* AEAD parameter */
  32     bool        keys_present;                      /* Are keys present (export successful) */
  33     uint8_t     key_c2s[NTS_KE_TLS13_KEY_MAX_LEN]; /* Derived client to server key */
  34     uint8_t     key_s2c[NTS_KE_TLS13_KEY_MAX_LEN]; /* Derived server to client key */
  35 } nts_cookie_t;
  36
  37 /* Helper structure to pass data to nts_append_used_frames_to_tree() */
  38 typedef struct _nts_used_frames_lookup_t {
  39     tvbuff_t *tvb;
  40     proto_tree *tree;
  41     int hfindex;
  42 } nts_used_frames_lookup_t;
  43
  44 /** Append a NTS cookie to the file-scoped wmem map and extract C2S and S2C keys.
  45  *
  46  * @param tvb The backing tvbuff of the cookie (only!) (may use tvb_new_subset_*()).
  47  * @param aead The IANA assigned ID of the AEAD parameter used for the cookie.
  48  * @param pinfo The packet_info of the packet which provided the cookie.
  49  *
  50  * @return A pointer to the cookie's nts_cookie_t data */
  51 nts_cookie_t* nts_new_cookie(tvbuff_t *tvb, uint16_t aead, packet_info *pinfo);
  52
  53 /** Append a NTS cookie to the file-scoped wmem map and copy crypto data from existing cookie.
  54  *
  55  * @param tvb The backing tvbuff of the cookie (only!) (may use tvb_new_subset_*()).
  56  * @param ref_cookie The reference cookie from which crypto data can be copied.
  57  * @param pinfo The packet_info of the packet which provided the cookie.
  58  *
  59  * @return A pointer to the cookie's nts_cookie_t data */
  60 nts_cookie_t* nts_new_cookie_copy(tvbuff_t *tvb, nts_cookie_t *ref_cookie, packet_info *pinfo);
  61
  62 /** Finds a NTS cookie in the wmem map and sets the frame_used and frame_used_uid info.
  63  *
  64  * @param tvb_cookie The backing tvbuff of the cookie (only!) (may use tvb_new_subset_*()).
  65  * @param tvb_uid The backing tvbuff of the packet's NTS UID (only!) (may use tvb_new_subset_*()).
  66  * @param pinfo The packet_info of the packet which provided the cookie.
  67  *
  68  * @return A pointer to the cookie's nts_cookie_t data if found */
  69 nts_cookie_t* nts_use_cookie(tvbuff_t *tvb_cookie, tvbuff_t *tvb_uid, packet_info *pinfo);
  70
  71 /** Finds a NTS cookie in the wmem map by a provided tvbuff of NTS UID.
  72  *
  73  * @param tvb_uid The backing tvbuff of the packet's UID (only!) (may use tvb_new_subset_*()).
  74  *
  75  * @return A pointer to the cookie's nts_cookie_t data if found */
  76 nts_cookie_t* nts_find_cookie_by_uid(tvbuff_t *tvb_uid);
  77
  78 /** Finds a matching AEAD algorithm entry by a given NTS-KE AEAD-Algo-ID.
  79  *
  80  * @param id The ID of an AEAD algorithm.
  81  *
  82  * @return A pointer to the AEAD's nts_aead algorithm data if found. */
  83 const nts_aead * nts_find_aead(uint16_t id);
  84
  85 /** Helper function for wmem_list_foreach() to append used cookies to proto_tree.
  86  *
  87  * @param data pointer to wmem_list_t of frame numbers. Typically frames_used in a nts_cookie_t.
  88  * @param user_data pointer to nts_used_frames_lookup_t with tree and field infos. */
  89 void nts_append_used_frames_to_tree(void *data, void *user_data);
  90
  91 #endif