Documentation

Mistake on this page? Email us
Docs › Provisioning devices › Certificates and certificate authorities › Integrating with a third-party CA

Integrating with a third-party CA

Note: This feature is disabled by default. You can integrate third-party CAs only if you have specifically requested it for your account. If you need to do this and find that the feature is disabled, contact Cloud support.

If your device works in bootstrap mode, it obtains a device LwM2M key as part of the bootstrap flow. The LwM2M key needs to be signed by a certificate that is trusted by your account. There are two ways to sign the device LwM2M key:

  • The key is signed by Device Management private key. This is the default behavior, and relies on Device Management being a CA.
  • The key is signed by a third-party CA.

You can also use third-party CA for renewing your device custom certificates using Device Management. See Certificate renewal.

Supported CAs

This feature currently supports signing certificates using:

Note: You may need to establish a business relationship with the third-party supplier.

Setting up a CA

You can set up and manage a CA using either the APIs or Device Management Portal.

  • You need to upload the third-party CA's signed certificate to your Device Management account as a trusted certificate.
  • You may need to upload the third-party CA's signed certificate to your own online services (like DLMS or WiSUN) if it is used for signing certificates that enable your device to connect to these services.
  • You can create (or register) CAs without making them active. If you make a CA active, any bootstrapping device will request for a certificate from it. You cannot use both your own CA and the Device Management CA at the same time.
  • In some cases, your device will be provisioned with a certificate chain to reflect your CA hierarchy.

Validating a CA

It is recommended to validate your CA configuration before activating it. The validation ensures that Device Management can access your third-party CA and use it to sign certificates.

Note: The API requests the third-party CA to sign a test certificate. For some third-party CAs, this operation may make use of the CA account quota.

Configuration using Device Management Portal

  1. Launch the Device Management Portal.
  2. Navigate to Device Identity.
  3. Select the Certificates view.
  4. Select Manage CAs from the available page actions at the top right corner. This takes you to the Certificate Authorities view.

Note: You cannot select Manage CAs in the Portal if the feature is not enabled for your account.

Managing CAs

  1. To create the CA click Add CA.
  2. To trust the CA for LwM2M usage, upload the CA certificate as a trusted certificate.
  3. Activate your CA for the Service Configurations it is intended for.
  4. To validate your CA configuration, click the Verify button on the CA entry in the list of CAs.

Managing service configurations

  1. In the Service configuration column, find the row corresponding to the Certificate Authority to be used.
  2. Click on an existing service configuration (or click on the action icon) in that row to launch the Select service configuration popup.
  3. Enter the name of a new Service Configuration.
  4. Click the + button to create the Service Configuration.
  5. Click Create to confirm and close the popup window.
  6. Alternatively, select an existing Service Configuration. An existing configuration will be moved onto the selected Certificate Authority.

Note: It is recommended to validate your CA configuration before activation.

Configuration using Device Management APIs

When using the Third party CA management API you need to handle two different entities:

  • Certificate issuers are used to manage the CAs.
  • Certificate issuer configurations are used to manage the service configurations.

Service configurations define the active CA you can use to sign the certificates used for a specific service. The service named LWM2M is used for securing your device connection to Device Management. You can define your own services for renewing your device custom certificates using Device Management. See Certificate Renewal.

Managing CAs with the API

For detailed information, refer to the API documentation.

Managing service configurations with the API

For detailed information, refer to the Certificate Issuers Activation section in the Third party CA management API document.

The exact parameters you need to enter depend on your CA. Follow the portal form or the API documentation associated with your CA.

Setting up your devices

This feature doesn't require any changes in the factory flow. The only requirement is that the devices are in bootstrap mode.

Signing certificates using Global Sign

For integrating with Global Sign you need to:

  • Have an account in Global Sign.
  • Provide Pelion Device Management with the relevant information for accessing the account.

Global Sign account credentials

To create an account in Global Sign, you need to generate an RSA key pair (optionally encrypted with a passphrase), and provide the generated public key to Global Sign. Global Sign then signs the given public key and provides a certificate for accessing the account (the CA certificate). Additionally, Global Sign provides an API key and API secret.

