prvs-client.h File Reference

PRVS for client. More...

#include <virgil/iot/protocols/snap/snap-structs.h>
#include <virgil/iot/protocols/snap/prvs/prvs-structs.h>
#include <virgil/iot/provision/provision-structs.h>

Go to the source code of this file.

Data Structures
struct	vs_snap_prvs_client_impl_t
	PRVS client implementation. More...

Typedefs
typedef vs_status_e(*	vs_snap_prvs_stop_wait_t) (int *condition, int expect)
	Stop waiting implementation. More...
typedef vs_status_e(*	vs_snap_prvs_wait_t) (uint32_t wait_ms, int *condition, int idle)
	Wait implementation. More...

Functions
const vs_snap_service_t *	vs_snap_prvs_client (vs_snap_prvs_client_impl_t impl)
	PRVS Client SNAP Service implementation. More...
vs_status_e	vs_snap_prvs_enum_devices (const vs_netif_t *netif, vs_snap_prvs_dnid_list_t *list, uint32_t wait_ms)
	Enumerate devices, which don't have initialization provision yet. More...
vs_status_e	vs_snap_prvs_save_provision (const vs_netif_t *netif, const vs_mac_addr_t *mac, uint8_t *asav_res, uint16_t buf_sz, uint32_t wait_ms)
	Save provision. More...
vs_status_e	vs_snap_prvs_device_info (const vs_netif_t *netif, const vs_mac_addr_t *mac, vs_snap_prvs_devi_t *device_info, uint16_t buf_sz, uint32_t wait_ms)
	Request device information. More...
vs_status_e	vs_snap_prvs_sign_data (const vs_netif_t *netif, const vs_mac_addr_t *mac, const uint8_t *data, uint16_t data_sz, uint8_t *signature, uint16_t buf_sz, uint16_t *signature_sz, uint32_t wait_ms)
	Sign data. More...
vs_status_e	vs_snap_prvs_set (const vs_netif_t *netif, const vs_mac_addr_t *mac, vs_snap_prvs_element_e element, const uint8_t *data, uint16_t data_sz, uint32_t wait_ms)
	Set data. More...
vs_status_e	vs_snap_prvs_get (const vs_netif_t *netif, const vs_mac_addr_t *mac, vs_snap_prvs_element_e element, uint8_t *data, uint16_t buf_sz, uint16_t *data_sz, uint32_t wait_ms)
	Get data. More...
vs_status_e	vs_snap_prvs_set_tl_header (const vs_netif_t *netif, const vs_mac_addr_t *mac, const uint8_t *data, uint16_t data_sz, uint32_t wait_ms)
	Set Trust List header. More...
vs_status_e	vs_snap_prvs_set_tl_footer (const vs_netif_t *netif, const vs_mac_addr_t *mac, const uint8_t *data, uint16_t data_sz, uint32_t wait_ms)
	Set Trust List footer. More...

Detailed Description

PRVS for client.

PRVS is the provision service. PRVS Server is a device, PRVS Client is the factory server with factory initializer utility. Client prepares device's card, server signs it, and client saves this information.

PRVS Client usage

Before first call it is necessary to register PRVS service :

const vs_snap_service_t *snap_prvs_client;      // INFO service
vs_snap_prvs_dnid_list_t dnid_list;             // Array of "Do Not Initialized Devices"
uint32_t wait_ms = 3000;                        // Waiting 3 seconds for all devices enumerating
 
// Initialize snap_prvs_client
 
// Register PRVS Client service
snap_prvs_client = vs_snap_prvs_client(_snap_prvs_impl());
STATUS_CHECK(vs_snap_register_service(snap_prvs_client), "Cannot register PRVS client service");
 
// Enumerate uninitialized devices
STATUS_CHECK(vs_snap_prvs_enum_devices(NULL, &dnid_list, devices_max, &devices_amount, wait_ms),
    "Unable to enumerate devices without provision");

_snap_prvs_impl is the function that returns implementation for vs_snap_prvs_client_impl_t. It requires two function to be present - vs_snap_prvs_stop_wait_t and vs_snap_prvs_wait_t. You can find an example of their implementation in the c-implementation tool.

