Modem JWT

The Modem JWT library provides access to the modem’s JSON Web Token (JWT) generation feature, which is available in modem firmware v1.3.0 or higher.

To use the library to request a JWT, complete the following steps:

  • Enable the library.

  • Populate the jwt_data structure with your desired values.

  • Pass the structure to the function that generates JWT (modem_jwt_generate()).

You can configure the following values in the jwt_data structure:

  • jwt_data.sec_tag - Optional. The sec tag must contain a valid signing key. If zero is given, modem uses its own key for signing.

  • jwt_data.key - Required if sec_tag is not zero. Defines the type of key in the sec tag.

  • jwt_data.alg - Required if sec_tag is not zero. Defines the JWT signing algorithm. Currently, only ECDSA 256 is supported.

  • jwt_data.exp_delta_s - Optional. If set, and if the modem has a valid date and time, the iat and exp claims are populated.

  • jwt_data.subject - Optional. Corresponds to sub claim. Use NULL if you want to leave out this field.

  • jwt_data.audience - Optional. Corresponds to aud claim. Use NULL if you want to leave out this field.

  • jwt_data.jwt_buf - Optional. Buffer for the generated, null-terminated, JWT string. If a buffer is not provided, the library will allocate memory.

  • jwt_data.jwt_sz - Size of JWT buffer. Required if jwt_data.jwt_buf is set.

If the function executes successfully, jwt_data.jwt_buf will contain the JSON Web Token.

Configuration

Configure the following options when using the library:

API documentation

Header file: include/modem/modem_jwt.h
Source file: lib/modem/modem_jwt.c
group modem_jwt

Enums

enum jwt_key_type

The type of key to be used for signing the JWT.

Values:

enumerator JWT_KEY_TYPE_CLIENT_PRIV
enumerator JWT_KEY_TYPE_ENDORSEMENT
enum jwt_alg_type

JWT signing algorithm.

Values:

enumerator JWT_ALG_TYPE_ES256

Functions

int modem_jwt_generate(struct jwt_data *const jwt)

Generates a JWT using the supplied parameters. If successful, the JWT string will be stored in the supplied struct. This function will allocate memory for the JWT if the user does not provide a buffer. In that case, the user is responsible for freeing the memory by calling modem_jwt_free.

Subject and audience fields may be NULL in which case those fields are left out from generated JWT token.

If sec_tag value is given as zero, JWT is signed with Nordic’s own keys that already exist in the modem.

Parameters

  • jwt – [inout] Pointer to struct containing JWT parameters and result.

Return values

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

int modem_jwt_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).

Uses internally modem_jwt_generate and parses JWT token for “iss” “jti” fields which contains given UUID values.

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.

void modem_jwt_free(char *const jwt_buf)

Frees the JWT buffer allocated by modem_jwt_generate.

Parameters

  • jwt_buf – [in] Pointer to JWT buffer; see jwt_data.

struct jwt_data
#include <modem_jwt.h>

JWT parameters required for JWT generation and pointer to generated JWT.

Public Members

int sec_tag

Modem sec tag to use for JWT signing

enum jwt_key_type key

Key type in the specified sec tag

enum jwt_alg_type alg

JWT signing algorithm

uint32_t exp_delta_s

Defines how long the JWT will be valid; in seconds (from generation). The ‘iat’ and ‘exp’ claims will be populated only if the modem has a valid date and time.

const char *subject

NULL terminated ‘sub’ claim; the principal that is the subject of the JWT

const char *audience

NULL terminated ‘aud’ claim; intended recipient of the JWT

char *jwt_buf

Buffer to which the NULL terminated JWT will be copied. If a buffer is provided by the user, the size must also be set. If buffer is NULL, memory will be allocated and user must free memory when finished by calling modem_jwt_free.

size_t jwt_sz

Size of the user provided buffer or size of the allocated buffer