nRF Cloud preconnect provisioning

This page describes preconnect provisioning for devices without a Nordic cellular modem, such as nRF71 Series and nRF70 Series Wi-Fi® devices. Preconnect provisioning installs the credentials on the device and registers the device with your nRF Cloud account before the device connects to nRF Cloud for the first time. The process uses scripts from the nRF Cloud Utils Python package. These devices store the credentials in the TLS credentials subsystem (CONFIG_NRF_CLOUD_CREDENTIALS_MGMT_TLS_CRED).

For devices with a Nordic cellular modem, such as nRF91 Series devices, use the nRF Cloud device provisioning service for over-the-air provisioning.

Overview 

Connections to nRF Cloud are mutually authenticated. The device authenticates the server, and the server authenticates the device. To achieve this, two steps are necessary:

Provisioning - Installs the following credentials on the device:
- The nRF Cloud root CA certificate.
- The device credentials, which are a private key and a device certificate signed by your own CA certificate.
Onboarding - Registers the device certificate with your nRF Cloud account.

These two steps involve the following certificates, each with a different role:

Your own CA certificate - Signs the device certificates. It stays on your host and is not installed on the device or uploaded to nRF Cloud.
The nRF Cloud root CA certificate - Signs the nRF Cloud server certificates. It is installed on the device during provisioning, so that the device can check the authenticity of the server.
The device certificate - Signed by your own CA certificate. It is installed on the device during provisioning and registered with nRF Cloud during onboarding, so that the server can check the authenticity of the device.

The device certificate is issued for a device ID, which must match the device ID that the firmware uses to connect to nRF Cloud (see Configuration options for device ID). Devices without a modem have no modem UUID or IMEI that the device_credentials_installer script can read, so pass the device ID with its --id-str option.

Prerequisites 

Before you provision your first device, complete the following steps:

Install nRF Cloud Utils as described in the documentation.
To onboard the devices from the command line, also install the Memfault CLI, as described in the nRF Cloud device onboarding quickstart.
Create your own CA certificate using the create_ca_cert script, setting -c to your two-letter country code:
```
create_ca_cert -c US -f self_
```
This creates the self_*_ca.pem certificate and the self_*_prv.pem private key used in the following sections.

Provisioning 

You can provision the credentials in one of the following ways, listed from most to least secure:

On-device key generation (recommended) - The device generates its private key, which never leaves the device.
Host-generated key - The private key is generated on the host then installed on the device.
Hard-coded credentials - The private key is built into the firmware. This method is intended for testing purposes only.

All methods create an onboard.csv file that you use to onboard the devices.

Inputs 

Before you provision a device, determine the following inputs:

Device ID - The device certificate is issued for the device ID that the firmware uses to connect to nRF Cloud.
- With On-device key generation and Host-generated key, the firmware determines the device ID. The nRF Cloud library logs it when it initializes (CONFIG_NRF_CLOUD_PRINT_DETAILS, enabled by default):
```
<inf> nrf_cloud_info: Device ID: <device_id>
```
- With Hard-coded credentials, choose a globally unique device ID that is not prefixed with nrf-, and set it in the CONFIG_NRF_CLOUD_CLIENT_ID Kconfig option.
Transport - If the device connects to nRF Cloud using CoAP, add the --coap option to the provisioning command, so that the CoAP root CA certificate is also installed.
Number of devices - To onboard several devices at once, add the --append option to the device_credentials_installer command, so that the script adds a row for each device to the same onboard.csv file. The create_device_credentials script always appends to the file.

In the following sections, replace device_id with the device ID.

On-device key generation 

In this method, the device generates its private key and certificate signing request (CSR) using the nRF Cloud on-device key generation library. The device_credentials_installer script reads the CSR over the shell, signs the device certificate with your CA certificate, and installs it on the device.

To provision the device, complete the following steps:

Set the following Kconfig options in your application configuration, for example in the prj.conf file:
```
CONFIG_NRF_CLOUD_CREDENTIALS_KEYGEN=y
CONFIG_NRF_CLOUD_CREDENTIALS_KEYGEN_SHELL=y
```
Build and program the firmware, then read the device ID (see Inputs).
Connect the device to your host and run the following command:
```
device_credentials_installer --ca self_*_ca.pem --ca-key self_*_prv.pem --id-str device_id -s -d --cmd-type nrf_cloud_cred_shell [--verify] [--coap] [--append]
```
The --verify option checks that the installed device certificate matches the on-device key. It requires the CONFIG_NRF_CLOUD_CREDENTIALS_KEYGEN_VERIFY Kconfig option. See nRF Cloud Utils: Devices without a modem for other script options.

