Skip to main content

Securely generating credentials for nRF91 Series devices

Once you have finished getting started with an nRF91 Series DK, you can securely generate credentials with the modem using the %KEYGEN AT command. Using this method, the private key is not exposed and never leaves the modem.

The steps in this guide require modem firmware v1.3.x or later for the nRF9160 DK, and modem firmware v2.0.0 or later for nRF91x1 devices.

note

The example AT commands in this guide include the AT prefix. Some samples may require an additional prefix to parse AT commands. If you encounter an error while using AT commands, refer to the documentation for that sample.

Generating credentials using Python scripts​

This is the recommended method for generating credentials. The other methods described on this page provide underlying details for advanced users designing their own solutions.

The easiest way to securely generate credentials on a device and obtain a csv file for onboarding the device to nRF Cloud is to use the device_credentials_installer.py script. For details, see the Device Credentials Installer documentation.

Clone the entire repository to your computer. Do not only download the script, as it depends on other scripts in the same repository. Follow the installation instructions for the required Python packages using pip, then follow the instructions for the device_credentials_installer.py script.

This method does not expose the private key.

Generating credentials using AT commands​

This section applies to devices using MQTT. It provides detailed background information on how the process automated by the device_credentials_installer.py script works.

This is not the recommended method for credential generation. Use the Python scripts in the previous section before attempting to use AT commands.

See Connecting a device using CoAP for more information on certificate requirements for CoAP devices, and Managing credentials to inject a CoAP CA certificate to an already onboarded device.

This method does not expose the private key.

To generate credentials on the device using AT commands:

  1. Connect the device to your computer over USB.

  2. Open the Serial Terminal app.

  3. To ensure the modem is deactivated, send the following AT command:

    AT+CFUN=4

    In the output, <sec_tag> is the slot in the modem where credentials are stored. The default <sec_tag> for nRF Cloud credentials is 16842753. In most cases, this slot already contains credentials. You must delete these to inject new credentials in the steps that follow. Otherwise, you can use a different slot.

    To see which slots are currently used, enter the AT%CMNG AT command:

    AT%CMNG=1

  4. If you intend to use the default slot 16842753, delete the existing certificate and private key by first sending the following AT command:

    AT%CMNG=3,16842753,1

    When you see OK in the terminal, enter the next command:

    AT%CMNG=3,16842753,2

    If you resend AT%CMNG=1, you see a value only for type 0 (CA certificate). This is expected, as you are not injecting a new CA certificate.

  5. To generate a private key in the modem and receive the associated certificate signing request (CSR), enter the following AT command. If you are not using the slot 16842753, substitute the correct value:

    AT%KEYGEN=16842753,2,0

    The %KEYGEN command uses the default value of the nRF9160's UUID as the CN in the credential. If you are using a different device ID or MQTT client ID, update your AT%KEYGEN command to use that ID as the CN value.

    The output of a successful AT%KEYGEN command is a base64-encoded CBOR object.

  6. Convert the CBOR object to a certificate signing request (CSR) in PEM format using the modem_credentials_parser.py script. See the Modem Credentials Parser documentation for additional details.

    note

    If you are manually copying and pasting the %KEYGEN output, make sure to copy all characters of the base64 string that is enclosed in double quotes.

  7. If you do not already have a CA certificate and private key, use the create_ca_cert.py script to create a CA and a key that you can use to sign all your device certificates.

  8. Use the CSR PEM file to create a device certificate with the create_device_credentials.py script. See the Create Device Credentials documentation for additional details.

  9. If the device uses MQTT to connect to nRF Cloud, write the device certificate to the device using the same <sec_tag> you used for the %KEYGEN AT command. See Managing credentials for details.

    After injecting the credentials, your device contains the private key in the <sec_tag> provided to the %KEYGEN AT command, as well as a device certificate.

  10. Download an AWS Root CA certificate. This is required for communicating with nRF Cloud.

  11. Write the CA certificate to your device using the same <sec_tag> you used for the %KEYGEN AT command.

    The device now has the credentials it needs to use all of the nRF Cloud APIs:

    • an AWS CA certificate
    • a private key
    • a device certificate for MQTT

  12. Onboard the device or register its public key, depending upon your protocol and which services you want to access:

    • A device that uses MQTT or the nRF Cloud FOTA service must be onboarded.

    • nRF Cloud REST APIs requiring a JSON Web Token (JWT): The device does not need to be onboarded.

      Register the device's public key through the RegisterPublicKeys endpoint.

    For default or prebuilt Asset Tracker applications, onboard your device using the nrf-[IMEI] device ID. Otherwise, configure these applications to use the device UUID.

If your device already has an active SIM card installed, you can see the device in your account and connected after a restart.

Generating credentials on a computer​

You can create credentials off-device and load them into the device later. This method is less secure, because it exposes the private key.

  1. To create a device certificate and a key pair (public key and private key), use the create_device_credentials.py script. See the Create Device Credentials documentation for additional details. For the -cn parameter (Common Name) to create_device_credentials.py use your device's nRF Cloud device ID. To use the device's internal UUID, see How to obtain the nRF9160's UUID.

    This step requires a CA certificate and its private key. If you do not already have one, use the create_ca_cert.py script to create a CA and key that you can use to sign all your device certificates.

  2. Upload the device certificate to nRF Cloud using the OnboardDevices endpoint.

    A successful call to the endpoint onboards the device and associates it with your nRF Cloud account. Devices that use MQTT or the nRF Cloud FOTA service must be onboarded and associated. If the device does not need to be onboarded but needs to use certain nRF Cloud REST APIs requiring a JWT, provide the public key generated above to nRF Cloud using the RegisterPublicKeys endpoint.

  3. Write the private key to your device so that it can communicate with nRF Cloud through MQTT (for mTLS) or REST (for signing JWTs). Use the desired <sec_tag>; typically 16842753 for nRF Cloud. See Managing credentials for details.

  4. If the device uses MQTT to connect to nRF Cloud, it needs the device certificate generated above. Write the device certificate to your device using the same <sec_tag> as in previous steps.

  5. Download an AWS Root CA certificate. This is required for communicating with nRF Cloud.

  6. Write the CA certificate to your device using the same <sec_tag> you used for the %KEYGEN AT command.

