| Wireshark 4.7.0 The Wireshark network protocol analyzer

Loading...
Searching...
No Matches
Classes | Typedefs | Enumerations | Functions
wscbor.h File Reference
`#include <ws_symbol_export.h>`
`#include <epan/tvbuff.h>`
`#include <epan/proto.h>`
`#include <epan/expert.h>`
`#include <wsutil/wmem/wmem_list.h>`

Go to the source code of this file.

## 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,...) G_GNUC_PRINTF(3
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

Copyright 2019-2021, Brian Sipos brian.nosp@m..sip.nosp@m.os@gm.nosp@m.ail..nosp@m.com

Wireshark - Network traffic analyzer By Gerald Combs geral.nosp@m.d@wi.nosp@m.resha.nosp@m.rk.o.nosp@m.rg Copyright 1998 Gerald Combs

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 item 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.