enable-device-cred-provisioning.adoc

Enable device-credential provisioning and install device certificates

Note	We recommend that you view this article in our documentation portal. Not all of our articles render correctly in GitHub.

Once you’re ready to provision devices in production, you need to build disk images that are configured to use device-credential provisioning.

After you have flashed those images to devices, you boot the image and install the device certicate for each device.

How you get the certificate on the device is up to you:

• You could have your HSM generate a private key and certificate directly on the device.

  You would then use your Fleet Root CA to sign the device’s certificate, for example using a PKCS#10 request.

  • We don’t have documentation on how to do this, since the method is different for each HSM model.

• You can also generate the device certificates and private keys on your development computer and copy them over to the device.

  • For these instructions, we’ll assume you are using this latter method.

HSM considerations

The following procedure includes configuration options 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.

Before you start these procedures, make sure that you’ve generated a device certificate first. You’ll need to copy that certificate to your device.

To enable device-credential provisioning and install device certificates, follow these steps:

1. Update your build configuration:

   • If you don’t want use an HSM, add the following lines to your conf/local.conf:

     SOTA_CLIENT_PROV = "aktualizr-device-prov"
     SOTA_DEPLOY_CREDENTIALS = "0"
     SOTA_PACKED_CREDENTIALS = "/path/to/your/credentials.zip"
     IMAGE_INSTALL_append = " dropbear "

   • If you do want to use an HSM, add the following lines to your conf/local.conf:

     SOTA_CLIENT_FEATURES = "hsm"
     SOTA_CLIENT_PROV = "aktualizr-device-prov-hsm"
     SOTA_DEPLOY_CREDENTIALS = "0"
     IMAGE_INSTALL_append = " softhsm-testtoken dropbear "

     Note

     The line IMAGE_INSTALL_append installs optional software to your device. The option dropbear installs the Dropbear ssh server. You’ll need to ssh into the device to copy the certificates to the device’s filesystem. The option softhsm-testtoken installs SoftHSM to so that you can easily test HSM interactions. When using a real HSM, you can omit this option.

2. Build a standard image using bitbake.

3. Boot the image.

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

   Note	You might remember that credentials.zip normally contains a provisioning key for shared-credential provisioning. In this case, we just need the autoprov.url file inside credentials.zip. This file contains the URL of your device gateway, which is specific to your account.

5. Copy the device credentials and device gateway root CA certificate to the device.

   export device_dir=path/to/device-creds/dir
   scp -P 2222 -pr ${device_dir} root@localhost:/var/sota/import

   Note	Replace path/to/device-creds/dir with the local directory where you generated the device certificate.

6. (Optional) When the copy operation has completed, ssh into your device and check the aktualizr log output with the following systemd command:

   journalctl -f -u aktualizr

   Once the certificates have copied, the following chain of events should occur:

   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.