Miscellaneous

Checksum APIs

CRC

group crc

Functions

uint16_t crc16(uint16_t poly, uint16_t seed, const uint8_t *src, size_t len)

Generic function for computing a CRC-16 without input or output reflection.

Compute CRC-16 by passing in the address of the input, the input length and polynomial used in addition to the initial value. This is O(n*8) where n is the length of the buffer provided. No reflection is performed.

Note

If you are planning to use a CRC based on poly 0x1012 the functions crc16_itu_t() is faster and thus recommended over this one.

Parameters

  • poly – The polynomial to use omitting the leading x^16 coefficient

  • seed – Initial value for the CRC computation

  • src – Input bytes for the computation

  • len – Length of the input in bytes

Returns

The computed CRC16 value (without any XOR applied to it)

uint16_t crc16_reflect(uint16_t poly, uint16_t seed, const uint8_t *src, size_t len)

Generic function for computing a CRC-16 with input and output reflection.

Compute CRC-16 by passing in the address of the input, the input length and polynomial used in addition to the initial value. This is O(n*8) where n is the length of the buffer provided. Both input and output are reflected.

The following checksums can, among others, be calculated by this function, depending on the value provided for the initial seed and the value the final calculated CRC is XORed with:

Note

If you are planning to use a CRC based on poly 0x1012 the function crc16_ccitt() is faster and thus recommended over this one.

Parameters

  • poly – The polynomial to use omitting the leading x^16 coefficient. Important: please reflect the poly. For example, use 0xA001 instead of 0x8005 for CRC-16-MODBUS.

  • seed – Initial value for the CRC computation

  • src – Input bytes for the computation

  • len – Length of the input in bytes

Returns

The computed CRC16 value (without any XOR applied to it)

uint8_t crc8(const uint8_t *src, size_t len, uint8_t polynomial, uint8_t initial_value, bool reversed)

Generic function for computing CRC 8.

Compute CRC 8 by passing in the address of the input, the input length and polynomial used in addition to the initial value.

Parameters

  • src – Input bytes for the computation

  • len – Length of the input in bytes

  • polynomial – The polynomial to use omitting the leading x^8 coefficient

  • initial_value – Initial value for the CRC computation

  • reversed – Should we use reflected/reversed values or not

Returns

The computed CRC8 value

uint16_t crc16_ccitt(uint16_t seed, const uint8_t *src, size_t len)

Compute the checksum of a buffer with polynomial 0x1021, reflecting input and output.

This function is able to calculate any CRC that uses 0x1021 as it polynomial and requires reflecting both the input and the output. It is a fast variant that runs in O(n) time, where n is the length of the input buffer.

The following checksums can, among others, be calculated by this function, depending on the value provided for the initial seed and the value the final calculated CRC is XORed with:

See ITU-T Recommendation V.41 (November 1988).

Note

To calculate the CRC across non-contiguous blocks use the return value from block N-1 as the seed for block N.

Parameters

  • seed – Value to seed the CRC with

  • src – Input bytes for the computation

  • len – Length of the input in bytes

Returns

The computed CRC16 value (without any XOR applied to it)

uint16_t crc16_itu_t(uint16_t seed, const uint8_t *src, size_t len)

Compute the checksum of a buffer with polynomial 0x1021, no reflection of input or output.

This function is able to calculate any CRC that uses 0x1021 as it polynomial and requires no reflection on both the input and the output. It is a fast variant that runs in O(n) time, where n is the length of the input buffer.

The following checksums can, among others, be calculated by this function, depending on the value provided for the initial seed and the value the final calculated CRC is XORed with:

See ITU-T Recommendation V.41 (November 1988) (MSB first).

Note

To calculate the CRC across non-contiguous blocks use the return value from block N-1 as the seed for block N.

Parameters

  • seed – Value to seed the CRC with

  • src – Input bytes for the computation

  • len – Length of the input in bytes

Returns

The computed CRC16 value (without any XOR applied to it)

static inline uint16_t crc16_ansi(const uint8_t *src, size_t len)

Compute the ANSI (or Modbus) variant of CRC-16.