Note

Almost all calls have netif parameter. If it is null, SNAP interface that has been initialized will be used. It is OK for default case.

Typedef Documentation

vs_snap_prvs_stop_wait_t

typedef vs_status_e(* vs_snap_prvs_stop_wait_t) (int *condition, int expect)

Stop waiting implementation.

This function interrupts asynchronously waiting started by #wait_func and sets for condition the value \expect

stop_wait_func member or vs_snap_prvs_client_impl_t structure. wait_func member or vs_snap_prvs_client_impl_t structure.

Parameters

[in]	condition	Condition buffer. Must not be NULL.
[in]	expect	Expected value to be set.

Returns

VS_CODE_OK in case of success or error code.

vs_snap_prvs_wait_t

typedef vs_status_e(* vs_snap_prvs_wait_t) (uint32_t wait_ms, int *condition, int idle)

Wait implementation.

This function checks condition variable during wait_ms when it will be equal to the idle condition

Parameters

[in]	wait_ms	Wait in milliseconds.
[in]	condition	Condition buffer. Must not be NULL.
[in]	idle	Idle condition.

Returns

VS_CODE_OK in case of success or error code.

Function Documentation

vs_snap_prvs_client()

const vs_snap_service_t* vs_snap_prvs_client

(

vs_snap_prvs_client_impl_t

impl

)

PRVS Client SNAP Service implementation.

This call returns PRVS client implementation. It must be called before any PRVS call.

Parameters

[in]

impl

vs_snap_prvs_client_impl_t callback functions. Must not be NULL.

Returns

vs_snap_service_t SNAP service description. Use this pointer to call vs_snap_register_service.

vs_snap_prvs_device_info()

vs_status_e vs_snap_prvs_device_info	(	const vs_netif_t *	netif,
		const vs_mac_addr_t *	mac,
		vs_snap_prvs_devi_t *	device_info,
		uint16_t	buf_sz,
		uint32_t	wait_ms
	)

Request device information.

Sends request for device information.

Parameters

[in]	netif	SNAP service descriptor. If NULL, default one will be used.
[in]	mac	Device MAC address.
[out]	device_info	Device information output buffer. Must not be NULL.
[in]	buf_sz	Buffer size
[in]	wait_ms	Time to wait response.

Returns

vs_snap_service_t SNAP service description. Use this pointer to call vs_snap_register_service.

vs_snap_prvs_enum_devices()

vs_status_e vs_snap_prvs_enum_devices	(	const vs_netif_t *	netif,
		vs_snap_prvs_dnid_list_t *	list,
		uint32_t	wait_ms
	)

Enumerate devices, which don't have initialization provision yet.

Enumerate devices, which don't have initialization provision yet.

Parameters

[in]	netif	vs_netif_t SNAP service descriptor. Must not be NULL.
[out]	list	vs_snap_prvs_dnid_list_t Buffer with devices list. Must not be NULL.
[in]	wait_ms	Time to wait response.

Returns

vs_snap_service_t SNAP service description. Use this pointer to call vs_snap_register_service.

vs_snap_prvs_get()

vs_status_e vs_snap_prvs_get	(	const vs_netif_t *	netif,
		const vs_mac_addr_t *	mac,
		vs_snap_prvs_element_e	element,
		uint8_t *	data,
		uint16_t	buf_sz,
		uint16_t *	data_sz,
		uint32_t	wait_ms
	)

Get data.

Sends request for get element provision data from mac device

vs_snap_prvs_set and vs_snap_prvs_get calls are used for prepare device provision.

Parameters

[in]	netif	SNAP service descriptor. If NULL, default one will be used.
[in]	mac	Device MAC address.
[in]	element	Element identifier.
[out]	data	Output buffer for data. Must not be NULL.
[in]	buf_sz	signature buffer size. Must not be zero.
[out]	data_sz	Buffer to store data size. Must not be NULL.
[in]	wait_ms	Time to wait response.

Returns

vs_snap_service_t SNAP service description. Use this pointer to call vs_snap_register_service.

vs_snap_prvs_save_provision()