The device now has:

  • An AWS CA certificate.
  • A private key.
  • A device certificate for MQTT.

The device is ready to interact with nRF Cloud through REST or MQTT.

Managing credentials​

Manage the credentials using the %CMNG AT command, either through the AT command directly or the Cellular Monitor Certificate manager.

Using the Cellular Monitor Certificate manager​

Complete the following steps to update the device's credentials:

  1. Connect your device over USB to the computer running nRF Connect for Desktop.

  2. Turn the device on.

  3. Open the Serial Terminal app.

  4. Choose your device to connect.

  5. Confirm that your device is connected.

    If the device does not respond, press the RESET (SW5) button to reboot the device.

  6. In the terminal, enter AT+CFUN=4 to disable the modem.

  7. Check the output to confirm that the modem is disabled.

  8. Open the Cellular Monitor app.

  9. Choose your device.

  10. Select the Certificate Manager tab.

  11. Type your <sec_tag> into the Security tag field, or leave the default value 16842753.

  12. Copy and paste the following AWS CA certificate and CoAP root CA certificate into the CA Certificate field, depending on the protocol.

    The following block contains the exact text of the AWS CA certificate, including the headers:

    -----BEGIN CERTIFICATE-----
    MIIDQTCCAimgAwIBAgITBmyfz5m/jAo54vB4ikPmljZbyjANBgkqhkiG9w0BAQsF
    ADA5MQswCQYDVQQGEwJVUzEPMA0GA1UEChMGQW1hem9uMRkwFwYDVQQDExBBbWF6
    b24gUm9vdCBDQSAxMB4XDTE1MDUyNjAwMDAwMFoXDTM4MDExNzAwMDAwMFowOTEL
    MAkGA1UEBhMCVVMxDzANBgNVBAoTBkFtYXpvbjEZMBcGA1UEAxMQQW1hem9uIFJv
    b3QgQ0EgMTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALJ4gHHKeNXj
    ca9HgFB0fW7Y14h29Jlo91ghYPl0hAEvrAIthtOgQ3pOsqTQNroBvo3bSMgHFzZM
    9O6II8c+6zf1tRn4SWiw3te5djgdYZ6k/oI2peVKVuRF4fn9tBb6dNqcmzU5L/qw
    IFAGbHrQgLKm+a/sRxmPUDgH3KKHOVj4utWp+UhnMJbulHheb4mjUcAwhmahRWa6
    VOujw5H5SNz/0egwLX0tdHA114gk957EWW67c4cX8jJGKLhD+rcdqsq08p8kDi1L
    93FcXmn/6pUCyziKrlA4b9v7LWIbxcceVOF34GfID5yHI9Y/QCB/IIDEgEw+OyQm
    jgSubJrIqg0CAwEAAaNCMEAwDwYDVR0TAQH/BAUwAwEB/zAOBgNVHQ8BAf8EBAMC
    AYYwHQYDVR0OBBYEFIQYzIU07LwMlJQuCFmcx7IQTgoIMA0GCSqGSIb3DQEBCwUA
    A4IBAQCY8jdaQZChGsV2USggNiMOruYou6r4lK5IpDB/G/wkjUu0yKGX9rbxenDI
    U5PMCCjjmCXPI6T53iHTfIUJrU6adTrCC2qJeHZERxhlbI1Bjjt/msv0tadQ1wUs
    N+gDS63pYaACbvXy8MWy7Vu33PqUXHeeE6V/Uq2V8viTO96LXFvKWlJbYK8U90vv
    o/ufQJVtMVT8QtPHRh8jrdkPSHCa2XV4cdFyQzR1bldZwgJcJmApzyMZFo6IQ6XU
    5MsI+yMRQ+hDKXJioaldXgjUkK642M4UwtBV8ob2xJNDd2ZhwLnoQdeXeGADbkpy
    rqXRfboQnoZsG4q5WTP468SQvvG5
    -----END CERTIFICATE-----

  13. Copy and paste the device certificate into the Client certificate field.

  14. Copy and paste the private key into the Private key field.

    note

    If you use AT%KEYGEN to generate a private key, do not enter any data into the Private key field. If you enter data into this field, it will overwrite the key created by AT%KEYGEN and you will need to start the process again.

  15. Click Update certificate.

  16. Confirm that the device certificate is updated using the Serial Terminal app.

  17. Press the RESET (SW5) button to reboot the device. This also re-enables the modem.

    The device attempts to re-connect with updated credentials.

  18. Confirm in the Serial Terminal app that the device connects successfully to nRF Cloud. You can also confirm that the device is onboarded and online in the nRF Cloud portal.

Using AT commands​

The Serial Terminal app does not properly format line breaks.

Writing a CA certificate​

To write a CA certificate to your device, give the following AT command:

AT%CMNG=0,<sec_tag>,0,"<CA_cert_text>"

Writing a device certificate​

To write a device certificate to your device, give the following AT command:

AT%CMNG=0,<sec_tag>,1,"<device_cert_text>"

Writing a private key​

To write a private key to your device, give the following AT command:

AT%CMNG=0,<sec_tag>,2,"<private_key_text>"

Additional information​

See background information on device security.

Last updated on
This page is human-authored. If you see any errors, outdated information, or any other suggestions for improving the contents, please contact us!