#include <ws_symbol_export.h>
#include <epan/tvbuff.h>
#include <epan/proto.h>
#include <epan/expert.h>
#include <wsutil/wmem/wmem_list.h>

Classes
struct	wscbor_error_t
	Decoding or require_* error. More...

struct	wscbor_tag_t
	Tag metadata and value. More...

struct	wscbor_chunk_t
	A data-containing, optionally-tagged chunk of CBOR. More...

Typedefs
typedef enum cbor_type	cbor_type
	The same enumeration from libcbor-0.5.

typedef struct _wscbor_chunk_priv_t	wscbor_chunk_priv_t

Enumerations
enum	cbor_type { CBOR_TYPE_UINT = 0 , CBOR_TYPE_NEGINT = 1 , CBOR_TYPE_BYTESTRING = 2 , CBOR_TYPE_STRING = 3 , CBOR_TYPE_ARRAY = 4 , CBOR_TYPE_MAP = 5 , CBOR_TYPE_TAG = 6 , CBOR_TYPE_FLOAT_CTRL = 7 }
	The same enumeration from libcbor-0.5. More...

enum	_cbor_ctrl { CBOR_CTRL_NONE = 0 , CBOR_CTRL_FALSE = 20 , CBOR_CTRL_TRUE = 21 , CBOR_CTRL_NULL = 22 , CBOR_CTRL_UNDEF = 23 }
	The same enumeration from libcbor-0.5.

Functions
WS_DLL_PUBLIC void	wscbor_init (void)

WS_DLL_PUBLIC const ei_register_info *	wscbor_expert_items (int *size)

WS_DLL_PUBLIC wscbor_error_t *	wscbor_error_new (wmem_allocator_t alloc, expert_field ei, const char *format,...)

WS_DLL_PUBLIC wscbor_chunk_t *	wscbor_chunk_read (wmem_allocator_t alloc, tvbuff_t tvb, int *offset)

WS_DLL_PUBLIC void	wscbor_chunk_free (wscbor_chunk_t *chunk)

WS_DLL_PUBLIC uint64_t	wscbor_chunk_mark_errors (packet_info pinfo, proto_item item, const wscbor_chunk_t *chunk)

WS_DLL_PUBLIC unsigned	wscbor_has_errors (const wscbor_chunk_t *chunk)

WS_DLL_PUBLIC bool	wscbor_is_indefinite_break (const wscbor_chunk_t *chunk)

WS_DLL_PUBLIC bool	wscbor_skip_next_item (wmem_allocator_t alloc, tvbuff_t tvb, int *offset)

WS_DLL_PUBLIC bool	wscbor_skip_if_errors (wmem_allocator_t alloc, tvbuff_t tvb, int offset, const wscbor_chunk_t chunk)

WS_DLL_PUBLIC bool	wscbor_require_major_type (wscbor_chunk_t *chunk, cbor_type major)

WS_DLL_PUBLIC bool	wscbor_require_array (wscbor_chunk_t *chunk)

WS_DLL_PUBLIC bool	wscbor_require_array_size (wscbor_chunk_t *chunk, uint64_t count_min, uint64_t count_max)

WS_DLL_PUBLIC bool	wscbor_require_map (wscbor_chunk_t *chunk)

WS_DLL_PUBLIC bool *	wscbor_require_boolean (wmem_allocator_t alloc, wscbor_chunk_t chunk)

WS_DLL_PUBLIC uint64_t *	wscbor_require_uint64 (wmem_allocator_t alloc, wscbor_chunk_t chunk)

WS_DLL_PUBLIC int64_t *	wscbor_require_int64 (wmem_allocator_t alloc, wscbor_chunk_t chunk)

WS_DLL_PUBLIC char *	wscbor_require_tstr (wmem_allocator_t alloc, wscbor_chunk_t chunk)

WS_DLL_PUBLIC tvbuff_t *	wscbor_require_bstr (wmem_allocator_t alloc, wscbor_chunk_t chunk)

WS_DLL_PUBLIC proto_item *	proto_tree_add_cbor_container (proto_tree tree, int hfindex, packet_info pinfo, tvbuff_t tvb, const wscbor_chunk_t chunk)