Account validation policies

Global Sign allows you to set the validation rules on the certificate fields that are applied when signing the certificate.

You need to set the following:

  • Public key type: ECDSA.
  • Public key length: 256.

The following subject fields are used and they should not have any account-specific format restrictions:

  • Common name
  • Country
  • State
  • Organization
  • Organization unit
  • Locality
  • Email

Other certificate fields are not used and should not be configured as "required".

Setting Global Sign as an external CA

You can set Global Sign as a CA using either the APIs or Device Management Portal.

In the Device Management Portal:

  • Navigate to Device identity > Certificates.

  • First click Manage CAs and then Add CA.

  • Select Global Sign as the issuer type and enter the following information:

    • API key: The API key received from Global Sign.
    • API secret: The API secret received from Global Sign.
    • Client certificate: The CA certificate received from Global Sign.
    • Private key: The private key that was generated.
    • Passphrase: The passphrase that was used for the private key encryption, if it was encrypted.

  • If you are using External CA Management API:

    • Refer to the API documentation, especially POST /v3/certificate-issuers.
    • Supply the following information:
      • api_key: The API key received from Global Sign.
      • api_secret: The API secret received from Global Sign.
      • client_certificate: The CA certificate received from Global Sign.
      • private_key: The private key that was generated.
      • passphrase: The passphrase that was used for the private key encryption, if it was encrypted.

Signing certificates using CloudFlare CFSSL (a third party CA)

You can use CFSSL, CloudFlare's Public Key Infrastructure (PKI) toolkit, as an HTTP API server for signing certificates. Refer to the CFSSL documentation for more information.

Configuring the CFSSL API server

During startup, the CFSSL API server uses a configuration file to set the behavior of its authenticator and to set the certificate usage attribute.

Authenticator configuration

The CFSSL API allows applications to access CFSSL functionality with both authenticated and unauthenticated methods. Currently, Device Management supports using the standard authenticator only, which is based on the HMAC calculation of the request. For more information, refer to the documentation on CFSSL authentication.

Your authenticator configuration should contain the hex-encoded authentication key, which is used to compute the HMAC of the request to the CFSSL. The key must contain an even number of hexadecimal characters. Read more about the authenticator configuratation, under the "AUTHENTICATION" section. If you use another authenticator or unauthenticated access method, please contact support.

Certificate usage configuration

The usage configuration defines the purpose for which the certified public key may be used. The supported configuration is "client auth".

Configuration example

{
	"signing": {
		"profiles": {
			"CA": {
				"usages": ["client auth"],
				"expiry": "17520h",
				"auth_key": "ca_key"
			}
		},
		"default": {
			"usages": ["client auth"],
			"expiry": "17520h"
		}
	},
	"auth_keys": {
		"ca_key": {
			"type":"standard",
			"key":"0123456789ABCDEF0123456789ABCDEF"
		}
	}
}

In the example:

  • The "CA" profile is configured to use the authenticated method.
  • The "default" profile is configured to use the unauthenticated method.

Configuring CFSSL_AUTH as CA in Pelion Device Management

If you're using Device Management Portal:

  1. Create the CA:
    1. In the Device identity tab, select Certificates > Actions > Manage CAs and click Add CA.
  2. Select Issuer Type CFSSL_AUTH and enter the following information:
    • Host URL: This is the URL for connecting to the CFSSL server; it must be accessible.
    • (Optional) CFSSL profile: The profile configured on the CFSSL server that is used by CFSSL when creating the certificate. Refer to the CFSSL PROGRAM documentation, under "SIGNING PROFILES" section, for more information.
    • (Optional) CFSSL label: The label used by CFSSL when creating the certificate. Refer to the CFSSL SIGNING ENDPOINT documentation for more information regarding label and profile.
    • HMAC Hex key: This is used to compute the HMAC of every request using the HMAC-SHA-256 algorithm and should be the same key that was configured on the CFSSL server.

If you're using the External CA Management API, refer to the API documentation.

Previous Next