Mistake on this page? Email us

Provisioning for Pelion Device Management

Note: This document assumes you already have a device running MBL and a Pelion Device Management account.

To connect your devices to Pelion Device Management, you must provision the device with security credentials that establish trust with the cloud services. Device Management offers a developer certificate to connect a development device to a Device Management account. The developer certificate doesn't require setting up a certificate authority (unlike the full credentials for production devices). Instead, you can simply download the certificate from the Device Management Portal. You then need to get the certificate on the device in a process called provisioning.

To use Pelion Device Management for firmware updates of either your file system or your applications, you must also provision your device with an update authenticity certificate. This certificate is used to sign and verify firmware update manifests, and is created using the manifest tool.

Starting with Mbed Linux OS 0.6, your devices can be provisioned with developer and update authenticity certificates using MBL CLI 2.0.

Tip: See the Device Management documentation for background on the developer certificate and its scope.

Process review

Tip: If you want to specify a storage location on the device for your API key and certificates, rather than use the default storage location, do so before you begin the provisioning process.

The full provisioning process is:

  1. Generate a Device Management API key from the Device Management Portal.

  2. Use MBL CLI to save the API key to the host machine.

  3. Use the manifest tool to generate the firmware update authenticity certificate (update_default_resources.c), which contains the:

    • Update certificate fingerprint.
    • Update certificate.
    • Vendor and class IDs.
  4. Use MBL CLI to:

    1. Create a developer certificate. The developer certificate (mbed_cloud_credentials.c) contains:

      • The bootstrap server CA certificate.
      • The bootstrap server private key.
      • The bootstrap server information.
    2. Program the developer certificate and authenticity certificate to the device.

As a preliminary step, create an API key on the Device Management Portal and used MBL CLI to save it to the device.

As a preliminary step, create an update authenticity certificate with the manifest tool. Then use MBL CLI to create a developer certificate and program both the update authenticity and developer certificates on the device.

Provisioning instructions

Prerequisites

A Pelion Device Management Account.

Preliminary steps

Mandatory: API key and update authenticity certificate

  1. Create an API key for Pelion Device Management. Be sure to copy the key when prompted - you will need to store it on the device before you begin provisioning.

  2. Create an update_default_resources.c file with your update authenticity certificate, created with the manifest tool:

    Note: This process is for development only. A production process will be documented when available based on the factory provisioning process.

    1. Create an update resources directory, such as ./update-resources:

      mkdir ./update-resources
      
    2. Move into the new directory:

      cd ./update-resources
      
    3. Use the manifest tool to generate an update_default_resources.c file. The tool will prompt you to enter some details for a new developer authenticity certificate that it will use in this generation process:

      manifest-tool init -d <domain> -m <device class>

      Where:

      • <domain> is your company's domain, like arm.com.
      • <device class> is a unique identifier for the device class. If you're in development (using developer credentials), you can use dev-device.

      Warning: The authenticity certificate generated will be a developer certificate. The Manifest Tool will let you enter a manual expiration value, and will default to 90 if you don't enter one. When the certificate expires, the device will not be updatable. You will need to put a new authenticity certificate on the device, either by reflashing the device or provisioning the device again.

      For example:

      $ manifest-tool init -d arm.com -m dev-device
      A certificate has not been provided to init, and no certificate is provided in .update-certificates/default.der
      Init will now guide you through the creation of a certificate.
      
      This process will create a self-signed certificate, which is not suitable for production use.
      
      In the terminology used by certificates, the "subject" means the holder of the private key that matches a certificate.
      In which country is the subject located? UK
      In which state or province is the subject located? Cambridgeshire
      In which city or region is the subject located? Cambridge
      What is the name of the subject organization? Arm
      What is the common name of the subject organization? [arm.com]
      How long (in days) should the certificate be valid? [90]
      [WARNING]: Certificates generated with this tool are self-signed and for testing only
      [WARNING]: This certificate is valid for 90 days. For production,use certificates with at least 10 years validity.
      [INFO] 2019-09-30 10:56:04 - manifesttool.init - Certificate written to .update-certificates/default.der
      [INFO] 2019-09-30 10:56:04 - manifesttool.init - Private key written to .update-certificates/default.key.pem
      [INFO] 2019-09-30 10:56:04 - manifesttool.init - Default settings written to .manifest_tool.json
      [INFO] 2019-09-30 10:56:04 - manifesttool.init - Wrote default resource values to update_default_resources.c
      

Optional: persistent storage locations

Note: MBL CLI sets up defaults automatically; this manual step is optional, but if you chose to perform it, it should be done before any other provisioning steps.

MBL CLI can fetch and store API keys, firmware update authority certificates and developer certificates from a persistent storage location you can configure. This simplifies the provisioning workflow and makes API authentication easier; MBL CLI will automatically find the API key when it needs to authenticate with the Pelion Device Management service APIs.

You can save your credentials to either a user store or a team store:

  • User Store: Where API keys for each user are stored.

    Default location: ~/.mbl-store/user/ (permissions for this folder are set to drwx------). The folder is owned by the *nix user who created the store (the store is automatically created on first use).

    MBL CLI can save a single API key in the User Store, which it uses when it needs authentication with the Device Management APIs. If you save another API key, it will overwrite the previously stored key.

  • Team Store: Where developer certificates and firmware update authority certificates for your devices are stored; any team member who has access to this folder can provision devices with these credentials (using MBL CLI). If you want to give your team access to this folder, you can set this folder to be shared over a cloud service, or make it discoverable on your network.

    Default location: ~/.mbl-store/team/ (permissions for this folder are set to drwxrw----). You should set this store's user:group according to the access permissions you have defined for your team.

To specify a storage location, create a config file ~/.mbl-stores.json with the following contents:

{
    "user": path/to/user/store,
    "team": path/to/team/store
}

If, on first use, you do not create your own ~/.mbl-stores.json, it will be automatically created and populated with the default values.

Provisioning

To provision your device:

  1. Connect the device to your development PC. Follow the instructions to connect your device.

  2. Run the select command. It returns a list of discovered devices; you can select your device by its list index:

    $ mbl-cli select
    Discovering devices. This will take up to 30 seconds.
    
    1: mbed-linux-os-9999: fe80::21b:63ff:feab:e6a6%enpos623
    
    $ 1
    
    
  3. Store your API key on the device (replacing <api-key> with the real API key you saved from the portal).

    mbl-cli save-api-key <api-key>
    

    The command validates the key exists in Device Management, then saves the key in the User Store.

  4. To provision your device with the developer and update certificates:

    mbl-cli provision-pelion  <cert-name> <update-cert-name> -c -p <update-cert-path>
    

    The arguments are:

    Argument Info
    <cert-name> A name for your developer certificate.
    <update-cert-name> A name for your update authenticity certificate, created earlier using the manifest tool.
    -c Tells MBL CLI to create a new developer certificate and save it in your Team Store.
    -p Tells MBL CLI to parse an existing update_default_resources.c file and save it in the Team Store. For example, if your update_default_resources.c is located in path/to/resources/update_default_resources.c the form of the invocation would be: -p path/to/resources/update_default_resources.c

    MBL CLI injects the certificates into your selected device's secure storage. MBL CLI also saves the certificates, under the given names, in your Team Store for use with other devices.

Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.