WS_DLL_PUBLIC proto_item *	proto_tree_add_cbor_ctrl (proto_tree tree, int hfindex, packet_info pinfo, tvbuff_t tvb, const wscbor_chunk_t chunk)

WS_DLL_PUBLIC proto_item *	proto_tree_add_cbor_boolean (proto_tree tree, int hfindex, packet_info pinfo, tvbuff_t tvb, const wscbor_chunk_t chunk, const bool *value)

WS_DLL_PUBLIC proto_item *	proto_tree_add_cbor_uint64 (proto_tree tree, int hfindex, packet_info pinfo, tvbuff_t tvb, const wscbor_chunk_t chunk, const uint64_t *value)

WS_DLL_PUBLIC proto_item *	proto_tree_add_cbor_int64 (proto_tree tree, int hfindex, packet_info pinfo, tvbuff_t tvb, const wscbor_chunk_t chunk, const int64_t *value)

WS_DLL_PUBLIC proto_item *	proto_tree_add_cbor_bitmask (proto_tree tree, int hfindex, const int ett, int const fields, packet_info pinfo, tvbuff_t tvb, const wscbor_chunk_t chunk, const uint64_t *value)

WS_DLL_PUBLIC proto_item *	proto_tree_add_cbor_tstr (proto_tree tree, int hfindex, packet_info pinfo, tvbuff_t tvb, const wscbor_chunk_t chunk)

WS_DLL_PUBLIC proto_item *	proto_tree_add_cbor_bstr (proto_tree tree, int hfindex, packet_info pinfo, tvbuff_t tvb, const wscbor_chunk_t chunk)

WS_DLL_PUBLIC proto_item *	proto_tree_add_cbor_strlen (proto_tree tree, int hfindex, packet_info pinfo, tvbuff_t tvb, const wscbor_chunk_t chunk)

Detailed Description

Definitions for the Wireshark CBOR item decoding API. References: RFC 8949: https://tools.ietf.org/html/rfc8949

SPDX-License-Identifier: LGPL-2.1-or-later

Enumeration Type Documentation

◆ cbor_type

enum cbor_type

The same enumeration from libcbor-0.5.

Enumerator
CBOR_TYPE_UINT	positive integers
CBOR_TYPE_NEGINT	negative integers
CBOR_TYPE_BYTESTRING	byte strings
CBOR_TYPE_STRING	text strings
CBOR_TYPE_ARRAY	arrays
CBOR_TYPE_MAP	maps
CBOR_TYPE_TAG	tags
CBOR_TYPE_FLOAT_CTRL	decimals and special values (true, false, nil, ...)

Function Documentation

◆ proto_tree_add_cbor_container()

WS_DLL_PUBLIC proto_item * proto_tree_add_cbor_container	(	proto_tree *	tree,
		int	hfindex,
		packet_info *	pinfo,
		tvbuff_t *	tvb,
		const wscbor_chunk_t *	chunk
	)

Add an item representing an array or map container. If the item is type FT_UINT* or FT_INT* the count of (array) items or map (pairs) is used as the iterm value.

◆ proto_tree_add_cbor_ctrl()

WS_DLL_PUBLIC proto_item * proto_tree_add_cbor_ctrl	(	proto_tree *	tree,
		int	hfindex,
		packet_info *	pinfo,
		tvbuff_t *	tvb,
		const wscbor_chunk_t *	chunk
	)

Add an item representing a non-boolean, non-float control value.

◆ proto_tree_add_cbor_strlen()

WS_DLL_PUBLIC proto_item * proto_tree_add_cbor_strlen	(	proto_tree *	tree,
		int	hfindex,
		packet_info *	pinfo,
		tvbuff_t *	tvb,
		const wscbor_chunk_t *	chunk
	)

Add an item representing the length of a bstr or tstr value.

◆ wscbor_chunk_free()

WS_DLL_PUBLIC void wscbor_chunk_free ( wscbor_chunk_t * chunk )

Free a chunk and its lists.

◆ wscbor_chunk_mark_errors()

WS_DLL_PUBLIC uint64_t wscbor_chunk_mark_errors	(	packet_info *	pinfo,
		proto_item *	item,
		const wscbor_chunk_t *	chunk
	)