The ANSI variant of CRC-16 uses 0x8005 (0xA001 reflected) as its polynomial with the initial * value set to 0xffff.

Parameters

  • src – Input bytes for the computation

  • len – Length of the input in bytes

Returns

The computed CRC16 value

uint32_t crc32_ieee(const uint8_t *data, size_t len)

Generate IEEE conform CRC32 checksum.

Parameters

  • *data – Pointer to data on which the CRC should be calculated.

  • len – Data length.

Returns

CRC32 value.

uint32_t crc32_ieee_update(uint32_t crc, const uint8_t *data, size_t len)

Update an IEEE conforming CRC32 checksum.

Parameters

  • crc – CRC32 checksum that needs to be updated.

  • *data – Pointer to data on which the CRC should be calculated.

  • len – Data length.

Returns

CRC32 value.

uint32_t crc32_c(uint32_t crc, const uint8_t *data, size_t len, bool first_pkt, bool last_pkt)

Calculate CRC32C (Castagnoli) checksum.

Parameters

  • crc – CRC32C checksum that needs to be updated.

  • *data – Pointer to data on which the CRC should be calculated.

  • len – Data length.

  • first_pkt – Whether this is the first packet in the stream.

  • last_pkt – Whether this is the last packet in the stream.

Returns

CRC32 value.

uint8_t crc8_ccitt(uint8_t initial_value, const void *buf, size_t len)

Compute CCITT variant of CRC 8.

Normal CCITT variant of CRC 8 is using 0x07.

Parameters

  • initial_value – Initial value for the CRC computation

  • buf – Input bytes for the computation

  • len – Length of the input in bytes

Returns

The computed CRC8 value

uint8_t crc7_be(uint8_t seed, const uint8_t *src, size_t len)

Compute the CRC-7 checksum of a buffer.

See JESD84-A441. Used by the MMC protocol. Uses 0x09 as the polynomial with no reflection. The CRC is left justified, so bit 7 of the result is bit 6 of the CRC.

Parameters

  • seed – Value to seed the CRC with

  • src – Input bytes for the computation

  • len – Length of the input in bytes

Returns

The computed CRC7 value

Structured Data APIs

JSON

group json

Defines

JSON_OBJ_DESCR_PRIM(struct_, field_name_, type_)

Helper macro to declare a descriptor for supported primitive values.

Here’s an example of use: 

struct foo {
    int some_int;
};

struct json_obj_descr foo[] = {
    JSON_OBJ_DESCR_PRIM(struct foo, some_int, JSON_TOK_NUMBER),
};

Parameters

  • struct_ – Struct packing the values

  • field_name_ – Field name in the struct

  • type_ – Token type for JSON value corresponding to a primitive type. Must be one of: JSON_TOK_STRING for strings, JSON_TOK_NUMBER for numbers, JSON_TOK_TRUE (or JSON_TOK_FALSE) for booleans.

JSON_OBJ_DESCR_OBJECT(struct_, field_name_, sub_descr_)

Helper macro to declare a descriptor for an object value.

Here’s an example of use: 

 struct nested {
     int foo;
     struct {
        int baz;
     } bar;
 };

 struct json_obj_descr nested_bar[] = {
     { ... declare bar.baz descriptor ... },
 };
 struct json_obj_descr nested[] = {
     { ... declare foo descriptor ... },
     JSON_OBJ_DESCR_OBJECT(struct nested, bar, nested_bar),
 };

Parameters

  • struct_ – Struct packing the values

  • field_name_ – Field name in the struct

  • sub_descr_ – Array of json_obj_descr describing the subobject

JSON_OBJ_DESCR_ARRAY(struct_, field_name_, max_len_, len_field_, elem_type_)

Helper macro to declare a descriptor for an array of primitives.

Here’s an example of use: 

 struct example {
     int foo[10];
     size_t foo_len;
 };

 struct json_obj_descr array[] = {
      JSON_OBJ_DESCR_ARRAY(struct example, foo, 10, foo_len,
                           JSON_TOK_NUMBER)
 };

