generate-devicecert.adoc

Device Certificate Generation

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

Once you have your final Fleet Root CA, you can use it to sign device certificates. You can then automate the process of installing device certificates, or generate the keys and certificate on the device and sign the cert via PKCS#10 CSR.

We can’t tell you exactly how to automate this process, but heres a recap of how to do it manually with a self-signed fleet root CA:

To generate a device certificate, follow these steps

1. Make sure you already have generated a fleet root CA, and have a directory structure like the one in that guide. If you don’t have exactly the same directory structure, adjust the following commands as needed.

2. Generate an ID for the device, and make a directory for it. This ID should be unique within your fleet, so we recommend using a UUID if you do not already have a scheme of unique identifiers.

   export device_id=$(uuidgen | tr "[:upper:]" "[:lower:]")
   export device_dir=${fleet_name}/devices/${device_id}
   mkdir -p ${device_dir}

3. Generate a device certificate and public key, and sign it with your local Fleet Root CA. More complex architectures are possible, such as using a CSR server and generating the device certificates inside an HSM on the device, but are out of scope for this document.

   1. You’ll need OpenSSL config files called client.cnf and client.ext stored in the devices directory. You can paste the following to create the files with our recommended configuration:

      cat <<EOF > ${fleet_name}/devices/device_cert.cnf
      [req]
      prompt = no
      distinguished_name = dn
      req_extensions = ext
      
      [dn]
      CN=\$ENV::device_id
      
      [ext]
      keyUsage=critical, digitalSignature
      extendedKeyUsage=critical, clientAuth
      EOF
      
      cat <<EOF > ${fleet_name}/devices/device_cert.ext
      keyUsage=critical, digitalSignature
      extendedKeyUsage=critical, clientAuth
      EOF

   2. Generate and sign the new device certificate:

      # Generate a new elliptic curve based key
      openssl ecparam -genkey -name prime256v1 | openssl ec -out "${device_dir}/pkey.ec.pem"
      
      # Convert it to PKCS#8 format
      openssl pkcs8 -topk8 -nocrypt -in "${device_dir}/pkey.ec.pem" -out "${device_dir}/pkey.pem"
      
      # Create a CSR for the new device
      openssl req -new -config "${fleet_name}/devices/device_cert.cnf" -key "${device_dir}/pkey.pem" \
        -out "${device_dir}/${device_id}.csr"
      
      # Submit and resolve the CSR using your locally-generated Fleet Root CA
      openssl x509 -req -days 365 -extfile "${fleet_name}/devices/device_cert.ext" \
        -in "${device_dir}/${device_id}.csr" -CAkey "${fleet_name}/fleet_root_ca.key" \
        -CA "${fleet_name}/fleet_root_ca.crt" -CAcreateserial -out "${device_dir}/client.pem"

      Warning

      This command string is designed for OpenSSL 1.1 or higher. If you use an older version or LibreSSL, it may not work.

4. Get the URL and certificate for your account’s device gateway

   1. You can get the URL from the credentials.zip that you download from the OTA Connect Portal. If you haven’t done so already, download a provisioning key.

   2. Extract the contents of the credentials.zip file to a local folder.

   3. In that folder, look for the file autoprov.url. It will contain a URL that resembles the following example:

      https://beefcafe-13eb-478b-b215-fbd10dbbec0e.device-gateway.ota.api.here.com:443

   4. Get the device gateway’s root certificate and save it in the device directory with the following openssl command:

      export device_gateway=<your-gateway-url> (1)
      openssl s_client -connect ${device_gateway}:8000 -servername $device_gateway -showcerts | \
        sed -n '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > ${device_dir}/root.crt

      1. Replace <your-gateway-url> with the URL from the previous step.

Once you have a signed device certificate and the device gateway’s cert saved in your device directory, you can install the certificates on the device.