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 - Required. The sec tag must contain a valid signing key.

• jwt_data.key - Required. Defines the type of key in the sec tag.

• jwt_data.alg - Required. 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.

• jwt_data.audience - Optional. Corresponds to aud claim.

• 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:

• CONFIG_MODEM_JWT

• CONFIG_MODEM_JWT_MAX_LEN

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.

Parameters

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

Returns 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 struct 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.

char *subject

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

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