Receive Filter

Types and functions for operating with bRAWcap receive filters. More...

Macros
#define	BRAWCAP_FILTER_BYTE_MAX_LENGTH   64U
	The maximum supported filter byte mask length in bytes.

Typedefs
typedef UINT8	brawcap_filter_mask_array_t[BRAWCAP_FILTER_BYTE_MAX_LENGTH]
	Fixed size array for storing a filter byte mask.
typedef UINT8	brawcap_filter_ignore_bits_array_t[BRAWCAP_FILTER_BYTE_MAX_LENGTH]
	Fixed size array for storing a byte wise bitfield.
typedef brawcap_packet_size_t	brawcap_filter_byte_length_t
	Type for specifying the byte filter length.
typedef struct _brawcap_filter	brawcap_filter_t
	bRAWcap filter object.

Enumerations
enum	brawcap_filter_type_t {   BRAWCAP_FILTER_TYPE_BYTE_MASK = 0x00 ,   BRAWCAP_FILTER_TYPE_BPF = 0x01 ,   BRAWCAP_FILTER_TYPE_NONE = 0xFF }
	List of filter types. More...

Functions
brawcap_status_t	brawcap_filter_create (brawcap_filter_t **const pFilter, const brawcap_filter_type_t type)
	Creates a new filter.
brawcap_status_t	brawcap_filter_free (brawcap_filter_t *pFilter)
	Frees the specified filter. When this function is called the given filter becomes invalid and it´s memory will be released.
brawcap_status_t	brawcap_filter_type_get (brawcap_filter_t *const pFilter, brawcap_filter_type_t *const pType)
	Reads out the type for the specified filter.
brawcap_status_t	brawcap_filter_mask_set (brawcap_filter_t *const pFilter, const brawcap_filter_byte_length_t offset, const brawcap_filter_byte_length_t length, const brawcap_filter_mask_array_t mask, const brawcap_filter_ignore_bits_array_t ignoreBits)
	Sets the filter parameters for the specified filter.
brawcap_status_t	brawcap_filter_mask_get (brawcap_filter_t *const pFilter, brawcap_filter_byte_length_t *const pOffset, brawcap_filter_byte_length_t *const pLength, brawcap_filter_mask_array_t *const pMask, brawcap_filter_ignore_bits_array_t *const pIgnoreBits)
	Reads out the filter mask parameters for the specified filter.
brawcap_status_t	brawcap_filter_bpf_set (brawcap_filter_t *const pFilter, const char *const filterString)
	Sets the BPF filter string for the specified filter.
brawcap_status_t	brawcap_filter_bpf_get (brawcap_filter_t *const pFilter, char *filterString, UINT *const pLength)
	Reads the BPF filter string from the specified filter.
brawcap_status_t	brawcap_filter_bpf_compile_error_get (brawcap_filter_t *const pFilter, const char *pError)
	Retrieves the BPF compile error message from the specified filter.
brawcap_status_t	brawcap_filter_activate (brawcap_filter_t *const pFilter)
	Sets the specified filter to active.
brawcap_status_t	brawcap_filter_deactivate (brawcap_filter_t *const pFilter)
	Sets the specified filter to inactive.
brawcap_status_t	brawcap_filter_is_activated (brawcap_filter_t *const pFilter, BOOLEAN *const pActive)
	Reads out the current activation state of the specified filter.
brawcap_status_t	brawcap_filter_bytes_to_capture_set (brawcap_filter_t *const pFilter, const brawcap_packet_size_t offset, const brawcap_packet_size_t length)
	Sets the bytes to capture of the specified filter.
brawcap_status_t	brawcap_filter_bytes_to_capture_get (brawcap_filter_t *const pFilter, brawcap_packet_size_t *const pOffset, brawcap_packet_size_t *const pLength)
	Reads out the configured bytes to capture of the specified filter.
brawcap_status_t	brawcap_filter_indicate_set (brawcap_filter_t *const pFilter, const BOOLEAN indicate)
	Specifies if packets which matched the specified filter should be indicated to the network stack.
brawcap_status_t	brawcap_filter_indicate_get (brawcap_filter_t *const pFilter, BOOLEAN *const pIndicate)
	Reads out the current network stack indication state of the specified filter.

Detailed Description

Types and functions for operating with bRAWcap receive filters.

To create a new filter use brawcap_filter_create. If a filter is not required anymore it shall be deleted with brawcap_filter_free.

Note

Applying filters to handles:
Each bRAWcap handle has it´s own filter instance. Therefore after applying the filter to a bRAWcap handle the filter may be reused to apply the same (or a different) filter to another handle or freed if not required anymore.

List of examples:

1. Firewall
2. BPF

Typedef Documentation

brawcap_filter_mask_array_t

typedef UINT8 brawcap_filter_mask_array_t[BRAWCAP_FILTER_BYTE_MAX_LENGTH]

#include <brawcap_types_shared.h>

Fixed size array for storing a filter byte mask.

Note

It is not necessary to set all bytes. If the used filter does not require the complete mask length. bRAWcap evaluates only the bytes up to the specified filter length.

Examples

06_filter_firewall_f.c.

brawcap_filter_ignore_bits_array_t

typedef UINT8 brawcap_filter_ignore_bits_array_t[BRAWCAP_FILTER_BYTE_MAX_LENGTH]

#include <brawcap_types_shared.h>

Fixed size array for storing a byte wise bitfield.

This allows to ignore specific bits in the specified filter byte mask. Each bit which is set to one is ignored in the filter byte mask.

Note

It is not necessary to set all bytes. If the used filter does not require the complete mask length. bRAWcap evaluates only the bytes up to the specified filter length.

Examples

06_filter_firewall_f.c.

brawcap_filter_t

typedef struct _brawcap_filter brawcap_filter_t

#include <brawcap_types_shared.h>

bRAWcap filter object.

The filter object can be accessed with the bRAWcap filter functions. Filters can be created and freed.

Enumeration Type Documentation

brawcap_filter_type_t

enum brawcap_filter_type_t

#include <brawcap_types_shared.h>

List of filter types.

Note

Currently only the byte filter is supported. A BPF (Berkley Packet Filter) filter, which is equivalent to the one which libpcap uses, may be added in the future.

Enumerator
BRAWCAP_FILTER_TYPE_BYTE_MASK	A bRAWcap byte filter.
BRAWCAP_FILTER_TYPE_BPF	A Berkley Packet Filter.
BRAWCAP_FILTER_TYPE_NONE	No filter.

Function Documentation

brawcap_filter_create()

brawcap_status_t brawcap_filter_create	(	brawcap_filter_t **const	pFilter,
		const brawcap_filter_type_t	type
	)

#include <brawcap.h>

Creates a new filter.

The created filter can be used for filtering received packets by applying it to a bRAWcap handle with brawcap_rx_filter_set.

If a created filter is not required anymore it should be freed with brawcap_filter_free.

Note

Currently only the BRAWCAP_FILTER_TYPE_BYTE_MASK filter type is supported. Support for BRAWCAP_FILTER_TYPE_BPF may be added later on.

Parameters

[in]	pFilter	Will contain the new created filter.
[in]	type	Specifies the type of the created filter.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_NOT_AVAILABLE	Specified filter type is not supported.
BRAWCAP_STATUS_ERROR_FAILED	System error occurred (e.g. out of memory).

Examples

06_filter_firewall_f.c, and 11_filter_bpf_f.c.

brawcap_filter_free()

brawcap_status_t brawcap_filter_free

(

brawcap_filter_t *

pFilter

)

#include <brawcap.h>

Frees the specified filter. When this function is called the given filter becomes invalid and it´s memory will be released.

Warning

Freeing a filter is not thread safe and the user is responsible for synchronization.

Parameters

[in]

pFilter

The filter to be freed.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.

Examples

06_filter_firewall_f.c, and 11_filter_bpf_f.c.

brawcap_filter_type_get()

brawcap_status_t brawcap_filter_type_get	(	brawcap_filter_t *const	pFilter,
		brawcap_filter_type_t *const	pType
	)

#include <brawcap.h>

Reads out the type for the specified filter.

Parameters

[in]	pFilter	The filter to read from.
[out]	pType	Will contain the filter type, afterwards.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.

brawcap_filter_mask_set()

brawcap_status_t brawcap_filter_mask_set	(	brawcap_filter_t *const	pFilter,
		const brawcap_filter_byte_length_t	offset,
		const brawcap_filter_byte_length_t	length,
		const brawcap_filter_mask_array_t	mask,
		const brawcap_filter_ignore_bits_array_t	ignoreBits
	)

#include <brawcap.h>

Sets the filter parameters for the specified filter.

Note

Changes will only effect after applying the modified filter to a handle with brawcap_rx_filter_set.

Parameters

[in]	pFilter	The filter to be modified.
[in]	offset	Byte offset of the filter. This value specifies at which packet byte offset the first filter byte shall be applied.
[in]	length	Byte length of the filter. Specifies the number of bytes used by the filter. This value is limited to BRAWCAP_FILTER_BYTE_MAX_LENGTH.
[in]	mask	The byte mask for the filter. This is a fixed size byte array. Set the byte values to the filter you want to apply. Only bytes up to the specified filter length are used and following bytes will be ignored.

