Mistake on this page? Email us

Setting up your own certificate authority

When your devices connect to Device Management, they use a Datagram Transport Layer Security (DTLS) device certificate to prove that they are linked to your Device Management account. The device certificate must be generated and signed by a certificate authority (CA).

To sign device certificates, you can use the built-in CA services provided by Factory Configurator Utility (FCU), or you can use a third-party CA, with or without FCU.

Note: Arm licenses FCU to Device Management customers that manufacture connected devices. Contact us for more information. Customers entitled to use the FCU tool can download the tool and documentation from Device Management Portal by selecting Device identity > Factory > Download.

To use a third-party CA, you must upload the CA certificate to your Device Management account. The certificate is then considered a trusted certificate in your account. If you do not upload a trusted certificate to your account, devices with a device certificate signed by your CA will not be able to connect to Device Management.

You can provide a self-signed certificate as a trusted certificate, and you can also provide additional intermediate certificates as trusted certificates, as part of a certificate chain. You can upload up to 10 certificates to your Device Management account.

Certificate chains are only available for commercial accounts.

Tip: We recommend uploading the CA certificate to Device Management when you set up your factory process, before your production devices come online. This enables you to test and verify the factory setup.

Device Management tracks the status of your certificates and notifies you about certificates that are about to expire. This enables you to ensure that your certificates are valid, and to renew your certificates when necessary. When a CA certificate expires, devices with a device certificate signed by that CA will not be able to connect to Device Management.

CA certificate requirements

Device Management supports X.509 v3 CA certificates in PEM format.

Your CA certificate must have the following properties:

Field Value
Cipher NIST P-256 (secp256r1)
Signature algorithm ecdsa-with-sha256
Valid from Must be currently valid.
Valid to It is recommended that the certificate be valid for 35 years.
Basic Constraints extension Subject Type=CA
Key Usage extension Set at least Digital Signature, Certificate Sign, and CRL Sign.

Note: If you use FCU with your own certificate authority, do not populate the X.509 properties in the certificate-authority section of the fcu.yml configuration file.

Example of how to create a certificate

In this example, we use OpenSSL to create a key pair and a certificate:

  1. Create a private key:

    openssl ecparam -out CA_private.pem -name prime256v1 -genkey
    
  2. Configure the CA certificate:

    (echo '[req]'; echo 'distinguished_name=dn'; echo 'prompt=no'; echo '[dn]'; echo 'CN=CA'; echo '[ext]'; echo 'basicConstraints=CA:TRUE') > ca.cnf
    
  3. Create a self-signed certificate:

    openssl req -key CA_private.pem -new -sha256 -x509 -days 12775 -out CA_cert.pem -config ca.cnf -extensions ext
    

Warning: We've provided OpenSSL commands for reference only. You must adapt the commands to your own production setup and security requirements.

Uploading a CA certificate or certificate chain

When you upload a CA certificate to Device Management, all devices with a device certificate that was signed by the CA can connect to Device Management.

If you use the CA certificate that you upload to Device Management to sign other certificates, all devices with a device certificate that was signed by those certificates can also connect to Device Management.

Using the API

Use the /v3/trusted-certificates POST API to upload certificates and certificate chains in Device Management.

The /v3/trusted-certificates API has the following parameters:

  • name: Mandatory.
  • description: Optional.
  • cert_data: A certificate chain consisting of concatenated PEM files. Mandatory.
  • service: Bootstrap or LwM2M. To bypass the bootstrapping, set the value to lwm2m. Mandatory.

Note: You must upload the full chain of your trusted CA certificate, including the root and all intermediate certificates, up to your trusted CA. Device Management also supports self-signed certificates, which are handled as a chain of size 1. The certificates must be in PEM format and concatenated. Your device certificate must not be part of your uploaded certificate chain.

Using Device Management Portal

To upload a certificate or certificate chain to your account through Device Management Portal:

  1. Log in to Device Management Portal as an administrator.
  2. From the side menu, select Device identity > Certificates.
  3. Click New certificate and select Upload your own certificate.
  4. Populate the Name and Description fields.
  5. Click Choose File and select your CA file.
  6. From the How will devices use this certificate? dropdown, select:
    • Credentials or Factory configurator utility - I can prove ownership of these credentials - Select this to upload a LwM2M or Bootstrap certificate if you use Factory Configurator Utility.
    • Enrollment - I received this certificate from the device manufacturer or a supplier - Select this if you purchased pre-provisioned devices and the device manufacturer or a supplier provided you with a CA certificate. This method of claiming device ownership is called first-to-claim.
    • Third party CA - I cannot prove ownership of these credentials - Select this to upload the third-party CA certificate that issues your LwM2M device certificates. For more information, see Integrating with a third-party CA.
  7. Click Upload certificate.

