1 /* 2 * Copyright (c) 2009-2015 by Farsight Security, Inc. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef NMSG_PCAP_H 18 #define NMSG_PCAP_H 19 20 /*! \file nmsg/pcap_input.h 21 * \brief Reassembled IP datagram interface to libpcap. 22 * 23 * libpcap's frame-based interface is wrapped with calls to the ipdg.h interface 24 * and provides the caller with reassembled IP datagrams. 25 * 26 * Callers should not call pcap_setfilter() on the pcap_t handle passed to 27 * nmsg_pcap_input_open() but should instead use nmsg_pcap_input_setfilter(). 28 * Since IP datagrams are reassembled in userspace, they must undergo 29 * reevaluation of the user-provided filter. nmsg_pcap_input_setfilter() and 30 * nmsg_pcap_input_read() handle this transparently. 31 */ 32 33 typedef enum { 34 nmsg_pcap_type_file, 35 nmsg_pcap_type_live 36 } nmsg_pcap_type; 37 38 /** 39 * Initialize a new nmsg_pcap_t input from a libpcap source. 40 * 41 * \param[in] phandle pcap_t handle (e.g., acquired from pcap_open_offline() or 42 * pcap_open_live()). 43 * 44 * \return Opaque pointer that is NULL on failure or non-NULL on success. 45 */ 46 nmsg_pcap_t 47 nmsg_pcap_input_open(pcap_t *phandle); 48 49 /** 50 * Close an nmsg_pcap_t object and release all associated resources. 51 * 52 * \param[in] pcap pointer to an nmsg_pcap_t object. 53 */ 54 nmsg_res 55 nmsg_pcap_input_close(nmsg_pcap_t *pcap); 56 57 /** 58 * Read an IP datagram from an nmsg_pcap_t input, performing reassembly if 59 * necessary. 60 * 61 * \param[in] pcap nmsg_pcap_t object. 62 * 63 * \param[out] dg nmsg_ipdg structure to be filled. 64 * 65 * \param[out] ts timespec structure indicating time of datagram reception. 66 * 67 * \return #nmsg_res_success 68 * \return #nmsg_res_pcap_error 69 * \return #nmsg_res_again 70 */ 71 nmsg_res 72 nmsg_pcap_input_read(nmsg_pcap_t pcap, struct nmsg_ipdg *dg, 73 struct timespec *ts); 74 75 /** 76 * Read a raw packet from an nmsg_pcap_t input. 77 * 78 * \param[in] pcap nmsg_pcap_t object. 79 * 80 * \param[out] pkt_hdr Location to store pcap packet header. 81 * 82 * \param[out] pkt_data Location to store pcap packet data. 83 * 84 * \param[out] ts timespec structure indicating time of packet reception. 85 * 86 * \return #nmsg_res_success 87 * \return #nmsg_res_pcap_error 88 * \return #nmsg_res_again 89 */ 90 nmsg_res 91 nmsg_pcap_input_read_raw(nmsg_pcap_t pcap, struct pcap_pkthdr **pkt_hdr, 92 const uint8_t **pkt_data, struct timespec *ts); 93 94 /** 95 * Set a bpf filter on an nmsg_pcap_t object. This function performs 96 * additional transformation on the bpf filter text before passing the 97 * filter to pcap_compile() and pcap_setfilter(). 98 * 99 * \param[in] pcap nmsg_pcap_t object. 100 * 101 * \param[in] bpfstr is a valid bpf filter expression that will be passed to 102 * pcap_compile(). 103 * 104 * \return #nmsg_res_success 105 * \return #nmsg_res_failure 106 */ 107 nmsg_res 108 nmsg_pcap_input_setfilter(nmsg_pcap_t pcap, const char *bpfstr); 109 110 /** 111 * Set a bpf filter on an nmsg_pcap_t object. This function is a thin 112 * wrapper for pcap_setfilter(). 113 * 114 * \param[in] pcap nmsg_pcap_t object. 115 * 116 * \param[in] bpfstr is a valid bpf filter expression that will be passed to 117 * pcap_compile() and pcap_setfilter(). 118 * 119 * \return #nmsg_res_success 120 * \return #nmsg_res_failure 121 */ 122 nmsg_res 123 nmsg_pcap_input_setfilter_raw(nmsg_pcap_t pcap, const char *bpfstr); 124 125 /** 126 * Set raw mode. 127 * 128 * \param[in] pcap nmsg_pcap_t object. 129 * 130 * \param[in] raw True if raw packets should be passed, false if reassembled 131 * datagrams should be passed. 132 */ 133 void 134 nmsg_pcap_input_set_raw(nmsg_pcap_t pcap, bool raw); 135 136 /** 137 * Get the snapshot length of the underlying pcap handle. 138 * 139 * \param[in] pcap nmsg_pcap_t object. 140 * 141 * \return Pcap snapshot length. 142 */ 143 int 144 nmsg_pcap_snapshot(nmsg_pcap_t pcap); 145 146 /** 147 * Get the type of the underlying pcap handle. 148 * 149 * \param[in] pcap nmsg_pcap_t object. 150 * 151 * \return #nmsg_pcap_type_file 152 * \return #nmsg_pcap_type_live 153 */ 154 nmsg_pcap_type 155 nmsg_pcap_get_type(nmsg_pcap_t pcap); 156 157 /** 158 * Get the datalink type of the underlying pcap handle. 159 * 160 * \param[in] pcap nmsg_pcap_t object. 161 */ 162 int 163 nmsg_pcap_get_datalink(nmsg_pcap_t pcap); 164 165 /** 166 * Return the result of filtering a packet. 167 * 168 * \param[in] pcap nmsg_pcap_t object. 169 * 170 * \param[in] pkt Pointer to start of network packet. 171 * 172 * \param[in] len Length of packet. 173 * 174 * \return false if packet failed the filter 175 * \return true if packet passed the filter 176 */ 177 bool 178 nmsg_pcap_filter(nmsg_pcap_t pcap, const uint8_t *pkt, size_t len); 179 180 #endif /* NMSG_PCAP_H */ 181