Line data Source code
1 : #ifndef HEADER_fd_src_util_net_fd_pcapng_h 2 : #define HEADER_fd_src_util_net_fd_pcapng_h 3 : 4 : /* pcapng is a file format for packet captures. Incompatible with 5 : classic "tcpdump" pcap as in fd_pcap.h but supports additional 6 : features such as embedded encryption secrets. 7 : 8 : Spec: https://datatracker.ietf.org/doc/draft-ietf-opsawg-pcapng/ 9 : 10 : fd_pcapng only supports little-endian files. All strings in this API 11 : are formatted as UTF-8 (superset of ASCII) and max not exceed 200 12 : char length. All values in "opt" structs are optional, absence 13 : implied by zero unless otherwise stated. 14 : 15 : This library is not optimized for high performance and is thus not 16 : suitable for packet capture at line rate. Parsing API is hardened 17 : against malicious inputs. */ 18 : 19 : #include "../fd_util_base.h" 20 : 21 : /* Opaque handle of a pcapng iterator */ 22 : 23 : struct fd_pcapng_iter; 24 : typedef struct fd_pcapng_iter fd_pcapng_iter_t; 25 : 26 : #define FD_PCAPNG_ITER_ALIGN (32UL) 27 : 28 : /* Generalized frame read from a pcapng. 29 : Usually a packet but can also be metadata */ 30 : 31 : struct fd_pcapng_frame { 32 : long ts; /* Time in ns (matches fd_log_wallclock) */ 33 : uint type; /* Packet type */ 34 : uint data_sz; /* Size of data array */ 35 : uint orig_sz; /* Original packet size (>=data_sz) */ 36 : uint if_idx; /* Index of interface */ 37 : 38 : # define FD_PCAPNG_FRAME_SZ 16384UL 39 : uchar data[ FD_PCAPNG_FRAME_SZ ]; /* Frame data */ 40 : }; 41 : typedef struct fd_pcapng_frame fd_pcapng_frame_t; 42 : 43 : /* Section Header Block options */ 44 : 45 : struct fd_pcapng_shb_opts { 46 : char const * hardware; /* Generic name of machine performing capture 47 : e.g. "x86_64 Server" */ 48 : char const * os; /* Operating system or distro name */ 49 : char const * userappl; /* Name of this program (e.g. "Firedancer") */ 50 : }; 51 : typedef struct fd_pcapng_shb_opts fd_pcapng_shb_opts_t; 52 : 53 : /* Interface Description Block options */ 54 : 55 : struct fd_pcapng_idb_opts { 56 : char name[16]; /* Name of network interface in OS */ 57 : uchar ip4_addr[4]; /* IPv4 address in big endian order -- todo support multiple */ 58 : uchar mac_addr[6]; /* MAC address */ 59 : uchar tsresol; /* See FD_PCAPNG_TSRESOL_* */ 60 : char hardware[64]; /* Name of network interface hardware */ 61 : }; 62 : typedef struct fd_pcapng_idb_opts fd_pcapng_idb_opts_t; 63 : 64 : /* FD_PCAPNG_TSRESOL_* sets the resolution of a timestamp. */ 65 : 66 15 : #define FD_PCAPNG_TSRESOL_NS ((uchar)0x09) 67 : 68 : /* fd_pcapng_iter iter frame types */ 69 : 70 12 : #define FD_PCAPNG_FRAME_SIMPLE (1U) /* Simple packet type (data only) */ 71 21 : #define FD_PCAPNG_FRAME_ENHANCED (3U) /* Packet with metadata */ 72 3 : #define FD_PCAPNG_FRAME_TLSKEYS (4U) /* TLS keys */ 73 : 74 : FD_PROTOTYPES_BEGIN 75 : 76 : /* Read API ***********************************************************/ 77 : 78 : /* fd_pcap_iter_{align,footprint} return alignment and footprint 79 : requirements of an fd_pcap_iter_t memory region. */ 80 : 81 : FD_FN_CONST ulong 82 : fd_pcapng_iter_align( void ); 83 : 84 : FD_FN_CONST ulong 85 : fd_pcapng_iter_footprint( void ); 86 : 87 : /* fd_pcapng_iter_new creates an iterator suitable for reading a pcapng 88 : file. mem is a non-NULL pointer to a memory region matching align 89 : and footprint requirements. file should be non-NULL handle of a 90 : stream seeked to the first byte of a pcapng section header block 91 : (e.g. on a hosted platform a FILE * of the fopen'd file). Returns 92 : pointer to iter on success (not just a cast of mem) and NULL on 93 : failure (an indeterminant number of bytes in the stream might have 94 : been consumed on failure). */ 95 : 96 : fd_pcapng_iter_t * 97 : fd_pcapng_iter_new( void * mem, 98 : void * file ); 99 : 100 : /* fd_pcapng_iter_delete destroys an fd_pcap_iter_t. Returns the 101 : underlying memory region (not just a cast of iter). The caller 102 : regains ownership of the memory region and stream handle. */ 103 : 104 : void * 105 : fd_pcapng_iter_delete( fd_pcapng_iter_t * iter ); 106 : 107 : /* fd_pcapng_iter_next extracts the next frame from the pcapng stream. 108 : Returns a pointer to the frame descriptor on success and NULL on 109 : failure. Failure reasons include normal end of section (or file), 110 : fread failures, or file corruption. Details of all failures except 111 : normal end-of-file are logged with a warning. Last error code can 112 : be retrieved with fd_pcapng_iter_err. 113 : 114 : On successful return, the return value itself and the frame data 115 : are backed by a thread-local memory region that is valid until delete 116 : or next iter_next. */ 117 : 118 : fd_pcapng_frame_t * 119 : fd_pcapng_iter_next( fd_pcapng_iter_t * iter ); 120 : 121 : /* fd_pcapng_is_pkt returns 1 if given frame (non-NULL) is a regular 122 : captured packet and 0 if it is metadata (such as decryption secrets). */ 123 : 124 : FD_FN_UNUSED FD_FN_PURE static inline int 125 12 : fd_pcapng_is_pkt( fd_pcapng_frame_t const * frame ) { 126 12 : uint ty = frame->type; 127 12 : return (ty==FD_PCAPNG_FRAME_SIMPLE) | (ty==FD_PCAPNG_FRAME_ENHANCED); 128 12 : } 129 : 130 : /* fd_pcapng_iter_err returns the last encountered error. Uses fd_io 131 : error codes. */ 132 : 133 : FD_FN_PURE int 134 : fd_pcapng_iter_err( fd_pcapng_iter_t const * iter ); 135 : 136 : /* Write API **********************************************************/ 137 : 138 : /* fd_pcapng_shb_defaults stores default options for an SHB based on the 139 : system environment into opt. Given opt must be initialized prior to 140 : call. */ 141 : 142 : void 143 : fd_pcapng_shb_defaults( fd_pcapng_shb_opts_t * opt ); 144 : 145 : /* fd_pcapng_fwrite_shb writes a little endian pcapng SHB v1.0 (Section 146 : Header Block) to the stream pointed to by file. Same semantics as 147 : fwrite (returns the number of headers written, which should be 1 on 148 : success and 0 on failure). opt contains options embedded into SHB 149 : and may be NULL. 150 : 151 : The PCAPNG spec requires an SHB v1.0 at the beginning of the file. 152 : Multiple SHBs per file are permitted. An SHB clears any side effects 153 : induced by blocks (such as the timestamp resolution of an IDB). It 154 : is the caller's responsibility to maintain 4 byte alignment for 155 : stream pointer of file. (all functions in this API will write 156 : multiples of 4). 157 : 158 : If SHB is not first of file, this function currently makes no attempt 159 : to fix up the length field of the preceding SHB (may change in the 160 : future). */ 161 : 162 : ulong 163 : fd_pcapng_fwrite_shb( fd_pcapng_shb_opts_t const * opt, 164 : void * file ); 165 : 166 : #if FD_HAS_HOSTED 167 : 168 : /* fd_pcapng_idb_defaults stores default options for an IDB based on the 169 : system environment into opt. if_idx is the operating system's 170 : interface index. (THIS IS UNRELATED TO THE PCAPNG INTERFACE INDEX). 171 : Returns 0 on success and -1 on failure. Reasons for failure are 172 : written to log. On failure, partially writes opt. */ 173 : 174 : int 175 : fd_pcapng_idb_defaults( fd_pcapng_idb_opts_t * opt, 176 : uint if_idx ); 177 : 178 : #endif /* FD_HAS_HOSTED */ 179 : 180 : /* fd_pcapng_fwrite_idb writes an IDB (Interface Description Block) to 181 : the stream pointed to by file. Usually a successor of an SHB. Refer 182 : to fd_pcapng_fwrite_shb for use of opt, file args. link_type is one 183 : of FD_PCAPNG_LINKTYPE_*. opt->tsresol is ignored. fd_pcapng always 184 : writes TSRESOL==9 (nanoseconds). */ 185 : 186 : /* FD_PCAPNG_LINKTYPE_*: Link types (currently only Ethernet supported) */ 187 : 188 0 : #define FD_PCAPNG_LINKTYPE_ETHERNET (1U) /* IEEE 802.3 Ethernet */ 189 0 : #define FD_PCAPNG_LINKTYPE_COOKED (113U) /* Linux "cooked" capture */ 190 : 191 : ulong 192 : fd_pcapng_fwrite_idb( uint link_type, 193 : fd_pcapng_idb_opts_t const * opt, 194 : void * file ); 195 : 196 : /* fd_pcapng_fwrite_pkt writes an EPB (Enhanced Packet Block) containing 197 : an ethernet frame at time ts (in nanos). Same semantics as fwrite 198 : (returns the number of packets written, which should be 1 on success 199 : and 0 on failure). queue is the RX queue index on which this packet 200 : was received on (-1 if unknown). */ 201 : 202 : ulong 203 : fd_pcapng_fwrite_pkt( long ts, 204 : void const * payload, 205 : ulong payload_sz, 206 : void * file ); 207 : 208 : /* fd_pcapng_fwrite_tls_key_log writes TLS key log info to a PCAPNG via 209 : a DSB (Decryption Secrets Block). Similar semantics to fwrite 210 : (returns 1 on success and 0 on failure, but will dispatch multiple 211 : fwrite calls internally). log points to first byte of NSS key log 212 : in ASCII format. log_sz is byte size of log. */ 213 : 214 : ulong 215 : fd_pcapng_fwrite_tls_key_log( uchar const * log, 216 : uint log_sz, 217 : void * file ); 218 : 219 : FD_PROTOTYPES_END 220 : 221 : #endif /* HEADER_fd_src_util_net_fd_pcapng_h */
