|
| 1 | +/* |
| 2 | + * Copyright (c) 2024 Nordic Semiconductor ASA |
| 3 | + * |
| 4 | + * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause |
| 5 | + */ |
| 6 | + |
| 7 | +#ifndef _APP_JWT_H |
| 8 | +#define _APP_JWT_H |
| 9 | + |
| 10 | +#ifdef __cplusplus |
| 11 | +extern "C" { |
| 12 | +#endif |
| 13 | + |
| 14 | +/** |
| 15 | + * @file app_jwt.h |
| 16 | + * |
| 17 | + * @brief Generate a JWT with from application core. |
| 18 | + * @defgroup app_jwt JWT generation |
| 19 | + * @{ |
| 20 | + * |
| 21 | + */ |
| 22 | + |
| 23 | +#include <stdint.h> |
| 24 | +#include <stdbool.h> |
| 25 | +#include <strings.h> |
| 26 | + |
| 27 | +/** @brief Maximum size of a JWT string, could be used to allocate JWT |
| 28 | + * output buffer. |
| 29 | + */ |
| 30 | +#define APP_JWT_STR_MAX_LEN 900 |
| 31 | + |
| 32 | +/** @brief Maximum valid duration for JWTs generated by user application */ |
| 33 | +#define APP_JWT_VALID_TIME_S_MAX (7 * 24 * 60 * 60) |
| 34 | + |
| 35 | +/** @brief Default valid duration for JWTs generated by user application */ |
| 36 | +#define APP_JWT_VALID_TIME_S_DEF (10 * 60) |
| 37 | + |
| 38 | +/** @brief UUID size in bytes */ |
| 39 | +#define APP_JWT_UUID_BYTE_SZ 16 |
| 40 | + |
| 41 | +/** @brief UUID v4 format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + '\0' */ |
| 42 | +#define APP_JWT_UUID_V4_STR_LEN (((APP_JWT_UUID_BYTE_SZ * 2) + 4) + 1) |
| 43 | + |
| 44 | +/** @brief Size in bytes of each JWT String field */ |
| 45 | +#define APP_JWT_CLAIM_MAX_SIZE 64 |
| 46 | + |
| 47 | +/** @brief The type of key to be used for signing the JWT. */ |
| 48 | +enum app_jwt_key_type { |
| 49 | + JWT_KEY_TYPE_CLIENT_PRIV = 2, |
| 50 | + JWT_KEY_TYPE_ENDORSEMENT = 8, |
| 51 | +}; |
| 52 | + |
| 53 | +/** @brief JWT signing algorithm */ |
| 54 | +enum app_jwt_alg_type { |
| 55 | + JWT_ALG_TYPE_ES256 = 0, |
| 56 | +}; |
| 57 | + |
| 58 | +/** @brief JWT parameters required for JWT generation and pointer to generated JWT */ |
| 59 | +struct app_jwt_data { |
| 60 | + /** Sec tag to use for JWT signing */ |
| 61 | + unsigned int sec_tag; |
| 62 | + /** Key type in the specified sec tag */ |
| 63 | + enum app_jwt_key_type key_type; |
| 64 | + /** JWT signing algorithm */ |
| 65 | + enum app_jwt_alg_type alg; |
| 66 | + |
| 67 | + /** |
| 68 | + * Indicates if a 'kid' claim is required or not, if set to 1, 'kid' claim |
| 69 | + * will contain sha256 of the signing key. |
| 70 | + */ |
| 71 | + bool add_keyid_to_header; |
| 72 | + |
| 73 | + /** |
| 74 | + * NULL terminated 'jti' claim; Unique identifier; can be used to prevent the |
| 75 | + * JWT from being replayed |
| 76 | + */ |
| 77 | + const char *json_token_id; |
| 78 | + /** NULL terminated 'sub' claim; the principal that is the subject of the JWT */ |
| 79 | + const char *subject; |
| 80 | + /** NULL terminated 'aud' claim; intended recipient of the JWT */ |
| 81 | + const char *audience; |
| 82 | + /** NULL terminated 'iss' claim; Issuer of the JWT */ |
| 83 | + const char *issuer; |
| 84 | + |
| 85 | + /** |
| 86 | + * Indicates if an issue timestamp is required or not, if set to 1, 'exp' claim |
| 87 | + * will be present. |
| 88 | + */ |
| 89 | + bool add_timestamp; |
| 90 | + |
| 91 | + /** |
| 92 | + * Corresponds to 'exp' claim; Defines how long the JWT will be valid. |
| 93 | + * If application has a valid time source, and the 'iat' claim is present, |
| 94 | + * the timestamp in seconds will be added to this value. |
| 95 | + */ |
| 96 | + uint32_t validity_s; |
| 97 | + |
| 98 | + /** |
| 99 | + * Buffer to which the NULL terminated JWT will be copied. |
| 100 | + * It is the responsibility of the user to provide a valid buffer. |
| 101 | + * The returned JWT could be as long as 900 bytes, use the |
| 102 | + * defined size value APP_JWT_STR_MAX_LEN to create your supplied return buffer. |
| 103 | + */ |
| 104 | + char *jwt_buf; |
| 105 | + /** Size of the user provided buffer. */ |
| 106 | + size_t jwt_sz; |
| 107 | +}; |
| 108 | + |
| 109 | +/** |
| 110 | + * @brief Generate a JWT using the supplied parameters. If successful, |
| 111 | + * the JWT string will be stored in the supplied struct. |
| 112 | + * You are responsible for providing a valid pointer to store the JWT. |
| 113 | + * |
| 114 | + * Subject, audience, token ID and issuer fields may be NULL in which case those |
| 115 | + * fields are left out from generated JWT token. |
| 116 | + * |
| 117 | + * All fields will be truncated to 64 characters, you should always provide null |
| 118 | + * terminated strings. |
| 119 | + * |
| 120 | + * The API does not verify the time source validity, it is up to the caller to make sure |
| 121 | + * that the system has access to a valid time source, otherwise "iat" field will |
| 122 | + * contain an arbitrary timestamp. |
| 123 | + * |
| 124 | + * @param[in,out] jwt Pointer to struct containing JWT parameters and result. |
| 125 | + * |
| 126 | + * @retval 0 If the operation was successful. |
| 127 | + * @retval -errno Negative errno for other failures. |
| 128 | + */ |
| 129 | +int app_jwt_generate(struct app_jwt_data *const jwt); |
| 130 | + |
| 131 | +/** |
| 132 | + * @brief Get the device UUID from the secure domain |
| 133 | + * and return it as a NULL terminated string in the supplied buffer. |
| 134 | + * The device UUID can be used as a device identifier for cloud services and |
| 135 | + * for secure device management using the nRF Cloud Identity Service. |
| 136 | + * |
| 137 | + * UUID v4 defined by ITU-T X.667 | ISO/IEC 9834-8 has a length of 35 bytes, add |
| 138 | + * 1 byte for the atring termination character. You are expected to provide a buffer |
| 139 | + * of at least 36 bytes. |
| 140 | + * |
| 141 | + * @param[out] uuid_buffer Pointer to buffer where the device UUID string will be written to. |
| 142 | + * @param[in] uuid_buffer_size Size of the provided buffer. |
| 143 | + * |
| 144 | + * @retval 0 If the operation was successful. |
| 145 | + * @retval -errno Negative errno for other failures. |
| 146 | + */ |
| 147 | +int app_jwt_get_uuid(char *uuid_buffer, const size_t uuid_buffer_size); |
| 148 | + |
| 149 | +/** @} */ |
| 150 | + |
| 151 | +#ifdef __cplusplus |
| 152 | +} |
| 153 | +#endif |
| 154 | + |
| 155 | +#endif /* _APP_JWT_H */ |
0 commit comments