Configuration Fetch Functions

Microvisor system calls include the following functions for transferring secrets, called “configuration data”, to the device:

• mvSendConfigFetchRequest()
• mvReadConfigFetchResponseData()
• mvReadConfigResponseItem()

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

mvSendConfigFetchRequest()

Request configuration data via a network channel

Declaration

extern enum MvStatus mvSendConfigFetchRequest(MvChannelHandle handle,
                                              struct MvConfigKeyFetchParams *request);

Parameters

Possible errors

Notifications

This call, if successful, may subsequently yield any of the following notifications.

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:

The integer placed in store will be one of the following values:

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

Possible errors

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:

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

Possible errors

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:

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