Mistake on this page? Email us

Setting up FCU as a CA

Note: If you want to use FCU as a certificate authority, you must set it up as part of FCU's configuration. You can do this at any time, but we explain it as part of the initial setup process.

Device Management expects devices to have a certificate proving their right to connect to your Device Management account. To accept these certificates, Device Management must know the certificate authority (CA) that generated them.

Process overview

When FCU acts as a CA, it generates device certificates and signs them with a private key. This private key matches the FCU CA certificate.

If FCU acts as an intermediate CA, the FCU CA certificate is the end-entity certificate in the CA certificate chain, and FCU signs the device certificates.

For this process to work, you need to:

  1. Edit the certificate-authority section in the FCU configuration file.

  2. Generate the key and certificate pair, either yourself or by using FCU.

    If FCU is an intermediate CA, you can generate the key and certificate chain pair yourself or by using FCU.
    Using FCU's setup command creates a CSR. Use your Certificate Authority to sign the CSR, and provide the generated certificate chain to FCU.

  3. Upload the FCU CA certificate to Device Management Portal.

    If you inject devices with a certificate chain, upload the entire certificate chain to Device Management Portal.

Device Management can then verify devices' validity by checking the key in the devices' certificates against the CA certificate (or certificate chain) you uploaded. This confirms your FCU, and not an imposter, generated the certificates.

Assumptions

  • You have integrated FCU with your factory tool or with the Factory tool demo.
  • You don't have to provide the certificate until your devices are ready to come online, but it's best practice to provide it while setting up your factory process.

Editing the FCU configuration file

When FCU acts as a CA, it generates X.509 certificate with pre-specified fields as its X.509 Distinguished Name. The information for these fields is contained in the FCU configuration file.

In the configuration file, edit the certificate-authority section:

Parameter Explanation
common-name Common Name (CN) field.
organization-name Organization Name (O) field.
organizational-unit-name Organizational Unit (OU) field.
locality-name Locality (L) field.
state-or-province-name State or Province (ST) field.
country-name Country (C) field.

You can use any valid X.509 values - Device Management doesn't require any specific X.509 Distinguished Name.

Generating a CA key and certificate for FCU

When you need to certify FCU as a CA, there are two ways to generate a private key and certificate:

  • Self-generated in the FCU setup phase.
  • Provided by your factory tool.

Using FCU to generate credentials

  1. Edit the certificate-authority section in the FCU configuration file, as explained above.
  2. Invoke the FCU setup API. This generates three files under the directory <FCU DIR>/keystore:
    • A private key: fcu_private_key.pem.
    • Depending on the setup-ca-as-intermediate parameter in the FCU configuration file:
      • If setup-ca-as-intermediate is false:
        The setup command creates a self-signed X.509 certificate named fcu.crt.

      • If setup-ca-as-intermediate is true:
        The setup command creates a CSR named fcu_csr.pem. Use your certificate authority to sign the CSR, and provide the generated certificate chain to FCU in a file named fcu.crt. The fcu.crt file must have the following structure:

           -----BEGIN CERTIFICATE-----   
           (FCU certificate)   
           -----END CERTIFICATE-----   
           -----BEGIN CERTIFICATE-----   
           (Intermediate certificate)   
           -----END CERTIFICATE-----
           ...
           -----BEGIN CERTIFICATE-----
           (Intermediate certificate)
           -----END CERTIFICATE-----
           -----BEGIN CERTIFICATE-----
           (Root certificate)
           -----END CERTIFICATE-----
        

        Note: When you use FCU as a certificate authority, if fcu.crt is a certificate chain, you must specify a device-certificate-chain-depth value in the FCU configuration file.