Byte order

The mask ALWAYS represents on-the-wire values in network byte order (big endian), independent of the host platform endianness. The library/driver does NOT perform any host-to-network conversion for you. You must pre‑encode any multi-byte protocol fields (e.g. Ethertype, IP addresses, ports) into big-endian form before passing them here. Single-byte fields can be copied directly.

Attention

The mask is always interpreted in network-order (big endian). Supplying host-endian encoded multi-byte values on a little-endian host will result in the filter not matching.

Ignore bits

The ignoreBits array uses per-bit flags (1 = ignore / wildcard that bit, 0 = compare) aligned to the corresponding byte in mask. Ignoring an entire byte can be achieved by setting its ignoreBits value to 0xFF.

Example

Match TCP destination port 443 (0x01BB) at offset 36 in an Ethernet II + IPv4 (no options) packet (Ethernet header 14 bytes + IP header 20 bytes + TCP dest port is bytes 2-3 of TCP header => offset 14+20+2 = 36):

brawcap_filter_mask_array_t mask = {0};
brawcap_filter_ignore_bits_array_t ignoreBits = {0};
// Encode 0x01BB in big endian
mask[36] = 0x01; // high byte
mask[37] = 0xBB; // low  byte
// No bits ignored -> ignoreBits[36] = ignoreBits[37] = 0;
brawcap_filter_mask_set(filter, 36, 2, mask, ignoreBits);

If VLAN tagging (802.1Q) is enabled and the VLAN header is present on the wire, remember that all subsequent offsets shift by 4 bytes; you must account for this when computing offset.

Parameters

[in]

ignoreBits

A fixed size bitfield byte array. The bytes in this array has to be interpreted/used as bitfields. This allows to select if a single bit at the corresponding mask position shall be ignored. To ignore the value of a bit set it´s value to 1. Like the mask, only bytes up to the specified filter length are used and following bytes will be ignored.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_INVALID_PARAM	Specified filter is not of type BRAWCAP_FILTER_TYPE_BYTE_MASK.
BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE	Specified offset+length exceeds BRAWCAP_FILTER_BYTE_MAX_LENGTH.

Examples

06_filter_firewall_f.c.

brawcap_filter_mask_get()

brawcap_status_t brawcap_filter_mask_get	(	brawcap_filter_t *const	pFilter,
		brawcap_filter_byte_length_t *const	pOffset,
		brawcap_filter_byte_length_t *const	pLength,
		brawcap_filter_mask_array_t *const	pMask,
		brawcap_filter_ignore_bits_array_t *const	pIgnoreBits
	)

#include <brawcap.h>

Reads out the filter mask parameters for the specified filter.

Parameters

[in]	pFilter	The filter to read from.
[out]	pOffset	Will contain the filter byte offset, afterwards.
[out]	pLength	Will contain the filter byte length, afterwards.
[out]	pMask	Will contain the filter mask bytes, afterwards.

Byte order

Returned mask bytes are in network byte order (big endian) exactly as stored internally / originally supplied. If you need to interpret multi-byte fields as host-endian integers, perform the appropriate conversion (e.g. (mask[i] << 8) | mask[i+1] for 16-bit values).

Attention

The mask is always interpreted in network-order (big endian) when applying the filter during packet comparison.

Parameters

[out]

pIgnoreBits

Will contain the filter bits to ignore, afterwards

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_INVALID_PARAM	Specified filter is not of type BRAWCAP_FILTER_TYPE_BYTE_MASK.

brawcap_filter_bpf_set()

brawcap_status_t brawcap_filter_bpf_set	(	brawcap_filter_t *const	pFilter,
		const char *const	filterString
	)

#include <brawcap.h>

Sets the BPF filter string for the specified filter.

Parameters

[in]	pFilter	The filter to be modified.
[in]	filterString	The BPF filter string to set.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_INVALID_PARAM	Specified filter is not of type BRAWCAP_FILTER_TYPE_BPF.
BRAWCAP_STATUS_ERROR_BPF_COMPILE_FAILED	BPF filter compilation failed.
BRAWCAP_STATUS_ERROR_NOT_AVAILABLE	libpcap not available/found.

Examples

11_filter_bpf_f.c.

brawcap_filter_bpf_get()

brawcap_status_t brawcap_filter_bpf_get	(	brawcap_filter_t *const	pFilter,
		char *	filterString,
		UINT *const	pLength
	)

#include <brawcap.h>

Reads the BPF filter string from the specified filter.

Parameters

