If you followed the "Getting Started" procedures, you used a provisioning key that was shared by all devices that run the same software image. This key enables you to provision the permanent credentials for your test devices. This method is fine if you’re just testing and want to get started quickly. When you move to production, a more secure option is to provision with credentials that are specific to each device.

When you provision with device credentials, you install permanent credentials each device before the device connects to the server. Unlike shared-credential provisioning, the server doesn’t issue any credentials to devices. Instead, you use a root CA certificate to sign the credentials that you install on the device. You then install the same root CA certificate on the OTA Connect server.

Every time the device attempts to connect, the server verifies that the device credentials are signed by the same CA that you originally installed on the server. The device also verifies that is communicating with a genuine HERE OTA Connect server.

The following procedures describe different options for provisioning with device credentials.

Simulate the provisioning process with device credentials

To provision with device credentials in production, you need to have a root CA. If you want to test this provisioning method without generating a root CA, you can simulate it with the aktualizr-cert-provider command.

To use the aktualizr-cert-provider command, you must still generate a provisioning key that your devices can share. But with this method, you use the provisioning key to sign the device certificate. In production, you would use the root CA to sign the device certificate, but this method is useful for testing.

To simulate provisioning with a device certificate, follow these steps:
  1. Add the following lines to your local.conf:

    SOTA_CLIENT_PROV = "aktualizr-device-prov"
  2. Build a standard image using the bitbake command.

  3. Boot the image.

    The device should not be able to provision at this time. To verify this, log in to the HERE OTA Connect server and make sure that the device does not appear in the list of devices.

  4. Load the device credentials on to the device with aktualizr-cert-provider command:

    aktualizr-cert-provider -c credentials.zip -t <device> -d /var/sota/import -r -u

    You can find the aktualizr-cert-provider source in the aktualizr repo. You can also find a compiled binary in the host work directory of bitbake. The path is something like tmp/work/x86_64-linux/aktualizr-native/1.0+gitAUTOINC+<version>/build/src/cert_provider/aktualizr-cert-provider.

Use a Hardware Security Module (HSM) When provisioning with device credentials

As described in the introduction, it’s a good idea to use a Hardware Security Model (HSM) to hold potentially sensitive device credentials.

The following procedure describes how to use QEMU and SoftHSM to simulate a device with an HSM. However, the procedure for your HSM will probably be different. We’ve provided these instructions as a basic guide to how this provisioning method works but you’ll need to make further changes on your own. For example, you’ll probably need to adapt your BSP so that aktualizr can access the keys from your HSM.

To use an HSM when provisioning with device credentials, follow these steps:
  1. Generate and install a root certificate.

  2. Add the following lines to your conf/local.conf:

    SOTA_CLIENT_PROV = "aktualizr-device-prov-hsm"
    IMAGE_INSTALL_append = " softhsm-testtoken "
  3. Build a standard image using bitbake. Make sure that an ssh server is installed. Usually you can do this with IMAGE_INSTALL_append = " dropbear ".

  4. Boot the image.

  5. Run the following commands to tell the device what server URL to connect to:

    unzip credentials.zip autoprov.url
    scp -P 2222 autoprov.url root@localhost:/var/sota/import/gateway.url
  6. Copy the device credentials and device gateway root CA certificate to the device’s HSM. For the QEMU simulated HSM, enter the device directory whose credentials you want to copy, then enter the following command:

    scp -P 2222 -pr ./ root@localhost:/var/sota/import
    1. The server authenticates the client device by verifying that the client’s certificate was signed by the root CA private key that was uploaded in step 2.

    2. The client device authenticates the server by verifying that the server’s certificate was signed by the server’s internal root CA private key.

    3. The device is provisioned and appears online in the web UI.

More information is available on provisioning with shared credentials, device credentials (with or without an HSM), and how the various files included in credentials.zip are related.