Microvisor is in a pre-release phase and the information contained in this document is subject to change. Some features referenced below may not be fully available until Microvisor's General Availability (GA) release.
Microvisor system calls include the following functions for transferring secrets, called "configuration data", to the device:
The functions for managing configuration data requests and the responses they generate operate through Microvisor network channels, specifically channels of type MV_CHANNELTYPE_CONFIGFETCH
. To learn how to establish network connections, and open channels through them, please see Microvisor network functions.
Configuration data, such as certificates, API keys, authentication tokens, and encryption keys, is stored securely in the Microvisor cloud as key-value pairs on a per-account basis. You define each key's name when you upload its value. This is done using the Microvisor API.
Configuration data is scoped: either to all of the devices associated with a Twilio account, or to a single device under that account. Use the former scope for data common to all devices: for example, an API key for a cloud service which all of them post data to or request data from. The device-level scope might be used for information unique to an individual device's use-case.
The Microvisor cloud maintains two types of configuration data: 'secrets' and 'configs', stored as key-value pairs. Configs are items that are not confidential and so may be both created and subsequently read back using the Microvisor REST API. An example might be the base of a device's publicly readable application name and version string.
Secrets, however, are not viewable via API access once they have created. Their values will always remain hidden.
These levels of visibility only govern API access to the data — devices' application firmware can read both types of data. Nonetheless, when devices request a key's value, they must indicate the data type in their request configuration.
For more information on the API's account-level Config and Secret resources, and device-level Config and Secret subresources, please see the Microvisor API documentation.
Requests issued to Microvisor return immediately with a success or failure indication. However, success does not mean that the requested configuration data has been retrieved. The retrieval process is asynchronous and is signaled via the notification center you created and associated with your Config Fetch data channel. Microvisor posts a notification of type MV_EVENTTYPE_CHANNELDATAREADABLE
and triggers an interrupt when data is received from the channel. Your interrupt service routine should set a flag, which your main code can read and proceed to get the received data: in this case the Config Fetch response. This can be parsed to check that the data request was successful and, if so, your code can proceed to access the configuration data value it contains.
All of the functions described below return a 32-bit integer that is one of the values from the standard Microvisor enumeration MvStatus
. All possible error values for a given system call are provided with each function's description.
Success is always signaled by a return value of zero (MV_STATUS_OKAY
).
The configuration fetch functions for managing requests and the responses they generate operate through Microvisor network channels. To learn how to establish network connections, and open channels through them, please see Microvisor network functions.
Request configuration data via a network channel
1extern enum MvStatus mvSendConfigFetchRequest(MvChannelHandle handle,2struct MvConfigKeyFetchParams *request);
Parameter | Description |
---|---|
handle | The handle of the channel that will issue the request. This must be a channel of type MV_CHANNELTYPE_CONFIGFETCH |
request | A pointer to request configuration data |
Error Value | Description |
---|---|
MV_STATUS_PARAMETERFAULT | request does not reference memory accessible to the application |
MV_STATUS_LATEFAULT | One or more of the pointers within request are illegal |
MV_STATUS_INVALIDHANDLE | handle does not reference a valid channel of type MV_CHANNELTYPE_CONFIGFETCH |
MV_STATUS_INVALIDBUFFERSIZE | The request structure will not fit in the channel's send buffer |
MV_STATUS_CHANNELCLOSED | The specified channel has already been closed |
MV_STATUS_REQUESTALREADYSENT | The request has already been sent, either successfully or not |
This call, if successful, may subsequently yield any of the following notifications.
Notification Event Type | Description |
---|---|
MV_EVENTTYPE_CHANNELDATAREADABLE | Issued to the host channel's notification center when data has been received through the channel. Call mvReadConfigFetchResponseData() to the ultimate outcome of the request |
Use this call to access configuration data that you have already uploaded to secure storage in the Microvisor cloud. Secrets can be uploaded using the Microvisor API.
The application makes use of channels of type MV_CHANNELTYPE_CONFIGFETCH
to make requests for configuration data. The channel must be open for the request to be issued and of the correct type.
For each channel, only one request can be issued. If Microvisor returns MV_STATUS_PARAMETERFAULT
, MV_STATUS_INVALIDHANDLE
, MV_STATUS_INVALIDBUFFERSIZE
or MV_STATUS_CHANNELCLOSED
, then the request will not have been issued, and you can reconfigure the request and try again. Any other value indicates that the request has been sent, and any attempt to issue it again, or to use the channel for a fresh request, will result in MV_STATUS_REQUESTALREADYSENT
being returned. Instead, send any subsequent configuration data request through a new channel. You can re-use the channel definition structure and buffers if you wish. Be sure to close the channel used for a given request once you have received the response or a failure notification.
The call's request
parameter takes a pointer to an MvConfigKeyFetchParams
structure:
1struct MvConfigKeyFetchParams {2uint32_t num_items,3struct MvConfigKeyToFetch *keys_to_fetch4}
This structure's properties are:
num_items
— The number of items of configuration data you are requesting.
keys_to_fetch
— An array of
MvConfigKeyToFetch
structures, each of which identifies a single item of configuration data to retrieve.
The MvConfigKeyToFetch
structure is defined as:
1struct MvConfigKeyToFetch {2enum MvConfigKeyFetchScope scope,3enum MvConfigKeyFetchStore store,4struct MvSizedString *key5}
The integer placed in scope
will be one of the following values:
Constant | Description |
---|---|
MV_CONFIGKEYFETCHSCOPE_ACCOUNT | The requested key is scoped to all devices on the associated account |
MV_CONFIGKEYFETCHSCOPE_DEVICE | The requested key is scoped solely to the device making the request |
The integer placed in store
will be one of the following values:
Constant | Description |
---|---|
MV_CONFIGKEYFETCHSTORE_SECRET | The requested key is in the Microvisor cloud write-only store |
MV_CONFIGKEYFETCHSTORE_STORE | The requested key is in the Microvisor cloud read/write store |
The value of key
is a data structure that provides the name of the requested item. You set a key's name when you upload its value.
This section of a C function shows the usage of mvSendConfigFetchRequest()
. Further sections will be shown in the System Calls below.
1/**2* @brief Request the value of a secret.3*4* @param value_buffer - Whether the value will be written back to.5* @param key - The key name we're targeting.6*7* @returns `true` if the value was retrieved successfully,8* otherwise `false`9*/10bool config_get_secret(char *value, char key[]) {1112// Set up the request parameters13struct MvConfigKeyToFetch key_one = {14.scope = MV_CONFIGKEYFETCHSCOPE_ACCOUNT, // An account-level value15.store = MV_CONFIGKEYFETCHSTORE_SECRET, // A secret value16.key = {17.data = (uint8_t*)key,18.length = strlen(key)19}20};2122uint32_t item_count = 1;23struct MvConfigKeyToFetch keys[item_count];24keys[0] = key_one;2526struct MvConfigKeyFetchParams request = {27.num_items = item_count,28.keys_to_fetch = keys29};3031// Request the value of the key specified above32server_log("Requesting value for key '%s'", key);33enum MvStatus status = mvSendConfigFetchRequest(config_handles.channel, &request);34if (status != MV_STATUS_OKAY) {35// Failure -- report and close channel36server_error("Could not issue config fetch request");37config_close_channel();38return false;39}4041// Wait for the data to arrive42received_config = false;43uint32_t last_tick = HAL_GetTick();44while(HAL_GetTick() - last_tick < CONFIG_WAIT_PERIOD_MS) {45if (received_config) break;46}4748if (!received_config) {49server_error("Config fetch request timed out");50config_close_channel();51return false;52}5354...55}
Access the response to a request for configuration data
1extern enum MvStatus mvReadConfigFetchResponseData(MvChannelHandle handle,2const struct MvConfigResponseData *response);
Parameter | Description |
---|---|
handle | The handle of the channel that will issue the request. This must be a channel of type MV_CHANNELTYPE_CONFIGFETCH |
response | A pointer to an MvConfigResponseData structure |
Error Value | Description |
---|---|
MV_STATUS_PARAMETERFAULT | response does not reference memory accessible to the application |
MV_STATUS_INVALIDHANDLE | handle does not reference a valid channel of type MV_CHANNELTYPE_CONFIGFETCH |
MV_STATUS_CHANNELCLOSED | The specified channel has already been closed |
Your application should call mvReadConfigFetchResponseData()
when the channel receives a notification of type MV_EVENTTYPE_CHANNELDATAREADABLE
. Microvisor will write an MvConfigResponseData
record which your code can then parse:
1struct MvConfigResponseData {2enum MvConfigFetchResult result,3uint32_t num_items4}
The integer placed in result
will be one of the following values:
Constant | Description |
---|---|
MV_CONFIGFETCHRESULT_OK | The fetch operation was successful |
MV_CONFIGFETCHRESULT_RESPONSETOOLARGE | The resulting response was too large for the assigned buffer |
If the operation was successful, your code can call mvReadConfigResponseItem()
for each returned item. The number of items available is given by num_items
. The order of the returned items matches the order of items in the source request.
This example continues the function begun in mvSendConfigFetchRequest()
.
1bool config_get_secret(char *value_buffer, char key[]) {2...34// Parse the received data record5server_log("Received value for key '%s'", key);6struct MvConfigResponseData response = {7.result = 0,8.num_items = 09};1011status = mvReadConfigFetchResponseData(config_handles.channel, &response);12if (status != MV_STATUS_OKAY || response.result != MV_CONFIGFETCHRESULT_OK || response.num_items != item_count) {13server_error("Could not get config item (status: %i; result: %i)", status, response.result);14config_close_channel();15return false;16}1718...19}
Access requested configuration data
1extern enum MvStatus mvReadConfigResponseItem(MvChannelHandle handle,2const struct MvConfigResponseReadItemParams *item);
Parameter | Description |
---|---|
handle | The handle of the channel that will issue the request. This must be a channel of type MV_CHANNELTYPE_CONFIGFETCH |
item | A pointer to an MvConfigResponseReadItemParams structure |
Error Value | Description |
---|---|
MV_STATUS_PARAMETERFAULT | item does not reference memory accessible to the application |
MV_STATUS_ITEMINDEXINVALID | item references data at an invalid index |
MV_STATUS_INVALIDHANDLE | handle does not reference a valid channel of type MV_CHANNELTYPE_CONFIGFETCH |
MV_STATUS_CHANNELCLOSED | The specified channel has already been closed |
To retrieve the value of a specific key that you have successfully retrieved, call mvReadConfigResponseItem()
and pass in an MvConfigResponseReadItemParams
structure to indicate which item you require and where Microvisor should write it:
1struct MvConfigResponseReadItemParams {2enum MvConfigKeyFetchResult *result,3uint32_t item_index,4struct MvSizedString *buf5}
The integer placed in the memory referenced by result
will be one of the following values:
Constant | Description |
---|---|
MV_CONFIGFETCHRESULT_OK | The fetch operation was successful |
MV_CONFIGFETCHRESULT_RESPONSETOOLARGE | The data was too large for the assigned buffer |
The structure's other properties are:
item_index
— The index of the item you want. The order of the returned items matches the item request order.
buf
— A pointer to
a buffer structure
which Microvisor will use to write back the requested item.
This example continues the function begun in mvSendConfigFetchRequest()
.
1bool config_get_secret(char *value_buffer, char key[]) {2...34uint8_t value[65] = {0};5uint32_t value_length = 0;6enum MvConfigKeyFetchResult result = 0;78struct MvConfigResponseReadItemParams item = {9.result = &result,10.item_index = 0,11.buf = {12.data = &value[0],13.size = 64,14.length = &value_length15}16};1718// Get the value itself19status = mvReadConfigResponseItem(config_handles.channel, &item);20if (status != MV_STATUS_OKAY || result != MV_CONFIGKEYFETCHRESULT_OK) {21server_error("Could not get config item (status: %i; result: %i)", status, result);22config_close_channel();23return false;24}2526// Copy the value data to the requested location27strncpy(value, (char*)value, value_length + 1);28config_close_channel();29return true;30}