Parameters

  • struct_ – Struct packing the values

  • field_name_ – Field name in the struct

  • max_len_ – Maximum number of elements in array

  • len_field_ – Field name in the struct for the number of elements in the array

  • elem_type_ – Element type, must be a primitive type

JSON_OBJ_DESCR_OBJ_ARRAY(struct_, field_name_, max_len_, len_field_, elem_descr_, elem_descr_len_)

Helper macro to declare a descriptor for an array of objects.

Here’s an example of use: 

 struct person_height {
     const char *name;
     int height;
 };

 struct people_heights {
     struct person_height heights[10];
     size_t heights_len;
 };

 struct json_obj_descr person_height_descr[] = {
      JSON_OBJ_DESCR_PRIM(struct person_height, name, JSON_TOK_STRING),
      JSON_OBJ_DESCR_PRIM(struct person_height, height, JSON_TOK_NUMBER),
 };

 struct json_obj_descr array[] = {
      JSON_OBJ_DESCR_OBJ_ARRAY(struct people_heights, heights, 10,
                               heights_len, person_height_descr,
                               ARRAY_SIZE(person_height_descr)),
 };

Parameters

  • struct_ – Struct packing the values

  • field_name_ – Field name in the struct containing the array

  • max_len_ – Maximum number of elements in the array

  • len_field_ – Field name in the struct for the number of elements in the array

  • elem_descr_ – Element descriptor, pointer to a descriptor array

  • elem_descr_len_ – Number of elements in elem_descr_

JSON_OBJ_DESCR_ARRAY_ARRAY(struct_, field_name_, max_len_, len_field_, elem_descr_, elem_descr_len_)

Helper macro to declare a descriptor for an array of array.

Here’s an example of use: 

 struct person_height {
     const char *name;
     int height;
 };

 struct person_heights_array {
     struct person_height heights;
 }

 struct people_heights {
     struct person_height_array heights[10];
     size_t heights_len;
 };

 struct json_obj_descr person_height_descr[] = {
     JSON_OBJ_DESCR_PRIM(struct person_height, name, JSON_TOK_STRING),
     JSON_OBJ_DESCR_PRIM(struct person_height, height, JSON_TOK_NUMBER),
 };

 struct json_obj_descr person_height_array_descr[] = {
     JSON_OBJ_DESCR_OBJECT(struct person_heights_array,
                           heights, person_height_descr),
 };

 struct json_obj_descr array_array[] = {
      JSON_OBJ_DESCR_ARRAY_ARRAY(struct people_heights, heights, 10,
                                 heights_len, person_height_array_descr,
                                 ARRAY_SIZE(person_height_array_descr)),
 };

Parameters

  • struct_ – Struct packing the values

  • field_name_ – Field name in the struct containing the array

  • max_len_ – Maximum number of elements in the array

  • len_field_ – Field name in the struct for the number of elements in the array

  • elem_descr_ – Element descriptor, pointer to a descriptor array

  • elem_descr_len_ – Number of elements in elem_descr_

JSON_OBJ_DESCR_PRIM_NAMED(struct_, json_field_name_, struct_field_name_, type_)

Variant of JSON_OBJ_DESCR_PRIM that can be used when the structure and JSON field names differ.

This is useful when the JSON field is not a valid C identifier.

See also

JSON_OBJ_DESCR_PRIM

Parameters

  • struct_ – Struct packing the values.

  • json_field_name_ – String, field name in JSON strings

  • struct_field_name_ – Field name in the struct

  • type_ – Token type for JSON value corresponding to a primitive type.

JSON_OBJ_DESCR_OBJECT_NAMED(struct_, json_field_name_, struct_field_name_, sub_descr_)

Variant of JSON_OBJ_DESCR_OBJECT that can be used when the structure and JSON field names differ.

This is useful when the JSON field is not a valid C identifier.

See also

JSON_OBJ_DESCR_OBJECT

Parameters

  • struct_ – Struct packing the values

  • json_field_name_ – String, field name in JSON strings

  • struct_field_name_ – Field name in the struct

  • sub_descr_ – Array of json_obj_descr describing the subobject