After both reading and decoding a chunk, report on any errors found.

Parameters

pinfo	The associated packet.
item	The associated tree item.
chunk	The chunk with possible errors.

Returns: The error count.

◆ wscbor_chunk_read()

WS_DLL_PUBLIC wscbor_chunk_t * wscbor_chunk_read	(	wmem_allocator_t *	alloc,
		tvbuff_t *	tvb,
		int *	offset
	)

Scan for a tagged chunk of headers. The chunk of byte string and text string items includes the data content in its offset.

Parameters

	alloc	The allocator to use.
	tvb	The TVB to read from.
[in,out]	offset	The offset with in `tvb`. This is updated to be just past the new chunk.

Returns: The chunk of data found, including any errors. This never returns NULL.

Postcondition: This can throw ReportedBoundsError or ContainedBoundsError if the read itself ran out of data.

◆ wscbor_error_new()

WS_DLL_PUBLIC wscbor_error_t * wscbor_error_new	(	wmem_allocator_t *	alloc,
		expert_field *	ei,
		const char *	format,
			...
	)

Construct a new error object.

Parameters

alloc	The allocator to use.
ei	The specific error type.
format	If non-NULL, a message format string.

Returns: The new object.

◆ wscbor_expert_items()

WS_DLL_PUBLIC const ei_register_info * wscbor_expert_items ( int * size )

Expose available expert info for this library.

Parameters

[out] size Set to the size of the array.

Returns: The array of expert info objects.

◆ wscbor_has_errors()

WS_DLL_PUBLIC unsigned wscbor_has_errors ( const wscbor_chunk_t * chunk )

Determine if a chunk has errors.

Parameters

chunk The chunk with possible errors.

Returns: The error count.

◆ wscbor_init()

WS_DLL_PUBLIC void wscbor_init ( void )

Register expert info and other wireshark data.

◆ wscbor_is_indefinite_break()

WS_DLL_PUBLIC bool wscbor_is_indefinite_break ( const wscbor_chunk_t * chunk )

Determine if an indefinite break is present.

Parameters

chunk The chunk to check.

Returns: True if it's an indefinite break.

◆ wscbor_require_array()

WS_DLL_PUBLIC bool wscbor_require_array ( wscbor_chunk_t * chunk )

Require an array item.

Parameters

[in,out] chunk The chunk to read from and write errors on.

Returns: True if the item is an array.

◆ wscbor_require_array_size()

WS_DLL_PUBLIC bool wscbor_require_array_size	(	wscbor_chunk_t *	chunk,
		uint64_t	count_min,
		uint64_t	count_max
	)

Require an array have a specific ranged size.

Parameters

[in,out]	chunk	The chunk to read from and write errors on.
	count_min	The minimum acceptable size.
	count_max	The maximum acceptable size.

Returns: True if the size is acceptable.

◆ wscbor_require_boolean()

WS_DLL_PUBLIC bool * wscbor_require_boolean	(	wmem_allocator_t *	alloc,
		wscbor_chunk_t *	chunk
	)

Require a CBOR item to have a boolean value.

Parameters

	alloc	The allocator to use.
[in,out]	chunk	The chunk to read from and write errors on.

Returns: Pointer to the boolean value, if the item was boolean. The value can be deleted with wscbor_require_delete().

◆ wscbor_require_bstr()

WS_DLL_PUBLIC tvbuff_t * wscbor_require_bstr	(	wmem_allocator_t *	alloc,
		wscbor_chunk_t *	chunk
	)

Require a CBOR item to have a byte-string value. Use tvb_memdup() or similar if the raw byte-string is needed.

Parameters

	alloc	The allocator to use.
[in,out]	chunk	The chunk to read from and write errors on.

Returns: Pointer to the value, if the item was an bstr. The value is memory managed by wireshark.

◆ wscbor_require_int64()

WS_DLL_PUBLIC int64_t * wscbor_require_int64	(	wmem_allocator_t *	alloc,
		wscbor_chunk_t *	chunk
	)

Require a CBOR item to have an signed- or unsigned-integer value.

Note: This reader will clip the most significant bit of the value.

