Microvisor Public Beta
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
_10extern enum MvStatus mvSendConfigFetchRequest(MvChannelHandle handle,_10 struct 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:
_10struct MvConfigKeyFetchParams {_10 uint32_t num_items,_10 struct MvConfigKeyToFetch *keys_to_fetch_10}
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:
_10struct MvConfigKeyToFetch {_10 enum MvConfigKeyFetchScope scope,_10 enum MvConfigKeyFetchStore store,_10 struct MvSizedString *key_10}
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.
_55/**_55 * @brief Request the value of a secret._55 *_55 * @param value_buffer - Whether the value will be written back to._55 * @param key - The key name we're targeting._55 *_55 * @returns `true` if the value was retrieved successfully,_55 * otherwise `false`_55 */_55bool config_get_secret(char *value, char key[]) {_55_55 // Set up the request parameters_55 struct MvConfigKeyToFetch key_one = {_55 .scope = MV_CONFIGKEYFETCHSCOPE_ACCOUNT, // An account-level value_55 .store = MV_CONFIGKEYFETCHSTORE_SECRET, // A secret value_55 .key = {_55 .data = (uint8_t*)key,_55 .length = strlen(key)_55 }_55 };_55_55 uint32_t item_count = 1;_55 struct MvConfigKeyToFetch keys[item_count];_55 keys[0] = key_one;_55_55 struct MvConfigKeyFetchParams request = {_55 .num_items = item_count,_55 .keys_to_fetch = keys_55 };_55_55 // Request the value of the key specified above_55 server_log("Requesting value for key '%s'", key);_55 enum MvStatus status = mvSendConfigFetchRequest(config_handles.channel, &request);_55 if (status != MV_STATUS_OKAY) {_55 // Failure -- report and close channel_55 server_error("Could not issue config fetch request");_55 config_close_channel();_55 return false;_55 }_55_55 // Wait for the data to arrive_55 received_config = false;_55 uint32_t last_tick = HAL_GetTick();_55 while(HAL_GetTick() - last_tick < CONFIG_WAIT_PERIOD_MS) {_55 if (received_config) break;_55 }_55_55 if (!received_config) {_55 server_error("Config fetch request timed out");_55 config_close_channel();_55 return false;_55 }_55_55 ..._55}
Access the response to a request for configuration data
_10extern enum MvStatus mvReadConfigFetchResponseData(MvChannelHandle handle,_10 const 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:
_10struct MvConfigResponseData {_10 enum MvConfigFetchResult result,_10 uint32_t num_items_10}
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().
_19bool config_get_secret(char *value_buffer, char key[]) {_19 ..._19_19 // Parse the received data record_19 server_log("Received value for key '%s'", key);_19 struct MvConfigResponseData response = {_19 .result = 0,_19 .num_items = 0_19 };_19_19 status = mvReadConfigFetchResponseData(config_handles.channel, &response);_19 if (status != MV_STATUS_OKAY || response.result != MV_CONFIGFETCHRESULT_OK || response.num_items != item_count) {_19 server_error("Could not get config item (status: %i; result: %i)", status, response.result);_19 config_close_channel();_19 return false;_19 }_19_19 ..._19}
Access requested configuration data
_10extern enum MvStatus mvReadConfigResponseItem(MvChannelHandle handle,_10 const 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:
_10struct MvConfigResponseReadItemParams {_10 enum MvConfigKeyFetchResult *result,_10 uint32_t item_index,_10 struct MvSizedString *buf_10}
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().
_30bool config_get_secret(char *value_buffer, char key[]) {_30 ..._30_30 uint8_t value[65] = {0};_30 uint32_t value_length = 0;_30 enum MvConfigKeyFetchResult result = 0;_30_30 struct MvConfigResponseReadItemParams item = {_30 .result = &result,_30 .item_index = 0,_30 .buf = {_30 .data = &value[0],_30 .size = 64,_30 .length = &value_length_30 }_30 };_30_30 // Get the value itself_30 status = mvReadConfigResponseItem(config_handles.channel, &item);_30 if (status != MV_STATUS_OKAY || result != MV_CONFIGKEYFETCHRESULT_OK) {_30 server_error("Could not get config item (status: %i; result: %i)", status, result);_30 config_close_channel();_30 return false;_30 }_30_30 // Copy the value data to the requested location_30 strncpy(value, (char*)value, value_length + 1);_30 config_close_channel();_30 return true;_30}