JSON_OBJ_DESCR_ARRAY_NAMED(struct_, json_field_name_, struct_field_name_, max_len_, len_field_, elem_type_)

Variant of JSON_OBJ_DESCR_ARRAY that can be used when the structure and JSON field names differ.

This is useful when the JSON field is not a valid C identifier.

See also

JSON_OBJ_DESCR_ARRAY

Parameters

  • struct_ – Struct packing the values

  • json_field_name_ – String, field name in JSON strings

  • struct_field_name_ – Field name in the struct

  • max_len_ – Maximum number of elements in array

  • len_field_ – Field name in the struct for the number of elements in the array

  • elem_type_ – Element type, must be a primitive type

JSON_OBJ_DESCR_OBJ_ARRAY_NAMED(struct_, json_field_name_, struct_field_name_, max_len_, len_field_, elem_descr_, elem_descr_len_)

Variant of JSON_OBJ_DESCR_OBJ_ARRAY that can be used when the structure and JSON field names differ.

This is useful when the JSON field is not a valid C identifier.

Here’s an example of use: 

 struct person_height {
     const char *name;
     int height;
 };

 struct people_heights {
     struct person_height heights[10];
     size_t heights_len;
 };

 struct json_obj_descr person_height_descr[] = {
      JSON_OBJ_DESCR_PRIM(struct person_height, name, JSON_TOK_STRING),
      JSON_OBJ_DESCR_PRIM(struct person_height, height, JSON_TOK_NUMBER),
 };

 struct json_obj_descr array[] = {
      JSON_OBJ_DESCR_OBJ_ARRAY_NAMED(struct people_heights,
                                     "people-heights", heights,
                                     10, heights_len,
                                     person_height_descr,
                                     ARRAY_SIZE(person_height_descr)),
 };

Parameters

  • struct_ – Struct packing the values

  • json_field_name_ – String, field name of the array in JSON strings

  • struct_field_name_ – Field name in the struct containing the array

  • max_len_ – Maximum number of elements in the array

  • len_field_ – Field name in the struct for the number of elements in the array

  • elem_descr_ – Element descriptor, pointer to a descriptor array

  • elem_descr_len_ – Number of elements in elem_descr_

Typedefs

typedef int (*json_append_bytes_t)(const char *bytes, size_t len, void *data)

Function pointer type to append bytes to a buffer while encoding JSON data.

Param bytes

Contents to write to the output

Param len

Number of bytes to append to output

Param data

User-provided pointer

Return

This callback function should return a negative number on error (which will be propagated to the return value of json_obj_encode()), or 0 on success.

Enums

enum json_tokens

Values:

enumerator JSON_TOK_NONE = '_'
enumerator JSON_TOK_OBJECT_START = '{'
enumerator JSON_TOK_OBJECT_END = '}'
enumerator JSON_TOK_LIST_START = '['
enumerator JSON_TOK_ARRAY_START = '['
enumerator JSON_TOK_LIST_END = ']'
enumerator JSON_TOK_ARRAY_END = ']'
enumerator JSON_TOK_STRING = '"'
enumerator JSON_TOK_COLON = ':'
enumerator JSON_TOK_COMMA = ','
enumerator JSON_TOK_NUMBER = '0'
enumerator JSON_TOK_FLOAT = '1'
enumerator JSON_TOK_OPAQUE = '2'
enumerator JSON_TOK_OBJ_ARRAY = '3'
enumerator JSON_TOK_TRUE = 't'
enumerator JSON_TOK_FALSE = 'f'
enumerator JSON_TOK_NULL = 'n'
enumerator JSON_TOK_ERROR = '!'
enumerator JSON_TOK_EOF = '\0'

Functions

int json_obj_parse(char *json, size_t len, const struct json_obj_descr *descr, size_t descr_len, void *val)

Parses the JSON-encoded object pointed to by json, with size len, according to the descriptor pointed to by descr. Values are stored in a struct pointed to by val. Set up the descriptor like this:

struct s { int foo; char *bar; } struct json_obj_descr descr[] = { JSON_OBJ_DESCR_PRIM(struct s, foo, JSON_TOK_NUMBER), JSON_OBJ_DESCR_PRIM(struct s, bar, JSON_TOK_STRING), };

