Menu

Expand
Rate this page:

Configuration Fetch Functions

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

Configuration data, such as certificates, API keys, authentication tokens, and encryption keys, is stored securely in the Twilio 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.

Data scope

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.

Data types

The Twilio 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 API documentation.

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).

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
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

Possible errors

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

Notifications

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

Description

Use this call to access configuration data that you have already uploaded to secure storage in the Twilio 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:

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 of MvConfigKeyToFetch structures, 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
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 Twilio cloud write-only store
MV_CONFIGKEYFETCHSTORE_STORE The requested key is in the Twilio 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
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

Possible errors

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

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
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.

Example

This example continues the function begun in mvSendConfigFetchRequest().

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
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

Possible errors

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

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
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.

Example

This example continues the function begun in mvSendConfigFetchRequest().

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;
}
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

thanks-feedback-gif