[in]	pFilter	The filter to read from.
[out]	filterString	Buffer for the BPF filter string.
[in,out]	pLength	Length of the provided buffer for the BPF filter string. If the provided buffer is too small, it will contain the required length, afterwards and BRAWCAP_STATUS_ERROR_OVERRUN will be returned.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_INVALID_PARAM	Specified filter is not of type BRAWCAP_FILTER_TYPE_BPF or current filter string is empty / not set.
BRAWCAP_STATUS_ERROR_OVERRUN	BPF filter string is too long.

brawcap_filter_bpf_compile_error_get()

brawcap_status_t brawcap_filter_bpf_compile_error_get	(	brawcap_filter_t *const	pFilter,
		const char *	pError
	)

#include <brawcap.h>

Retrieves the BPF compile error message from the specified filter.

Attention

pError is only valid as long as the filter is not freed (by brawcap_filter_free).

Parameters

[in]	pFilter	The filter to read from.
[out]	pError	Will contain the BPF compile error message, afterwards.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_INVALID_PARAM	Specified filter is not of type BRAWCAP_FILTER_TYPE_BPF or current filter string is empty / not set.

Examples

11_filter_bpf_f.c.

brawcap_filter_activate()

brawcap_status_t brawcap_filter_activate

(

brawcap_filter_t *const

pFilter

)

#include <brawcap.h>

Sets the specified filter to active.

Note

Changes will only effect after applying the modified filter to a handle with brawcap_rx_filter_set.

Parameters

[in]

pFilter

The filter to be modified.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.

Examples

06_filter_firewall_f.c, and 11_filter_bpf_f.c.

brawcap_filter_deactivate()

brawcap_status_t brawcap_filter_deactivate

(

brawcap_filter_t *const

pFilter

)

#include <brawcap.h>

Sets the specified filter to inactive.

Note

Changes will only effect after applying the modified filter to a handle with brawcap_rx_filter_set.

Parameters

[in]

pFilter

The filter to be modified.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.

brawcap_filter_is_activated()

brawcap_status_t brawcap_filter_is_activated	(	brawcap_filter_t *const	pFilter,
		BOOLEAN *const	pActive
	)

#include <brawcap.h>

Reads out the current activation state of the specified filter.

Parameters

[in]	pFilter	The filter to read from.
[out]	pActive	Will contain the activation state, afterwards.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.

brawcap_filter_bytes_to_capture_set()

brawcap_status_t brawcap_filter_bytes_to_capture_set	(	brawcap_filter_t *const	pFilter,
		const brawcap_packet_size_t	offset,
		const brawcap_packet_size_t	length
	)

#include <brawcap.h>

Sets the bytes to capture of the specified filter.

Note

Changes will only effect after applying the modified filter to a handle with brawcap_rx_filter_set.

Parameters

[in]	pFilter	The filter to be modified.
[in]	offset	The byte offset, from packet payload beginning, to begin capturing the payload bytes.
[in]	length	The number of bytes to be captured - beginning at offset.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE	Specified offset+length exceeds BRAWCAP_PACKET_SIZE_MAX.

brawcap_filter_bytes_to_capture_get()

brawcap_status_t brawcap_filter_bytes_to_capture_get	(	brawcap_filter_t *const	pFilter,
		brawcap_packet_size_t *const	pOffset,
		brawcap_packet_size_t *const	pLength
	)

#include <brawcap.h>

Reads out the configured bytes to capture of the specified filter.

Parameters

[in]	pFilter	The filter to read from.
[out]	pOffset	Will contain the byte offset of the bytes to capture, afterwards.
[out]	pLength	Will contain the number of bytes to capture, afterwards.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.

brawcap_filter_indicate_set()

brawcap_status_t brawcap_filter_indicate_set	(	brawcap_filter_t *const	pFilter,
		const BOOLEAN	indicate
	)

#include <brawcap.h>

Specifies if packets which matched the specified filter should be indicated to the network stack.

Note

Changes will only effect after applying the modified filter to a handle with brawcap_rx_filter_set.

Parameters

[in]	pFilter	The filter to be modified.
[in]	indicate	Flag specifying the network stack indication. If true filtered packets are forwarded to the network stack. If false filtered packets are not forwarded to the network stack, they are only visible for bRAWcap handles.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.

Examples

06_filter_firewall_f.c, and 11_filter_bpf_f.c.

brawcap_filter_indicate_get()

brawcap_status_t brawcap_filter_indicate_get	(	brawcap_filter_t *const	pFilter,
		BOOLEAN *const	pIndicate
	)

#include <brawcap.h>

Reads out the current network stack indication state of the specified filter.

Parameters

[in]	pFilter	The filter to read from.
[out]	pIndicate	Will contain the current network stack indication, afterwards.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.