Deleting a CA certificate

When you delete a bootstrap certificate from Device Management, devices that have the deleted certificate in their chain of trust can no longer bootstrap using the deleted certificate; however, they might still be able to bootstrap using a different certificate in their chain of trust. They can also continue to connect to Device Management as long as their LwM2M credentials are still valid.

For more information about the use of bootstrap and LwM2M in Device Management, see device onboarding and connection options.

You can also blacklist or disable a certificate. Devices that have the disabled certificate in their chain of trust can no longer bootstrap and they cannot connect to Device Management using their LWM2M credentials.

Using the API

Use the /v3/trusted-certificates/{cert_id} DELETE API to delete certificates and certificate chains in Device Management.

Use GET /v3/trusted-certificates to retrieve the cert_id.

Using Device Management Portal

To delete a certificate from your account through Device Management Portal:

  1. Log in to Device Management Portal as an administrator.
  2. From the side menu, select Device identity > Certificates.
  3. From the list of certificates, select the certificate that you want to blacklist. This opens a pane on the right-hand side with the details of the selected certificate.
  4. Click the Delete button (Delete button). This opens the Delete bootstrap certificate window.
  5. Click Delete certificate.

Blacklisting a bootstrap certificate

Blacklisting a bootstrap certificate blocks all new devices that hold the certificate in their chain of trust from connecting to Device Management. Devices that have already onboarded to Pelion Device Management can continue operation normally.

You can also choose to suspend devices that are already onboarded. If you choose this option, blacklisting a certificate from the Device Management portal automatically suspends devices that have already registered using that certificate. However, automatic suspension of devices as part of certificate blacklisting is only a proof of concept and needs to be enabled separately for your account. Contact Arm support for more information.

Note: When you delete a bootstrap certificate from Device Management, devices that have the deleted certificate in their chain of trust can no longer bootstrap using the deleted certificate; however, they may still be able to bootstrap using a different certificate in their chain of trust. They can also continue to connect to Device Management as long as their LwM2M credentials are valid. When you blacklist a certificate, devices with a disabled certificate in their chain of trust can no longer bootstrap and cannot connect to Device Management using their LwM2M credentials. For more information about the use of bootstrap and LwM2M in Device Management, see device onboarding and connection options.

Using the API

Use /v3/trusted-certificates/{cert_id} PUT API to blacklist or enable a blacklisted certificate by changing the certificate's status.

For example:

curl -X PUT https://api.us-east-1.mbedcloud.com/v3/trusted-certificates/{cert_id} \
-H 'Authorization: Bearer <api_key>' \
-H 'content-type: application/json' \
-d  {"status": "INACTIVE"}

Using Device Management Portal

To blacklist (inactivate) a certificate:

  1. Sign in to Device Management Portal.
  2. From the side menu, select Device identity > Certificates.
  3. From the list of certificates, select the certificate that you want to blacklist. This opens a pane on the right-hand side with the details of the selected certificate.
  4. Click Blacklist. This opens the Blacklist a trusted certificate window.
  5. Click Blacklist certificate. You can see that the status of the certificate is now Inactive.

To enable (activate) a blacklisted certificate:

  1. Sign in to Device Management Portal.
  2. From the side menu, select Device identity > Certificates.
  3. From the list of certificates, select the certificate that you want to blacklist. This opens a pane on the right-hand side with the details of the selected certificate.
  4. Click Enable. This opens the Activate a trusted certificate window.
  5. Click Activate certificate. You can see that the status of the certificate is now Active.

Providing device DTLS keys (Bootstrap or LwM2M)

To use your own CA, you must generate device keys and sign certificates yourself.

To configure FCU to use your device keys and certificates:

  1. Use your CA to generate a device key and certificate, as explained in the Properties for manually generated keys and certificates section.
  2. In the fcu.yml configuration file, set the device-key-generation-mode parameter to externally_supplied.
  3. Place your DTLS keys and certificates in a folder of your choice. Make a note of that location; you will need to use this path as a parameter when provisioning devices, as explained in the Provisioning information section.