Modem attestation token

The Modem attestation token library is used to obtain an attestation token from an nRF9160-based device.

Attestation tokens are used to verify the authenticity of the device. An attestation token includes the device’s internal UUID and the UUID of the modem firmware that is installed in the device. An attestation token consists of two base64url strings. The format is base64url1.base64url2. The first base64url string (base64url1) is the Device Identity Attestation message, which is a CBOR encoded payload containing the device UUID, device type, and modem firmware UUID. The second base64url string (base64url2) is the CBOR Object Signing and Encryption (COSE) authentication metadata.

To use the library to obtain the attestation token, complete the following steps:

• Enable the Modem attestation token library.

• Initialize the Modem library integration layer and AT command parser libraries.

• Call the modem_attest_token_get() function to obtain the two base64url strings in the nrf_attestation_token structure.

• Enable token parsing (CONFIG_MODEM_ATTEST_TOKEN_PARSING).

• Call the modem_attest_token_parse() function to parse the token.

The function modem_attest_token_parse() parses nrf_attestation_token and populates the nrf_attestation_data structure with the data. To obtain only the device UUID string or the modem firmware UUID string or both, you must call modem_attest_token_get_uuids().

Configuration

Configure the following options when using this library:

• CONFIG_MODEM_ATTEST_TOKEN

• CONFIG_MODEM_ATTEST_TOKEN_PARSING

API documentation

Header file: include/modem/modem_attest_token.h

Source file: lib/modem/modem_attest_token.c

group modem_attest_token

Defines

NRF_UUID_BYTE_SZ

NRF_DEVICE_UUID_SZ

NRF_MODEM_FW_UUID_SZ

NRF_ATTEST_NONCE_SZ

NRF_UUID_V4_STR_LEN

NRF_DEVICE_UUID_STR_LEN

NRF_MODEM_FW_UUID_STR_LEN

Enums

enum nrf_id_srvc_msg_type

Values:

enumerator NRF_ID_SRVC_MSG_TYPE_INVALID

enumerator NRF_ID_SRVC_MSG_TYPE_ID_V1

enumerator NRF_ID_SRVC_MSG_TYPE_PROV_RESP_V1

enumerator NRF_ID_SRVC_MSG_TYPE_PUB_KEY_V2

enumerator NRF_ID_SRVC_MSG_TYPE_CSR_V2

enum nrf_device_type

Values:

enumerator NRF_DEVICE_TYPE_INVALID

enumerator NRF_DEVICE_TYPE_9160_SIAA

enumerator NRF_DEVICE_TYPE_9160_SIBA

enumerator NRF_DEVICE_TYPE_9160_SICA

Functions

int modem_attest_token_get(struct nrf_attestation_token *const token)

Gets the device attestation token from the modem. If successful, the base64url attestation string and base64url COSE string will be stored in the supplied struct. This function will allocate memory for the strings if buffers are not provided by the user. In that case, the user is responsible for freeing the memory by calling modem_attest_token_free.

Parameters

• token – [inout] Pointer to struct containing attestation token strings.

Return values

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

void modem_attest_token_free(struct nrf_attestation_token *const token)

Frees the memory allocated by modem_attest_token_get.

Parameters

• token – [in] Pointer to attestation token.

int modem_attest_token_parse(struct nrf_attestation_token const *const token_in, struct nrf_attestation_data *const data_out)

Parses attestation token.

Parameters

• token_in – [in] Pointer to struct containing attestation token strings.

• data_out – [out] Pointer to struct containing parsed attestation data.

Return values

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

int modem_attest_token_get_uuids(struct nrf_device_uuid *dev, struct nrf_modem_fw_uuid *mfw)

Gets the device and/or modem firmware UUID from the modem and returns it as a NULL terminated string in the supplied struct(s).

Parameters

• dev – [out] Pointer to struct containing device UUID string. Can be NULL if UUID is not wanted.

• mfw – [out] Pointer to struct containing modem fw UUID string. Can be NULL if UUID is not wanted.

Return values

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

struct nrf_attestation_token

#include <modem_attest_token.h>

Base64url attestation and COSE strings.

Public Members

char *attest

NULL terminated base64url attestation string buffer

size_t attest_sz

Size of the attestation buffer

char *cose

NULL terminated base64url COSE string buffer

size_t cose_sz

Size of the COSE buffer

struct nrf_attestation_data

#include <modem_attest_token.h>

Parsed attestation token data.

struct nrf_device_uuid

#include <modem_attest_token.h>

Device UUID string (UUID v4 format)

struct nrf_modem_fw_uuid

#include <modem_attest_token.h>

Modem firmware UUID string (UUID v4 format)