provision.h File Reference

Provision interface. More...

#include <virgil/iot/secmodule/secmodule.h>
#include <virgil/iot/provision/provision-structs.h>
#include <virgil/iot/status_code/status_code.h>
#include <virgil/iot/storage_hal/storage_hal.h>

Go to the source code of this file.

Functions
vs_status_e	vs_provision_init (vs_storage_op_ctx_t *tl_storage_ctx, vs_secmodule_impl_t *secmodule, vs_provision_events_t events_cb)
	Provision initialization. More...
vs_status_e	vs_provision_deinit (void)
	Provision destruction. More...
vs_status_e	vs_provision_get_slot_num (vs_provision_element_id_e id, uint16_t *slot)
	Get slot number. More...
vs_status_e	vs_provision_search_hl_pubkey (vs_key_type_e key_type, vs_secmodule_keypair_type_e ec_type, const uint8_t *key, uint16_t key_sz)
	Search high level public key. More...
vs_status_e	vs_provision_verify_hl_key (const uint8_t *key_to_check, uint16_t key_size)
	Verify high level public key. More...
const char *	vs_provision_cloud_url (void)
	Get Thing service URL. More...
vs_status_e	vs_provision_tl_find_first_key (vs_provision_tl_find_ctx_t *search_ctx, vs_key_type_e key_type, vs_pubkey_dated_t **pubkey_dated, uint8_t **pubkey, uint16_t *pubkey_sz, uint8_t **meta, uint16_t *meta_sz)
	Find first key. More...
vs_status_e	vs_provision_tl_find_next_key (vs_provision_tl_find_ctx_t *search_ctx, vs_pubkey_dated_t **pubkey_dated, uint8_t **pubkey, uint16_t *pubkey_sz, uint8_t **meta, uint16_t *meta_sz)
	Find Next key. More...

Detailed Description

Provision interface.

Provision interface allows user to :

• Enumerate Trust List keys (vs_provision_tl_find_first_key, vs_provision_tl_find_next_key).
• Search for specified high level key in internal storage (vs_provision_verify_hl_key).
• Verify high level public key (vs_provision_verify_hl_key).
• Get slot number for specific element (vs_provision_get_slot_num).
• Get Thing service URL (vs_provision_cloud_url)

Provision Usage

Provision library must be initialized before the first call and destroyed after the last one :

vs_status_e ret_code;                   // Result code
vs_storage_op_ctx_t tl_storage_impl;    // Trust List storage implementation
vs_secmodule_impl_t *secmodule_impl;    // Security Module implementation
vs_storage_op_ctx_t slots_storage_impl; // Slots storage implementation
 
// Initialize tl_storage_impl, secmod_impl, slots_storage_impl
 
// Security module can be initialized by software implementation
secmodule_impl = vs_soft_secmodule_impl(&slots_storage_impl);
 
STATUS_CHECK(vs_provision_init(&tl_storage_impl, secmod_impl), "Unable to initialize Provision Module");
 
// Operations
 
vs_provision_deinit();

Storage implementation for Trust List and Slots is described in Storage HAL Usage .

Trust List enumeration is done by vs_provision_tl_find_first_key first call and subsequent vs_provision_tl_find_next_key ones. Code below calculates IoT device keys amount :

vs_provision_tl_find_ctx_t search_ctx;      // Used by subsequent find first / next calls
uint8_t *public_key;                        // Public key pointer
uint16_t public_key_size;                   // Public key size
uint8_t *meta_info;                         // Meta information pointer
uint16_t meta_info_size;                    // Meta information size
size_t keys_amount = 0;                     // Keys amount
vs_pubkey_dated_t *pubkey_dated;            // Pointer to #vs_pubkey_dated_t structure
 
if( vs_provision_tl_find_first_key(&search_ctx, VS_KEY_IOT_DEVICE, &pubkey_dated, &public_key, &public_key_size,
&meta_info, &meta_info_size) == VS_CODE_OK ) {
    ++keys_amount;  // First key
 
    while( vs_provision_tl_find_next_key(&search_ctx, &pubkey_dated, &public_key, &public_key_size, &meta_info,
&meta_info_size) == VS_CODE_OK ) {
        ++keys_amount;  // Next key
    }
}

