Keychain#

Wi-SUN Keychain API is an interface for retrieving device credentials and trusted CA certificates from a set of keychains.

Supported keychain types:

• built-in Built-in keychain is created during compilation time and cannot be changed. The application may add its own credentials via template contributions using Silicon Labs Configurator. Device private keys are stored unencrypted.

• NVM NVM keychain is dynamically provisioned either during device production or while on the field. Device private keys are stored in PSA ITS, device certificates and trusted CA certificates are stored in NVM3. Depending on the device capabilities, PSA ITS may be encrypted.

#include "sl_memory_manager.h"
#include "sl_wisun_api.h"
#include "sl_wisun_keychain.h"

uint8_t trustedca_count;
sl_wisun_keychain_entry_t *trustedca;
sl_wisun_keychain_credential_t *credential;
uint16_t certificate_options;

// Retrieve a device credential
credential = sl_wisun_keychain_get_credential(SL_WISUN_KEYCHAIN_AUTOMATIC, 0);

// Configure the device certificate
sl_wisun_set_device_certificate(SL_WISUN_CERTIFICATE_OPTION_NONE,
                                credential->certificate.data_length,
                                credential->certificate.data);

// Configure the device private key
if (credential->pk.type == SL_WISUN_KEYCHAIN_KEY_TYPE_PLAINTEXT) {
  sl_wisun_set_device_private_key(SL_WISUN_PRIVATE_KEY_OPTION_NONE,
                                  credential->pk.u.plaintext.data_length,
                                  credential->pk.u.plaintext.data);
} else {
  sl_wisun_set_device_private_key_id(credential->pk.u.key_id);
}

// Free the device credential, ownership was transferred
sl_free(credential);

// Enumerate the trusted CA certificates
trustedca_count = sl_wisun_keychain_get_trustedca_count();

// Loop through available trusted CA certificates
certificate_options = SL_WISUN_CERTIFICATE_OPTION_NONE;
for (uint8_t idx = 0; idx < trustedca_count; ++idx) {
  // Retrieve a trusted CA certificate
  trustedca = sl_wisun_keychain_get_trustedca(idx);

  // Configure the trusted CA certificate
  sl_wisun_set_trusted_certificate(certificate_options,
                                   trustedca->data_length,
                                   trustedca->data);

  // Free the trusted CA certificate, ownership was transferred
  sl_free(trustedca);

  // The trusted CA certificates after the first one must be
  // configured with SL_WISUN_CERTIFICATE_OPTION_APPEND.
  certificate_options |= SL_WISUN_CERTIFICATE_OPTION_APPEND;
}

It's possible to utilize Silicon Labs Configurator to add credentials/trusted CAs to the built-in keychain during compile time through template contributions.

• wisun_keychain_include::path is the name of the header file that contains the uint8_t array declarations or definitions.

• wisun_keychain_trustedca::certificate is the name of the uint8_t array for a trusted CA certificate. This variable can be defined multiple times.

• wisun_keychain_credential::certificate is the name of the uint8_t array for the device certificate.

• wisun_keychain_credential::key is the name of the uint8_t array for the device private key.

template_contribution:
  - name: wisun_keychain_include
    value:
      path: certificate_example.h
  - name: wisun_keychain_trustedca
    value:
      certificate: EXAMPLE_ROOT_CERT
  - name: wisun_keychain_trustedca
    value:
      certificate: EXAMPLE_MCA_CERT
  - name: wisun_keychain_trustedca
    value:
      certificate: EXAMPLE_MICA_CERT
  - name: wisun_keychain_credential
    value:
      certificate: EXAMPLE_DEVICE_CERT
      key: EXAMPLE_DEVICE_KEY

In certificate_example.h

const uint8_t EXAMPLE_ROOT_CERT[] = {
  ...
};
const uint8_t EXAMPLE_MCA_CERT[] = {
  ...
};
const uint8_t EXAMPLE_MICA_CERT[] = {
  ...
};
const uint8_t EXAMPLE_DEVICE_CERT[] = {
  ...
};
const uint8_t EXAMPLE_DEVICE_KEY[] = {
  ...
};

Modules#

sl_wisun_keychain_credential_t

sl_wisun_keychain_entry_t

sl_wisun_keychain_key_t