hzl_ClientOs.h File Reference

Hazelnet Client public API, addon for Operating Systems. More...

#include "hzl.h"
#include "hzl_Client.h"

Include dependency graph for hzl_ClientOs.h:

Go to the source code of this file.

Functions
HZL_API hzl_Err_t	hzl_ClientNew (hzl_ClientCtx_t **pCtx, const char *fileName)
	Allocates a new context structure on the heap and fills it with the new configuration from the file and OS functions for time and randomness. More...
HZL_API void	hzl_ClientFree (hzl_ClientCtx_t **pCtx)
	Zeros-out the context, frees it and sets the pointer to it to NULL, to avoid use-after-free and double-free. More...
HZL_API hzl_Err_t	hzl_ClientNewMsg (hzl_CbsPduMsg_t **pMsg)
	Allocates a new CAN FD message structure on the heap with enough space to hold up to 64 B of data. More...
HZL_API void	hzl_ClientFreeMsg (hzl_CbsPduMsg_t **pMsg)
	Zeros-out the message, frees it and sets the pointer to it to NULL, to avoid use-after-free and double-free. More...

Detailed Description

Hazelnet Client public API, addon for Operating Systems.

Hazelnet implements the CAN Bus Security (CBS) protocol, which secures the CAN FD traffic providing encryption, authenticity and freshness of the messages.

This header adds to the hzl_Client.h header, providing a simpler alternative for desktop usage on an OS like Windows or Linux compared to an embedded usage. This API allows the user to heap-allocate the Client context, load its configuration from file and assign the timestamping and TRNG functions automatically by using the ones provided by the OS. Similarly, heap-allocation of messages is also available.

Function Documentation

hzl_ClientNew()

HZL_API hzl_Err_t hzl_ClientNew	(	hzl_ClientCtx_t **	pCtx,
		const char *	fileName
	)

Allocates a new context structure on the heap and fills it with the new configuration from the file and OS functions for time and randomness.

This is a handy replacement of hzl_ClientInit() to use when on an OS to simplify the library usage. The function would automatically allocate the context and fill its configuration fields from the file. The IO functions for TRNG and timestamping are also obtained from the OS. The user must only supply the low level transmission function and the file name where to take the configuration from.

It's up to the user to free the context allocated by this function using hzl_ClientFree().

File format

The file must have the following format with all multi-byte integers encoded as little Endian and without any paddings between any value or between any struct:

1. "HZL\0" as a magic number in ASCII encoding, used to double-check that the loaded file is the correct one. That is: [0x48, 0x5A, 0x4C, 0x00] in binary;
2. the whole hzl_ClientConfig_t struct without any padding;
3. an array of hzl_ClientGroupConfig_t structs without any padding and with as many elements (structs) as specified in hzl_ClientConfig_t.amountOfGroups.

It's common to use the .hzl file extension to denote this file format. To generate such binary file from a JSON file, the helper Python scripts in toolsupport/config can be used.

Parameters

[out]	pCtx	where to load the new context. Must not be NULL.
[in]	fileName	path to the file to load the configuration from. Must not be NULL.

Return values

HZL_OK	on success.
HZL_ERR_NULL_CTX	if pCtx is NULL.
HZL_ERR_NULL_FILENAME	if fileName is NULL.
HZL_ERR_CANNOT_OPEN_CONFIG_FILE	if the file cannot be opened (does not exists, or the permissions are not correct)
HZL_ERR_MALLOC_FAILED	if the heap-allocation fails (out of memory).
HZL_ERR_UNEXPECTED_EOF	if the file is too short: more data was expected during parsing. Probably is has incorrect syntax or amount of groups.
Same	values as hzl_ClientInit() in case the context has incorrect data or pointers.

hzl_ClientFree()

HZL_API void hzl_ClientFree

(

hzl_ClientCtx_t **

pCtx

)

Zeros-out the context, frees it and sets the pointer to it to NULL, to avoid use-after-free and double-free.

If some fields are partially-initialised, it clears and frees anything not-NULL.

Warning

Only use on heap-allocated contexts, as created by hzl_ClientNew().

Parameters

[in]

pCtx

address of the pointer to the context. The address of it is used to set the pointer to NULL after the data has been freed. If NULL or if *pCtx is NULL, the function does nothing.

hzl_ClientNewMsg()

HZL_API hzl_Err_t hzl_ClientNewMsg

(

hzl_CbsPduMsg_t **

pMsg

)

Allocates a new CAN FD message structure on the heap with enough space to hold up to 64 B of data.

It's up to the user to free the message allocated by this function using hzl_ClientFreeMsg().

Parameters

[out]

pMsg

where to load the new message. Must not be NULL.

Return values

HZL_OK	on success.
HZL_ERR_NULL_PDU	if pMsg is NULL.
HZL_ERR_MALLOC_FAILED	if the heap-allocation fails (out of memory).

hzl_ClientFreeMsg()

HZL_API void hzl_ClientFreeMsg

(

hzl_CbsPduMsg_t **

pMsg

)

Zeros-out the message, frees it and sets the pointer to it to NULL, to avoid use-after-free and double-free.

If some fields are partially-initialised, it clears and frees anything not-NULL.

Warning

Only use on heap-allocated messages, as created by hzl_ClientNewMsg().

Parameters

[in]

pMsg

address of the pointer to the message. The address of it is used to set the pointer to NULL after the data has been freed. If NULL or if *pMsg is NULL, the function does nothing.