Function Documentation

vs_provision_cloud_url()

const char* vs_provision_cloud_url

(

void

)

Get Thing service URL.

This function returns Cloud URL for Thing service.

Returns

ASCIIZ URL or NULL in case of error

vs_provision_deinit()

vs_status_e vs_provision_deinit

(

void

)

Provision destruction.

This function must be called after all other Provision calls.

Returns

VS_CODE_OK in case of success or error code.

vs_provision_get_slot_num()

vs_status_e vs_provision_get_slot_num	(	vs_provision_element_id_e	id,
		uint16_t *	slot
	)

Get slot number.

This function returns slot number for specified provision element.

Parameters

[in]	id	Provision element.
[out]	slot	Slot number storage. Must not be NULL.

Returns

VS_CODE_OK in case of success or error code.

vs_provision_init()

vs_status_e vs_provision_init	(	vs_storage_op_ctx_t *	tl_storage_ctx,
		vs_secmodule_impl_t *	secmodule,
		vs_provision_events_t	events_cb
	)

Provision initialization.

This function must be called before any other Provision call.

Parameters

[in]	tl_storage_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_provision_search_hl_pubkey()

vs_status_e vs_provision_search_hl_pubkey	(	vs_key_type_e	key_type,
		vs_secmodule_keypair_type_e	ec_type,
		const uint8_t *	key,
		uint16_t	key_sz
	)

Search high level public key.

This function searches for the same key in its own slots and returns VS_CODE_OK if such key has been found.

Parameters

[in]	key_type	Key type.
[in]	ec_type	Elliptic curve type.
[in]	key	Key to be checked. Must not be NULL.
[in]	key_sz	Key size. Must not be zero.

Returns

VS_CODE_OK in case of success or error code.

vs_provision_tl_find_first_key()

vs_status_e vs_provision_tl_find_first_key	(	vs_provision_tl_find_ctx_t *	search_ctx,
		vs_key_type_e	key_type,
		vs_pubkey_dated_t **	pubkey_dated,
		uint8_t **	pubkey,
		uint16_t *	pubkey_sz,
		uint8_t **	meta,
		uint16_t *	meta_sz
	)

Find first key.

This function finds the first key_type key and returns it with meta information if present. You can find next key by vs_provision_tl_find_next_key call.

Parameters

[out]	search_ctx	Search context initialized by this function. Must not be NULL.
[in]	key_type	Key type to be found
[out]	pubkey	Public key pointer. Must not be NULL.
[out]	pubkey_sz	Public key size. Must not be NULL.
[out]	meta	Meta information pointer. Must not be NULL.
[out]	meta_sz	Meta information size. Must not be NULL.

Returns

VS_CODE_OK in case of success or error code.

vs_provision_tl_find_next_key()

vs_status_e vs_provision_tl_find_next_key	(	vs_provision_tl_find_ctx_t *	search_ctx,
		vs_pubkey_dated_t **	pubkey_dated,
		uint8_t **	pubkey,
		uint16_t *	pubkey_sz,
		uint8_t **	meta,
		uint16_t *	meta_sz
	)

Find Next key.

This function finds the next key_type key and returns it with meta information if present. First key must be found before by vs_provision_tl_find_first_key call.

Parameters

[out]	search_ctx	Search context initialized by this function. Must not be NULL.
[in]	key_type	Key type to be found
[out]	pubkey	Public key pointer. Must not be NULL.
[out]	pubkey_sz	Public key size. Must not be NULL.
[out]	meta	Meta information pointer. Must not be NULL.
[out]	meta_sz	Meta information size. Must not be NULL.

Returns

VS_CODE_OK in case of success or error code.

vs_provision_verify_hl_key()

vs_status_e vs_provision_verify_hl_key	(	const uint8_t *	key_to_check,
		uint16_t	key_size
	)

Verify high level public key.

This function verifies key to be signed.

Parameters

[in]	key_to_check	Key to check. Must not be NULL.
[in]	key_size	Key size. Must not be zero.

Returns

VS_CODE_OK in case of success or error code.