Example: Creating a certificate chain using OpenSSL when FCU is set up as an intermediate CA

  1. Create configuration for adding CA extensions:

    (echo '[req]'; echo 'distinguished_name=dn'; echo '[dn]'; echo '[ext]'; echo "basicConstraints = CA:TRUE"; echo "keyUsage = digitalSignature, keyCertSign, cRLSign") > ca_config.cnf
     # Create private keys -
    openssl ecparam -out root_key.pem -name prime256v1 -genkey
    openssl ecparam -out intermediate_key.pem -name prime256v1 -genkey
    
  2. Create the root self-signed certificate:

    openssl req -key root_key.pem -new -x509 -subj "//CN=ROOT_CA" -days 7300 -sha256 -out root_cert.pem -config ca_config.cnf -extensions ext
    
  3. Create an intermediate certificate:

    openssl req -new -sha256 -subj "//CN=INT_CA" -key intermediate_key.pem -out intermediate_csr.pem
    openssl x509 -sha256 -req -in intermediate_csr.pem -out intermediate_cert.pem -CA root_cert.pem -CAkey root_key.pem -days 7300 -extfile ca_config.cnf -extensions ext -CAcreateserial
    cat intermediate_cert.pem root_cert.pem > intermediate_chain.pem
    
  4. Create the FCU certificate:

    openssl x509 -sha256 -req -in fcu_csr.pem -out fcu_cert.pem -CA intermediate_cert.pem -CAkey intermediate_key.pem -days 7300 -extfile ca_config.cnf -extensions ext -CAcreateserial
     # Verify chain-
    openssl verify -verbose -CApath no-such-dir -CAfile intermediate_chain.pem fcu_cert.pem
    
  5. Create the FCU certificate chain:

    cat fcu_cert.pem intermediate_chain.pem > fcu.crt
    
  6. Move the certificate to the FCU keystore.

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

Providing external credentials

You can create the CA private key and certificate using your own tools consistent with the CA certificate guidelines.

To add these to your FCU installation:

  1. Create a keystore folder in the FCU extracted archive.

  2. Place the private key (in PEM format) under the keystore folder. Name it fcu_private_key.pem.

  3. Place the certificate (in PEM format) under the keystore folder. Name it fcu.crt.

    If you are adding a certificate chain, order it from the end-entity (first in file) to the root certificate (last in file).

Tip: You do not need to use the setup command in this workflow, because that command is only for FCU-generated credentials.

Securing your factory CA keys

When you use FCU as a CA, FCU stores the private key of the CA in its keystore directory.

Anyone who steals this private key could impersonate legitimate devices associated with the Device Management account of the true owner of the private key. Therefore, you must protect the FCU private key to avoid operational and security risks.

At a minimum, we recommend the following mitigations:

  • Do not remove the private key from the machine running FCU, unless absolutely necessary.
  • Limit physical access to the machine to trusted individuals.
  • Limit network access to the machine to trusted individuals.
  • Limit access to FCU backups to trusted individuals.
  • Encrypt FCU backups.
  • Use a unique private key for every FCU instance.

If a private key is stolen, minimize the damage by removing the key's certificate from Device Management to block potentially compromised devices from registering. Please note that this also blocks legitimate devices signed with the compromised from registering.

Uploading the FCU CA to Device Management

You must upload your CA certificate or certificate chain file to your Device Management account so that Device Management trusts the certificates FCU generates.

Depending on your FCU configuration, choose either bootstrap or LwM2M. For more information see Device onboarding and connection options.

Choose the certificate or certificate chain file to upload in PEM format (fcu.crt).

Note: If you inject the device with a certificate chain, upload the rest of the chain, which signs the device certificate chain.
For example, if the FCU certificate chain is:

-----BEGIN CERTIFICATE-----   
(FCU certificate)   
-----END CERTIFICATE-----   
-----BEGIN CERTIFICATE-----   
(Intermediate certificate)   
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Root certificate)
-----END CERTIFICATE-----

If you use device-certificate-chain-depth of 2, the device contains the following part of the certificate chain, which consists of the FCU certificate and the device certificate that was generated and signed by FCU:

-----BEGIN CERTIFICATE-----   
(device certificate)   
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----   
(FCU certificate)   
-----END CERTIFICATE-----

In this scenario, upload the certificate chain of the intermediate who signed FCU. The chain looks like this:

-----BEGIN CERTIFICATE-----   
(Intermediate certificate)   
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Root certificate)
-----END CERTIFICATE-----