Since this parser is designed for machine-to-machine communications, some liberties were taken to simplify the design: (1) strings are not unescaped (but only valid escape sequences are accepted); (2) no UTF-8 validation is performed; and (3) only integer numbers are supported (no strtod() in the minimal libc).

Parameters

  • json – Pointer to JSON-encoded value to be parsed

  • len – Length of JSON-encoded value

  • descr – Pointer to the descriptor array

  • descr_len – Number of elements in the descriptor array. Must be less than 31 due to implementation detail reasons (if more fields are necessary, use two descriptors)

  • val – Pointer to the struct to hold the decoded values

Returns

< 0 if error, bitmap of decoded fields on success (bit 0 is set if first field in the descriptor has been properly decoded, etc).

int json_arr_parse(char *json, size_t len, const struct json_obj_descr *descr, void *val)

Parses the JSON-encoded array pointed to by json, with size len, according to the descriptor pointed to by descr. Values are stored in a struct pointed to by val. Set up the descriptor like this:

struct s { int foo; char *bar; } struct json_obj_descr descr[] = { JSON_OBJ_DESCR_PRIM(struct s, foo, JSON_TOK_NUMBER), JSON_OBJ_DESCR_PRIM(struct s, bar, JSON_TOK_STRING), }; struct a { struct s baz[10]; size_t count; } struct json_obj_descr array[] = { JSON_OBJ_DESCR_OBJ_ARRAY(struct a, baz, 10, count,descr, ARRAY_SIZE(descr)), };

Since this parser is designed for machine-to-machine communications, some liberties were taken to simplify the design: (1) strings are not unescaped (but only valid escape sequences are accepted); (2) no UTF-8 validation is performed; and (3) only integer numbers are supported (no strtod() in the minimal libc).

Parameters

  • json – Pointer to JSON-encoded array to be parsed

  • len – Length of JSON-encoded array

  • descr – Pointer to the descriptor array

  • val – Pointer to the struct to hold the decoded values

Returns

0 if array has been successfully parsed. A negative value indicates an error (as defined on errno.h).

int json_arr_separate_object_parse_init(struct json_obj *json, char *payload, size_t len)

Initialize single-object array parsing.

JSON-encoded array data is going to be parsed one object at a time. Data is provided by payload with the size of len bytes.

Function validate that Json Array start is detected and initialize json object for Json object parsing separately.

Parameters

  • json – Provide storage for parser states. To be used when parsing the array.

  • payload – Pointer to JSON-encoded array to be parsed

  • len – Length of JSON-encoded array

Returns

0 if array start is detected and initialization is successful or negative error code in case of failure.

int json_arr_separate_parse_object(struct json_obj *json, const struct json_obj_descr *descr, size_t descr_len, void *val)

Parse a single object from array.

Parses the JSON-encoded object pointed to by json object array, with size len, according to the descriptor pointed to by descr.

Parameters

  • json – Pointer to JSON-object message state

  • descr – Pointer to the descriptor array

  • descr_len – Number of elements in the descriptor array. Must be less than 31.

  • val – Pointer to the struct to hold the decoded values

Returns

< 0 if error, 0 for end of message, bitmap of decoded fields on success (bit 0 is set if first field in the descriptor has been properly decoded, etc).

ssize_t json_escape(char *str, size_t *len, size_t buf_size)

Escapes the string so it can be used to encode JSON objects.

Parameters

  • str – The string to escape; the escape string is stored the buffer pointed to by this parameter

  • len – Points to a size_t containing the size before and after the escaping process

  • buf_size – The size of buffer str points to

Returns

0 if string has been escaped properly, or -ENOMEM if there was not enough space to escape the buffer

size_t json_calc_escaped_len(const char *str, size_t len)

Calculates the JSON-escaped string length.

Parameters

  • str – The string to analyze

  • len – String size

Returns

The length str would have if it were escaped

ssize_t json_calc_encoded_len(const struct json_obj_descr *descr, size_t descr_len, const void *val)