Parameters

	alloc	The allocator to use.
[in,out]	chunk	The chunk to read from and write errors on.

Returns: Pointer to the value, if the item was an integer. The value can be deleted with wscbor_require_delete().

◆ wscbor_require_major_type()

WS_DLL_PUBLIC bool wscbor_require_major_type	(	wscbor_chunk_t *	chunk,
		cbor_type	major
	)

Require a specific item major type.

Parameters

[in,out]	chunk	The chunk to read from and write errors on.
	major	The required major type.

Returns: True if the item is that type.

◆ wscbor_require_map()

WS_DLL_PUBLIC bool wscbor_require_map ( wscbor_chunk_t * chunk )

Require a map item.

Parameters

[in,out] chunk The chunk to read from and write errors on.

Returns: True if the item is a map.

◆ wscbor_require_tstr()

WS_DLL_PUBLIC char * wscbor_require_tstr	(	wmem_allocator_t *	alloc,
		wscbor_chunk_t *	chunk
	)

Require a CBOR item to have a text-string value. If the actual text string is not needed, use the following to avoid an unnecessary allocation.

wscbor_require_major_type(chunk, CBOR_TYPE_STRING)

CBOR_TYPE_STRING

@ CBOR_TYPE_STRING

text strings

Definition wscbor.h:45

Parameters

	alloc	The allocator to use.
[in,out]	chunk	The chunk to read from and write errors on.

Returns: Pointer to the null-terminated UTF-8, if the item was a tstr.

Postcondition: This can throw ContainedBoundsError string ran out of data.

◆ wscbor_require_uint64()

WS_DLL_PUBLIC uint64_t * wscbor_require_uint64	(	wmem_allocator_t *	alloc,
		wscbor_chunk_t *	chunk
	)

Require a CBOR item to have an unsigned-integer value.

Note: This reader will clip the most significant bit of the value.

Parameters

	alloc	The allocator to use.
[in,out]	chunk	The chunk to read from and write errors on.

Returns: Pointer to the boolean value, if the item was an integer. The value can be deleted with wscbor_require_delete().

◆ wscbor_skip_if_errors()

WS_DLL_PUBLIC bool wscbor_skip_if_errors	(	wmem_allocator_t *	alloc,
		tvbuff_t *	tvb,
		int *	offset,
		const wscbor_chunk_t *	chunk
	)

Skip over an item if a chunk has errors. This allows skipping an entire array or map if the major type or size is not as expected.

Parameters

	alloc	The allocator to use.
	tvb	The data buffer.
[in,out]	offset	The initial offset to read and skip over.
	chunk	The chunk with possible errors.

Returns: True if there were errors and the item skipped.

◆ wscbor_skip_next_item()

WS_DLL_PUBLIC bool wscbor_skip_next_item	(	wmem_allocator_t *	alloc,
		tvbuff_t *	tvb,
		int *	offset
	)

Recursively skip items from a stream.

Parameters

	alloc	The allocator to use.
	tvb	The data buffer.
[in,out]	offset	The initial offset to read and skip over. Will be set to one-past the last valid CBOR (possibly nested) present.

Returns: True if the skipped item was fully valid.

Postcondition: This can throw ReportedBoundsError or ContainedBoundsError if the read itself ran out of data.

Classes

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ cbor_type

Function Documentation

◆ proto_tree_add_cbor_container()

◆ proto_tree_add_cbor_ctrl()

◆ proto_tree_add_cbor_strlen()

◆ wscbor_chunk_free()

◆ wscbor_chunk_mark_errors()

◆ wscbor_chunk_read()

◆ wscbor_error_new()

◆ wscbor_expert_items()

◆ wscbor_has_errors()

◆ wscbor_init()

◆ wscbor_is_indefinite_break()

◆ wscbor_require_array()

◆ wscbor_require_array_size()

◆ wscbor_require_boolean()

◆ wscbor_require_bstr()

◆ wscbor_require_int64()

◆ wscbor_require_major_type()

◆ wscbor_require_map()

◆ wscbor_require_tstr()

◆ wscbor_require_uint64()

◆ wscbor_skip_if_errors()

◆ wscbor_skip_next_item()