Configuration Fetch Functions
Danger
This is historical documentation, and tooling and console operations are no longer available.
Microvisor system calls include the following functions for transferring secrets, called “configuration data”, to the device:
Configuration Data
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 REST API.
Data Scope
Configuration data is scoped: either to all of the devices associated with a Microvisor 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.
Data Types
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.
REST APIs
For more information on the API’s account-level Config and Secret resources, and device-level Config and Secret subresources, please see the Microvisor REST API dcoumentation.
Asynchronous Operation
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.
Return Values and Errors
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).
Note
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.
mvSendConfigFetchRequest()
Request configuration data via a network channel
Declaration
extern enum MvStatus mvSendConfigFetchRequest(MvChannelHandle handle,
struct MvConfigKeyFetchParams *request);
Parameters
Parameter |
Description |
|---|---|
|
The handle of the channel that will issue the request. |
|
A pointer to request configuration data |
Possible Errors
Error Value |
Description |
|---|---|
|
|
|
One or more of the pointers within |
|
|
|
The request structure will not fit in the channel’s send buffer |
|
The specified channel has already been closed |
|
The request has already been sent, either successfully or not |
Notifications
This call, if successful, may subsequently yield any of the following notifications.
Notification Event Type |
Description |
|---|---|
|
Issued to the host channel’s notification center when data |
Description
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 REST 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:
struct MvConfigKeyFetchParams {
uint32_t num_items,
struct MvConfigKeyToFetch *keys_to_fetch
}
This structure’s properties are:
num_items— The number of items of configuration data you are requesting.keys_to_fetch— An array ofMvConfigKeyToFetchstructures, each of which identifies a single item of configuration data to retrieve.
The MvConfigKeyToFetch structure is defined as:
struct MvConfigKeyToFetch {
enum MvConfigKeyFetchScope scope,
enum MvConfigKeyFetchStore store,
struct MvSizedString *key
}
The integer placed in scope will be one of the following values:
Constant |
Description |
|---|---|
|
The requested key is scoped to all devices on the associated account |
|
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 |
|---|---|
|
The requested key is in the Microvisor cloud write-only 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.
Example
This section of a C function shows the usage of mvSendConfigFetchRequest(). Further sections will be shown in the System Calls below.
/**
* @brief Request the value of a secret.
*
* @param value_buffer - Whether the value will be written back to.
* @param key - The key name we're targeting.
*
* @returns `true` if the value was retrieved successfully,
* otherwise `false`
*/
bool config_get_secret(char *value, char key[]) {
// Set up the request parameters
struct MvConfigKeyToFetch key_one = {
.scope = MV_CONFIGKEYFETCHSCOPE_ACCOUNT, // An account-level value
.store = MV_CONFIGKEYFETCHSTORE_SECRET, // A secret value
.key = {
.data = (uint8_t*)key,
.length = strlen(key)
}
};
uint32_t item_count = 1;
struct MvConfigKeyToFetch keys[item_count];
keys[0] = key_one;
struct MvConfigKeyFetchParams request = {
.num_items = item_count,
.keys_to_fetch = keys
};
// Request the value of the key specified above
server_log("Requesting value for key '%s'", key);
enum MvStatus status = mvSendConfigFetchRequest(config_handles.channel, &request);
if (status != MV_STATUS_OKAY) {
// Failure -- report and close channel
server_error("Could not issue config fetch request");
config_close_channel();
return false;
}
// Wait for the data to arrive
received_config = false;
uint32_t last_tick = HAL_GetTick();
while(HAL_GetTick() - last_tick < CONFIG_WAIT_PERIOD_MS) {
if (received_config) break;
}
if (!received_config) {
server_error("Config fetch request timed out");
config_close_channel();
return false;
}
...
}
mvReadConfigFetchResponseData()
Access the response to a request for configuration data
Declaration
extern enum MvStatus mvReadConfigFetchResponseData(MvChannelHandle handle,
const struct MvConfigResponseData *response);
Parameters
Parameter |
Description |
|---|---|
|
The handle of the channel that will issue the request. |
|
A pointer to an |
Possible Errors
Error Value |
Description |
|---|---|
|
|
|
|
|
The specified channel has already been closed |
Description
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:
struct MvConfigResponseData {
enum MvConfigFetchResult result,
uint32_t num_items
}
The integer placed in result will be one of the following values:
Constant |
Description |
|---|---|
|
The fetch operation was successful |
|
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.
Example
This example continues the function begun in the mvSendConfigFetchRequest() example.
bool config_get_secret(char *value_buffer, char key[]) {
...
// Parse the received data record
server_log("Received value for key '%s'", key);
struct MvConfigResponseData response = {
.result = 0,
.num_items = 0
};
status = mvReadConfigFetchResponseData(config_handles.channel, &response);
if (status != MV_STATUS_OKAY || response.result != MV_CONFIGFETCHRESULT_OK || response.num_items != item_count) {
server_error("Could not get config item (status: %i; result: %i)", status, response.result);
config_close_channel();
return false;
}
...
}
mvReadConfigResponseItem()
Access requested configuration data
Declaration
extern enum MvStatus mvReadConfigResponseItem(MvChannelHandle handle,
const struct MvConfigResponseReadItemParams *item);
Parameters
Parameter |
Description |
|---|---|
|
The handle of the channel that will issue the request. |
|
A pointer to an |
Possible Errors
Error Value |
Description |
|---|---|
|
|
|
|
|
|
|
The specified channel has already been closed |
Description
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:
struct MvConfigResponseReadItemParams {
enum MvConfigKeyFetchResult *result,
uint32_t item_index,
struct MvSizedString *buf
}
The integer placed in the memory referenced by result will be one of the following values:
Constant |
Description |
|---|---|
|
The fetch operation was successful |
|
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.
Example
This example continues the function begun in the mvSendConfigFetchRequest() example.
bool config_get_secret(char *value_buffer, char key[]) {
...
uint8_t value[65] = {0};
uint32_t value_length = 0;
enum MvConfigKeyFetchResult result = 0;
struct MvConfigResponseReadItemParams item = {
.result = &result,
.item_index = 0,
.buf = {
.data = &value[0],
.size = 64,
.length = &value_length
}
};
// Get the value itself
status = mvReadConfigResponseItem(config_handles.channel, &item);
if (status != MV_STATUS_OKAY || result != MV_CONFIGKEYFETCHRESULT_OK) {
server_error("Could not get config item (status: %i; result: %i)", status, result);
config_close_channel();
return false;
}
// Copy the value data to the requested location
strncpy(value, (char*)value, value_length + 1);
config_close_channel();
return true;
}