Calculates the string length to fully encode an object.

Parameters

  • descr – Pointer to the descriptor array

  • descr_len – Number of elements in the descriptor array

  • val – Struct holding the values

Returns

Number of bytes necessary to encode the values if >0, an error code is returned.

int json_obj_encode_buf(const struct json_obj_descr *descr, size_t descr_len, const void *val, char *buffer, size_t buf_size)

Encodes an object in a contiguous memory location.

Parameters

  • descr – Pointer to the descriptor array

  • descr_len – Number of elements in the descriptor array

  • val – Struct holding the values

  • buffer – Buffer to store the JSON data

  • buf_size – Size of buffer, in bytes, with space for the terminating NUL character

Returns

0 if object has been successfully encoded. A negative value indicates an error (as defined on errno.h).

int json_arr_encode_buf(const struct json_obj_descr *descr, const void *val, char *buffer, size_t buf_size)

Encodes an array in a contiguous memory location.

Parameters

  • descr – Pointer to the descriptor array

  • val – Struct holding the values

  • buffer – Buffer to store the JSON data

  • buf_size – Size of buffer, in bytes, with space for the terminating NUL character

Returns

0 if object has been successfully encoded. A negative value indicates an error (as defined on errno.h).

int json_obj_encode(const struct json_obj_descr *descr, size_t descr_len, const void *val, json_append_bytes_t append_bytes, void *data)

Encodes an object using an arbitrary writer function.

Parameters

  • descr – Pointer to the descriptor array

  • descr_len – Number of elements in the descriptor array

  • val – Struct holding the values

  • append_bytes – Function to append bytes to the output

  • data – Data pointer to be passed to the append_bytes callback function.

Returns

0 if object has been successfully encoded. A negative value indicates an error.

int json_arr_encode(const struct json_obj_descr *descr, const void *val, json_append_bytes_t append_bytes, void *data)

Encodes an array using an arbitrary writer function.

Parameters

  • descr – Pointer to the descriptor array

  • val – Struct holding the values

  • append_bytes – Function to append bytes to the output

  • data – Data pointer to be passed to the append_bytes callback function.

Returns

0 if object has been successfully encoded. A negative value indicates an error.

struct json_token
#include <json.h>
struct json_lexer
#include <json.h>
struct json_obj
#include <json.h>
struct json_obj_token
#include <json.h>
struct json_obj_descr
#include <json.h>

JWT

JSON Web Tokens (JWT) are an open, industry standard [RFC 7519](https://tools.ietf.org/html/rfc7519) method for representing claims securely between two parties. Although JWT is fairly flexible, this API is limited to creating the simplistic tokens needed to authenticate with the Google Core IoT infrastructure.

group jwt

JSON Web Token (JWT)

Functions

int jwt_init_builder(struct jwt_builder *builder, char *buffer, size_t buffer_size)

Initialize the JWT builder.

Initialize the given JWT builder for the creation of a fresh token. The buffer size should at least be as long as JWT_BUILDER_MAX_SIZE returns.

Parameters

  • builder – The builder to initialize.

  • buffer – The buffer to write the token to.

  • buffer_size – The size of this buffer. The token will be NULL terminated, which needs to be allowed for in this size.

Return values

  • 0 – Success

  • -ENOSPC – Buffer is insufficient to initialize

int jwt_add_payload(struct jwt_builder *builder, int32_t exp, int32_t iat, const char *aud)

add JWT primary payload.

int jwt_sign(struct jwt_builder *builder, const char *der_key, size_t der_key_len)

Sign the JWT token.

static inline size_t jwt_payload_len(struct jwt_builder *builder)
struct jwt_builder
#include <jwt.h>

JWT data tracking.

JSON Web Tokens contain several sections, each encoded in base-64. This structure tracks the token as it is being built, including limits on the amount of available space. It should be initialized with jwt_init().

Public Members

char *base

The base of the buffer we are writing to.

char *buf

The place in this buffer where we are currently writing.

size_t len

The length remaining to write.

bool overflowed

Flag that is set if we try to write past the end of the buffer. If set, the token is not valid.