vs_status_e vs_snap_prvs_save_provision	(	const vs_netif_t *	netif,
		const vs_mac_addr_t *	mac,
		uint8_t *	asav_res,
		uint16_t	buf_sz,
		uint32_t	wait_ms
	)

Save provision.

Sends request to initialize security module and to generate device key pair. After it necessarily saves the own key pair and received Recovery keys to OTP memory.

Parameters

[in]	netif	SNAP service descriptor. Must not be NULL.
[in]	mac	Device MAC address.
[out]	asav_res	vs_pubkey_t buffer to be saved.
[in]	buf_sz	Buffer size
[in]	wait_ms	Time to wait response.

Returns

vs_snap_service_t SNAP service description. Use this pointer to call vs_snap_register_service.

vs_snap_prvs_set()

vs_status_e vs_snap_prvs_set	(	const vs_netif_t *	netif,
		const vs_mac_addr_t *	mac,
		vs_snap_prvs_element_e	element,
		const uint8_t *	data,
		uint16_t	data_sz,
		uint32_t	wait_ms
	)

Set data.

Sends request for set element provision data for mac device.

vs_snap_prvs_set and vs_snap_prvs_get calls are used for prepare device provision.

Parameters

[in]	netif	SNAP service descriptor. If NULL, default one will be used.
[in]	mac	Device MAC address.
[in]	element	Element identificator.
[in]	data	Data to be saved. Must not be NULL.
[in]	data_sz	data size. Must not be zero.
[in]	wait_ms	Time to wait response.

Returns

vs_snap_service_t SNAP service description. Use this pointer to call vs_snap_register_service.

vs_snap_prvs_set_tl_footer()

vs_status_e vs_snap_prvs_set_tl_footer	(	const vs_netif_t *	netif,
		const vs_mac_addr_t *	mac,
		const uint8_t *	data,
		uint16_t	data_sz,
		uint32_t	wait_ms
	)

Set Trust List footer.

Sends request for set data to the Trust List footer for mac device

Parameters

[in]	netif	SNAP service descriptor. If NULL, default one will be used.
[in]	mac	Device MAC address.
[in]	data	Data to be saved. Must not be NULL.
[in]	wait_ms	Time to wait response.

Returns

vs_snap_service_t SNAP service description. Use this pointer to call vs_snap_register_service.

vs_snap_prvs_set_tl_header()

vs_status_e vs_snap_prvs_set_tl_header	(	const vs_netif_t *	netif,
		const vs_mac_addr_t *	mac,
		const uint8_t *	data,
		uint16_t	data_sz,
		uint32_t	wait_ms
	)

Set Trust List header.

Sends request for set data to the Trust List header for mac device

Parameters

[in]	netif	SNAP service descriptor. If NULL, default one will be used.
[in]	mac	Device MAC address.
[in]	element	Element identificator.
[in]	data	Data to be saved. Must not be NULL.
[in]	data_sz	data size. Must not be zero.
[in]	wait_ms	Time to wait response.

Returns

vs_snap_service_t SNAP service description. Use this pointer to call vs_snap_register_service.

vs_snap_prvs_sign_data()

vs_status_e vs_snap_prvs_sign_data	(	const vs_netif_t *	netif,
		const vs_mac_addr_t *	mac,
		const uint8_t *	data,
		uint16_t	data_sz,
		uint8_t *	signature,
		uint16_t	buf_sz,
		uint16_t *	signature_sz,
		uint32_t	wait_ms
	)

Sign data.

Sends generated device information for the device. Device signs it and returns signature back.

Parameters

[in]	netif	SNAP service descriptor. If NULL, default one will be used.
[in]	mac	Device MAC address.
[in]	data	Data to be signed. Must not be NULL.
[in]	data_sz	data size. Must not be zero.
[out]	signature	Output buffer for signature. Must not be NULL.
[in]	buf_sz	signature buffer size. Must not be zero.
[out]	signature_sz	Buffer to store signature size. Must not be NULL.
[in]	wait_ms	Time to wait response.

Returns

vs_snap_service_t SNAP service description. Use this pointer to call vs_snap_register_service.