Host-generated key 

In this method, the device_credentials_installer script generates the private key and the device certificate on the host, and installs them using the TLS Credentials Shell.

This method is less secure than On-device key generation because the private key exists on the host and it is stored on the device as raw key material rather than as a non-exportable key.

To provision the device, complete the following steps:

Set the following Kconfig options in your application configuration, for example in the prj.conf file:
```
CONFIG_TLS_CREDENTIALS_SHELL=y
CONFIG_NRF_CLOUD_CREDENTIALS_KEYGEN=n
```
Disable on-device key generation. Otherwise, the nRF Cloud library uses the on-device key instead of the installed private key.
Build and program the firmware, then read the device ID (see Inputs).
Connect the device to your host and run the following command:
```
device_credentials_installer --ca self_*_ca.pem --ca-key self_*_prv.pem --id-str device_id -s -d --cmd-type tls_cred_shell --local-cert [--verify] [--coap] [--append]
```
The --verify option checks that the installed credentials match the generated ones. See nRF Cloud Utils: Devices without a modem for other script options.
Delete the private key from the host after the installation.

Hard-coded credentials 

When the CONFIG_NRF_CLOUD_PROVISION_CERTIFICATES Kconfig option is enabled, the nRF Cloud library installs the credentials built into the firmware during initialization.

Caution

With this option, the device private key is built into the firmware image as plain text. Because this is insecure, use it for testing purposes only.

The credentials are included from the header file set by the CONFIG_NRF_CLOUD_CERTIFICATES_FILE Kconfig option. The default header, subsys/net/lib/nrf_cloud/common/include/nrf_cloud-certs.h, includes the ca-cert.pem, client-cert.pem, and private-key.pem files from the include path.

To provision the device, complete the following steps:

Set the following Kconfig options in your application configuration, for example in the prj.conf file:
```
CONFIG_NRF_CLOUD_PROVISION_CERTIFICATES=y
CONFIG_NRF_CLOUD_CREDENTIALS_KEYGEN=n
CONFIG_NRF_CLOUD_CLIENT_ID_SRC_COMPILE_TIME=y
CONFIG_NRF_CLOUD_CLIENT_ID="device_id"
```
Disable on-device key generation. Otherwise, the nRF Cloud library uses the on-device key instead of the hard-coded private key.
Generate the credentials with the create_device_credentials script, setting -c to your two-letter country code:
```
create_device_credentials --ca self_*_ca.pem --ca-key self_*_prv.pem -c US --cn device_id -p dev_credentials --embed-save --csv onboard.csv [--coap]
```
The device ID must be the common name of the certificate. The --embed-save option saves the three .pem files in the dev_credentials folder. See Create Device Credentials for more details.
Add the folder containing the files to the include path of your application, for example by using zephyr_include_directories(certs) in your CMakeLists.txt file. Do not place them in subsys/net/lib/nrf_cloud/common/include, because files in that folder take precedence.
Build and program the firmware.

Onboarding 

Devices must be onboarded to your nRF Cloud account before they can connect. Onboarding uses the onboard.csv file created during provisioning, which can contain one or more devices (see Inputs).

You can onboard the devices in one of the following ways.

Onboarding with the nrfcloud CLI 

To onboard the devices from the command line, run the nrfcloud command of the Memfault CLI with the onboard.csv file:

nrfcloud --org-token $NRFCLOUD_OAT --org $NRFCLOUD_ORG --project $NRFCLOUD_PROJECT device create --csv onboard.csv

Where NRFCLOUD_OAT holds an organization auth token (OAT), and NRFCLOUD_ORG and NRFCLOUD_PROJECT the slugs of your nRF Cloud organization and project. See the nRF Cloud device onboarding prerequisites for how to get these values. Creating an OAT requires the Organization Admin role. Store the token securely, as it grants organization admin access to the API.

Onboarding with the nRF Cloud portal 

To onboard the devices from the nRF Cloud portal, go to the Devices section, select Add devices, and follow the instructions. Supply your onboard.csv file when prompted. See nRF Cloud Utils onboarding for the CSV format, if you need to create the file manually.