trust_list.h File Reference

Trust List module. More...

#include <stdint.h>
#include <stdbool.h>
#include <virgil/iot/secmodule/secmodule.h>
#include <virgil/iot/storage_hal/storage_hal.h>
#include <virgil/iot/status_code/status_code.h>
#include <virgil/iot/update/update.h>
#include <virgil/iot/trust_list/tl_structs.h>

Go to the source code of this file.

Functions
vs_status_e	vs_tl_init (vs_storage_op_ctx_t *op_ctx, vs_secmodule_impl_t *secmodule, vs_file_ver_info_cb_t ver_info_cb)
	Trust List initialization. More...
vs_status_e	vs_tl_deinit (void)
	Trust List destruction. More...
vs_status_e	vs_tl_save_part (vs_tl_element_info_t *element_info, const uint8_t *in_data, uint16_t data_sz)
	Trust List element saving. More...
vs_status_e	vs_tl_load_part (vs_tl_element_info_t *element_info, uint8_t *out_data, uint16_t buf_sz, uint16_t *out_sz)
	Trust List element loading. More...
vs_update_interface_t *	vs_tl_update_ctx (void)
	Update interface for Trust List. More...
const vs_update_file_type_t *	vs_tl_update_file_type (void)
	Trust List file type. More...
void	vs_tl_header_to_host (const vs_tl_header_t *src_data, vs_tl_header_t *dst_data)
	Convert Trust List header to host. More...
void	vs_tl_header_to_net (const vs_tl_header_t *src_data, vs_tl_header_t *dst_data)
	Convert Trust List header to network. More...

Detailed Description

Trust List module.

This file provides interface for Trust Lists processing.

Trust List contains the list of trusted public keys and signatures. Initial Trust List is obtained by device during provision. After that, it can be upgraded by Update library using FLDT service.

Trust List Usage

Trust List is maintained by Virgil IoT KIT modules and doesn't need to be processed by user. Nonetheless, there are some places where it needs user's attention :

• Gateway needs to initialize Trust List file type to retransmit it by Update library and to provide vs_fldt_server_add_filetype_cb for FLDT Server service :

vs_status_e
_add_filetype(const vs_update_file_type_t *file_type, vs_update_interface_t **update_ctx) {
    switch (file_type->type) {
 
    // ...
 
    // Trust List file type
        case VS_UPDATE_TRUST_LIST:
            *update_ctx = vs_tl_update_ctx();
            break;
    }
 
    return VS_CODE_OK;
}
 
// ...
 
    const vs_snap_service_t *snap_fldt_server;   // FLDT Server service
    vs_mac_addr_t mac_addr;                      // Own MAC address
 
    // Initialize mac_addr
 
    //  FLDT server service
    snap_fldt_server = vs_snap_fldt_server(&mac_addr, _add_filetype);
    STATUS_CHECK(vs_snap_register_service(snap_fldt_server), "Cannot register FLDT server service");
    STATUS_CHECK(vs_fldt_server_add_file_type(vs_tl_update_file_type(), vs_tl_update_ctx(), false),
                 "Unable to add Trust List file type");
    // Other file types

• After the Gateway receives the new Trust List using Cloud library, it is necessary to send the Trust List version to Things. Use vs_tl_load_part fir this purpose. This method reads Trust List header :

vs_tl_element_info_t elem = {.id = VS_TL_ELEMENT_TLH};      // Trust List header to be read
vs_tl_header_t tl_header;                                   // Header
uint16_t tl_header_sz = sizeof(tl_header);                  // Header size
vs_update_file_type_t tl_info;                              // Trust List file update information
 
// Load latest local Trust List
STATUS_CHECK(vs_tl_load_part(&elem, (uint8_t *)&tl_header, tl_header_sz, &tl_header_sz) &&
     tl_header_sz == sizeof(tl_header), "Unable to load Trust List header");
vs_tl_header_to_host(&tl_header, &tl_header);
 
// Prepare Update information
memset(tl_info, 0, sizeof(vs_update_file_type_t));
memcpy(&tl_info.info.version, &tl_header.version, sizeof(vs_file_version_t));
 
tl_info.type = VS_UPDATE_TRUST_LIST;
 
// Broadcast new Trust List information
STATUS_CHECK(vs_fldt_server_add_file_type(&tl_info, vs_tl_update_ctx(), true),
        "Unable to add new Trust List");

Function Documentation

vs_tl_deinit()

vs_status_e vs_tl_deinit

(

void

)

Trust List destruction.

Destroys Trust List.

Note

It is called by vs_provision_deinit.

Returns

VS_CODE_OK in case of success or error code.

vs_tl_header_to_host()

void vs_tl_header_to_host	(	const vs_tl_header_t *	src_data,
		vs_tl_header_t *	dst_data
	)

Convert Trust List header to host.

Convert Trust List header to the host format.

Parameters

[in]	src_data	Data source. Must not be NULL.
[out]	dst_data	Data destination. Must not be NULL.

vs_tl_header_to_net()

void vs_tl_header_to_net	(	const vs_tl_header_t *	src_data,
		vs_tl_header_t *	dst_data
	)

Convert Trust List header to network.

Convert Trust List header to the network format.

Parameters

[in]	src_data	Data source. Must not be NULL.
[out]	dst_data	Data destination. Must not be NULL.

vs_tl_init()

vs_status_e vs_tl_init	(	vs_storage_op_ctx_t *	op_ctx,
		vs_secmodule_impl_t *	secmodule,
		vs_file_ver_info_cb_t	ver_info_cb
	)

Trust List initialization.

Initializes Trust List.

Note

It is called by vs_provision_init.

Parameters

[in]	op_ctx	Storage context. Must not be NULL.
[in]	secmodule	Security Module implementation. Must not be NULL.

Returns

VS_CODE_OK in case of success or error code.

vs_tl_load_part()

vs_status_e vs_tl_load_part	(	vs_tl_element_info_t *	element_info,
		uint8_t *	out_data,
		uint16_t	buf_sz,
		uint16_t *	out_sz
	)

Trust List element loading.

Loads Trust List header, footer or data chunk. Element selection is performed by element_info selector.

Parameters

[in]	element_info	Element selection. Must not be NULL.
[out]	out_data	Output buffer to store data. Must not be NULL.
[in]	buf_sz	Buffer size. Must not be zero.
[out]	out_sz	Pointer to save stored data size. Must not be NULL.

Returns

VS_CODE_OK in case of success or error code.

vs_tl_save_part()

vs_status_e vs_tl_save_part	(	vs_tl_element_info_t *	element_info,
		const uint8_t *	in_data,
		uint16_t	data_sz
	)

Trust List element saving.

Saves Trust List header, footer or data chunk. Element selection is performed by element_info selector.

Parameters

[in]	element_info	Element selection. Must not be NULL.
[in]	in_data	Data to be saved. Must not be NULL.
[in]	data_sz	Data size. Must not be zero.

Returns

VS_CODE_OK in case of success or error code.

vs_tl_update_ctx()

vs_update_interface_t* vs_tl_update_ctx

(

void

)

Update interface for Trust List.

Returns Update context for Trust List.

Returns

vs_update_interface_t

vs_tl_update_file_type()

const vs_update_file_type_t* vs_tl_update_file_type

(

void

)

Trust List file type.

Returns Trust List file type for Update module.

Returns

vs_update_file_type_t