Class Peafowl¶
Defined in File peafowl.hpp
Class Documentation¶
-
class
peafowl::Peafowl¶ This class is the Peafowl handler.
Public Functions
-
~Peafowl()¶ Terminates the library.
-
void
setFlowManager(FlowManager *flowManager)¶ setFlowManager Sets the functor object which is called when the flow terminates.
- Parameters
flowManager: The functor object.
-
void
setExpectedFlows(uint32_t flows, FlowsStrategy strategy)¶ Sets the number of simultaneously active flows to be expected.
- Parameters
flows: The number of simultaneously active flows.strategy: If PFWL_FLOWS_STRATEGY_NONE, there will not be any limit to the number of simultaneously active flows. However, this could lead to slowdown when retrieving flow information. If PFWL_FLOWS_STRATEGY_SKIP, when that number of active flows is reached, if a new flow is created an error will be returned (PFWL_ERROR_MAX_FLOWS) and new flows will not be created. If PFWL_FLOWS_STRATEGY_EVICT, when when that number of active flows is reached, if a new flow is created the oldest flow will be evicted.
-
void
setMaxTrials(uint16_t maxTrials)¶ Sets the maximum number of packets to use to identify the protocol. During the flow protocol identification, after this number of trials, if the library cannot decide between two or more protocols, one of them will be chosen, otherwise PFWL_PROTOCOL_UNKNOWN will be returned.
- Parameters
maxTrials: Maximum number of trials. Zero will be consider as infinity.
-
void
setDefragmentationOptions(const DefragmentationOptions &options)¶ setDefragmentationOptions Sets the IPv4/IPv6 defragmentation options.
- Parameters
options: The IPv4/IPv6 defragmentation options.
-
void
tcpReorderingEnable()¶ If enabled, the library will reorder out of order TCP packets (enabled by default).
-
void
tcpReorderingDisable()¶ If called, the library will not reorder out of order TCP packets. Out-of-order segments will be delivered to the dissectors as they arrive. This means that the dissector may not be able to identify the application protocol. Moreover, if there are callbacks saved for TCP based protocols, if TCP reordering is disabled, the extracted informations could be erroneous or incomplete.
-
void
protocolL7Enable(ProtocolL7 protocol)¶ Enables an L7 protocol dissector.
- Parameters
protocol: The protocol to enable.
-
void
protocolL7Disable(ProtocolL7 protocol)¶ Disables an L7 protocol dissector.
- Parameters
protocol: The protocol to disable.
-
void
protocolL7EnableAll()¶ Enables all the L7 protocol dissector.
-
void
protocolL7DisableAll()¶ Disable all the protocol dissector.
-
void
setTimestampUnit(TimestampUnit unit)¶ Sets the unit of the timestamps used in the dissect* calls.
- Parameters
unit: The unit of the timestamps.
-
DissectionInfo
dissectFromL2(const std::string &pkt, double timestamp, ProtocolL2 datalinkType)¶ Dissects the packet starting from the beginning of the L2 (datalink) header.
- Return
The result of the dissection from L2 to L7.
- Parameters
pkt: A string containing the packet.timestamp: The current time. The time unit depends on the timers used by the caller and can be set through the setTimestampUnit call. By default it is assumed that the timestamps unit is ‘seconds’.datalinkType: The datalink type. You can convert a PCAP datalink type to a Peafowl datalink type by calling the function ‘convertPcapDlt’.
-
DissectionInfo
dissectFromL3(const std::string &pkt, double timestamp)¶ Dissects the packet starting from the beginning of the L3 (IP) header.
- Return
The result of the dissection from L3 to L7.
- Parameters
pkt: A string containing the packet (starting from the IP header).timestamp: The current time. The time unit depends on the timers used by the caller and can be set through the setTimestampUnit call. By default it is assumed that the timestamps unit is ‘seconds’.
-
DissectionInfo
dissectFromL4(const std::string &pkt, double timestamp, const DissectionInfo &info)¶ Dissects the packet starting from the beginning of the L4 (UDP or TCP) header.
- Return
The result of the dissection from L3 to L7.
- Parameters
pkt: A string containing the packet (from the start of TCP/UDP header).timestamp: The current time. The time unit depends on the timers used by the caller and can be set through the setTimestampUnit call. By default it is assumed that the timestamps unit is ‘seconds’.info: The dissection information about L3 header.
-
DissectionInfo
dissectL2(const std::string &pkt, pfwl_protocol_l2_t datalinkType)¶ Extracts from the packet the L2 information.
- Return
The result of the L2 dissection.
- Parameters
pkt: A string containing the packet.datalinkType: The datalink type. They match 1:1 the pcap datalink types. You can convert a PCAP datalink type to a Peafowl datalink type by calling the function ‘convertPcapDlt’.
-
DissectionInfo
dissectL3(const std::string &pkt, double timestamp)¶ Extracts from the packet the L3 information.
- Return
The result of the L3 dissection.
- Parameters
pkt: A string containing the packet (from the start of the IP header).timestamp: The current time. The time unit depends on the timers used by the caller and can be set through the setTimestampUnit call. By default it is assumed that the timestamps unit is ‘seconds’.
-
DissectionInfo
dissectL4(const std::string &pkt, double timestamp, const DissectionInfo &info, FlowInfoPrivate &flowInfoPrivate)¶ Extracts from the packet the L4 information.
- Return
The result of the L4 dissection.
- Parameters
pkt: A string containing the packet (from the start of the TCP/UDP header).timestamp: The current time. The time unit depends on the timers used by the caller and can be set through the setTimestampUnit call. By default it is assumed that the timestamps unit is ‘seconds’.info: The dissection information about L3 header. L4 protocol must be specified by the caller as well.flowInfoPrivate: Will be filled by this call.
-
DissectionInfo
dissectL7(const std::string &pkt, const DissectionInfo &info, FlowInfoPrivate &flowInfoPrivate)¶ Extracts from the packet the L7 information. Before calling it, a check on L4 protocol should be done and the function should be called only if the packet is TCP or UDP. It should be used if the application already called dissectL7 or if the application already has the concept of ‘flow’. In this case the first time that the flow is passed to the call, flow_info_private must be initialized with pfwl_init_flow_info(…) and stored with the flow already present in the application. With this call, information in dissection_info->flow are only set for L7 packets and bytes.
- Return
The result of the L7 dissection.
- Parameters
pkt: A string containing the packet (from the start of application data).info: The dissection information about L3 and L4 headers.flowInfoPrivate: The private information about the flow. It must be stored by the user.
-
void
fieldAddL7(FieldId field)¶ Enables the extraction of a specific L7 field for a given protocol. When a protocol is identified, the default behavior is to not inspect the packets belonging to that flow anymore and keep simply returning the same protocol identifier.
If at least one field extraction is enabled for a certain protocol, then we keep inspecting all the new packets of that flow to extract such field. Moreover, if the application protocol uses TCP, then we have the additional cost of TCP reordering for all the segments. Is highly recommended to enable TCP reordering if it is not already enabled (remember that is enabled by default). Otherwise the informations extracted could be erroneous/incomplete.
Please note that this is only a suggestion given by the user to peafowl, and that in some cases the dissector could still extract the field, even if this has not been requested by the user. Indeed, in some cases the extraction of some fields may be needed for the correct identification of the protocol.
- Parameters
field: The field to extract.
-
void
fieldRemoveL7(FieldId field)¶ Disables the extraction of a specific L7 protocol field.
- Parameters
field: The field identifier.
-
void
setProtocolAccuracyL7(ProtocolL7 protocol, DissectorAccuracy accuracy)¶ Some L7 protocols dissectors (e.g. SIP) can be applied with a different level of accuracy (and of performance). By using this call the user can decide if running the dissector in its most accurate version (at the cost of a higher processing latency).
- Parameters
protocol: The L7 protocol for which we want to change the accuracy.accuracy: The accuracy level.
-
void
fieldTagsLoadL7(FieldId field, const char *tagsFile)¶ fieldTagsLoadL7 Loads the associations between fields values and user-defined tags.
Loads the associations between fields values and user-defined tags.
{ “rules”: [ {“value”: “google.com”, “matchingType”: “SUFFIX”, “tag”: “GOOGLE”}, {“value”: “amazon.com”, “matchingType”: “SUFFIX”, “tag”: “AMAZON”}, … ], }
- Parameters
field: The field identifier.tagsFile: The name of the JSON file containing associations between fields values and tags. The structure of the JSON file depends from the type of ‘field’. If ‘field’ is a string:
value: Is the string to be matched against the field. The comparison will always be case insensitive. I.e. if searching for ‘BarFoo’, ‘barfoo’ and ‘BaRfOo’ will match as well. matchingType: Can be ‘PREFIX’, ‘EXACT’ or ‘SUFFIX’. tag: The tag to assign to the packet when the field matches with stringToMatch. If ‘field’ is a multi map:
{ “rules”: [ {“key”: “Host”, “value”: “google.com”, “matchingType”: “SUFFIX”, “tag”: “GOOGLE”}, {“key”: “Content-Type”, “value”: “amazon.com”, “matchingType”: “SUFFIX”, “tag”: “AMAZON”}, … ], }
key: The key to match in the multi map. ‘value’, ‘matchingType’ and ‘tag’ are the same as in the string case.
The ‘tagsFile’ argument can be NULL and the matching rules can be added later with the *TagsAdd calls.
-
void
fieldStringTagsAddL7(FieldId field, const std::string &value, FieldMatching matchingType, const std::string &tag)¶ pfwl_field_string_tags_add Adds a tag matching rule for a specific field.
Adds a tag matching rule for a specific string field.
- Parameters
field: The field identifier.value: Is the string to be matched against the field. The comparison will always be case insensitive. I.e. if searching for ‘BarFoo’, ‘barfoo’ and ‘BaRfOo’ will match as well.matchingType: Can be ‘PREFIX’, ‘EXACT’ or ‘SUFFIX’.tag: The tag to assign to the packet when the field matches with ‘value’.
-
void
fieldMmapTagsAddL7(FieldId field, const std::string &key, const std::string &value, FieldMatching matchingType, const std::string &tag)¶ fieldMmapTagsAddL7 Adds a tag matching rule for a specific field.
Adds a tag matching rule for a specific multimap field.
- Parameters
field: The field identifier.key: The key of the multimap value. The comparison will always be case insensitive. I.e. if searching for ‘BarFoo’, ‘barfoo’ and ‘BaRfOo’ will match as well.value: The value of the multimap value. The comparison will always be case insensitive. I.e. if searching for ‘BarFoo’, ‘barfoo’ and ‘BaRfOo’ will match as well.matchingType: Can be ‘PREFIX’, ‘EXACT’ or ‘SUFFIX’.tag: The tag to assign to the packet when the field matches with ‘value’.
-
void
fieldTagsUnloadL7(FieldId field)¶ fieldTagsUnloadL7 Unloads the associations between fields values and user-defined tags.
Unloads the associations between fields values and user-defined tags.
- Parameters
field: The field identifier.
-