![]() |
TF-M Reference Manual
1.2.0
TrustedFirmware-M
|
Common functions in attestation token decoder. More...
#include "attest_token_decode.h"
#include "attest.h"
#include "q_useful_buf.h"
#include "qcbor_util.h"
Go to the source code of this file.
Macros | |
#define | CLAIM_PRESENT_BIT(item_index) (0x01U << (item_index)) |
Functions | |
void | attest_token_decode_init (struct attest_token_decode_context *me, uint32_t options) |
Initialize token decoder. More... | |
enum attest_token_err_t | attest_token_decode_get_bstr (struct attest_token_decode_context *me, int32_t label, struct q_useful_buf_c *claim) |
Get a top-level claim, by integer label that is a byte string. More... | |
enum attest_token_err_t | attest_token_decode_get_tstr (struct attest_token_decode_context *me, int32_t label, struct q_useful_buf_c *claim) |
Get a top-level claim, by integer label that is a text string. More... | |
enum attest_token_err_t | attest_token_decode_get_int (struct attest_token_decode_context *me, int32_t label, int64_t *integer) |
Get a top-level claim by integer label who's value is a signed integer. More... | |
enum attest_token_err_t | attest_token_decode_get_uint (struct attest_token_decode_context *me, int32_t label, uint64_t *integer) |
Get a top-level claim by integer label who's value is an unsigned integer. More... | |
enum attest_token_err_t | attest_token_decode_get_payload (struct attest_token_decode_context *me, struct q_useful_buf_c *payload) |
Get undecoded CBOR payload from the token. More... | |
enum attest_token_err_t | attest_token_decode_get_iat_simple (struct attest_token_decode_context *me, struct attest_token_iat_simple_t *items) |
Batch fetch of all simple data items in a token. More... | |
enum attest_token_err_t | attest_token_get_num_sw_components (struct attest_token_decode_context *me, uint32_t *num_sw_components) |
Get the number of SW components in the token. More... | |
enum attest_token_err_t | attest_token_get_sw_component (struct attest_token_decode_context *me, uint32_t requested_index, struct attest_token_sw_component_t *sw_components) |
Get the nth SW component. More... | |
Common functions in attestation token decoder.
This decodes and verifies an attestation token giving access to the data items in the token. The data items are also known as claims.
This is written primarily as tests for the token encoder, though it close to a full commercial token decoder. The main thing missing is a thorough test suite for it. Test before commercial use is important as this is a parser / decoder and thus subject to attack by malicious input. It does however, use QCBOR for most base parsing, and QCBOR is thoroughly tested and commercial.
This is oriented around the Arm-defined initial attestation token.
uint_fast8_t
is used for type and nest levels. They are 8-bit quantities, but making using uint8_t variables and parameters can result in bigger, slower code. uint_fast8_t
is part of <stdint.h>
. It is not used in structures where it is more important to keep the size smaller.
Definition in file attest_token_decode_common.c.
#define CLAIM_PRESENT_BIT | ( | item_index | ) | (0x01U << (item_index)) |
Compute the bit indicating a claim is present
Definition at line 46 of file attest_token_decode_common.c.
enum attest_token_err_t attest_token_decode_get_bstr | ( | struct attest_token_decode_context * | me, |
int32_t | label, | ||
struct q_useful_buf_c * | claim | ||
) |
Get a top-level claim, by integer label that is a byte string.
[in] | me | The token decoder context. |
[in] | label | The integer label identifying the claim. |
[out] | claim | The byte string or NULL_Q_USEFUL_BUF_C . |
ATTEST_TOKEN_ERR_CBOR_STRUCTURE | General structure of the token is incorrect, for example the top level is not a map or some map wasn't closed. |
ATTEST_TOKEN_ERR_CBOR_NOT_WELL_FORMED | CBOR syntax is wrong and it is not decodable. |
ATTEST_TOKEN_ERR_CBOR_TYPE | Returned if the claim is not a byte string. |
ATTEST_TOKEN_ERR_NOT_FOUND | Data item for label was not found in token. |
If an error occurs, the claim will be set to NULL_Q_USEFUL_BUF_C
and the error state inside attest_token_decode_context
will be set.
Definition at line 64 of file attest_token_decode_common.c.
enum attest_token_err_t attest_token_decode_get_iat_simple | ( | struct attest_token_decode_context * | me, |
struct attest_token_iat_simple_t * | items | ||
) |
Batch fetch of all simple data items in a token.
[in] | me | The token decoder context. |
[out] | items | Structure into which all found items are placed. |
ATTEST_TOKEN_ERR_SUCCESS | Indicates that the token was successfully searched. It could mean that all the data item were found, only some were found, or even none were found. |
This searches the token for the simple unstructured data items all at once. It can be a little more efficient than getting them one by one.
Use IS_ITEM_FLAG_SET on item_flags
in attest_token_iat_simple_t
to determine if the data item was found or not and whether the corresponding member in the structure is valid.
Definition at line 252 of file attest_token_decode_common.c.
enum attest_token_err_t attest_token_decode_get_int | ( | struct attest_token_decode_context * | me, |
int32_t | label, | ||
int64_t * | claim | ||
) |
Get a top-level claim by integer label who's value is a signed integer.
[in] | me | The token decoder context. |
[in] | label | The integer label identifying the claim. |
[out] | claim | The signed integer or 0. |
ATTEST_TOKEN_ERR_CBOR_STRUCTURE | General structure of the token is incorrect, for example the top level is not a map or some map wasn't closed. |
ATTEST_TOKEN_ERR_CBOR_NOT_WELL_FORMED | CBOR syntax is wrong and it is not decodable. |
ATTEST_TOKEN_ERR_CBOR_TYPE | Returned if the claim is not a byte string. |
ATTEST_TOKEN_ERR_NOT_FOUND | Data item for label was not found in token. |
ATTEST_TOKEN_ERR_INTEGER_VALUE | Returned if the integer value is larger than INT64_MAX . |
This will succeed if the CBOR type of the claim is either a positive or negative integer as long as the value is between INT64_MIN
and INT64_MAX
.
See also attest_token_decode_get_uint().
If an error occurs the value 0 will be returned and the error inside the attest_token_decode_context
will be set.
Definition at line 128 of file attest_token_decode_common.c.
enum attest_token_err_t attest_token_decode_get_payload | ( | struct attest_token_decode_context * | me, |
struct q_useful_buf_c * | payload | ||
) |
Get undecoded CBOR payload from the token.
[in] | me | The token decoder context. |
[out] | payload | The returned, verified token payload. |
This will return an error if the signature over the payload did not validate.
This allows the caller to parse the payload with any CBOR decoder they wish to use. It also an "escape hatch" to get to claims in the token not supported by decoding in this implementation, for example claims that have non-integer labels.
Definition at line 224 of file attest_token_decode_common.c.
enum attest_token_err_t attest_token_decode_get_tstr | ( | struct attest_token_decode_context * | me, |
int32_t | label, | ||
struct q_useful_buf_c * | claim | ||
) |
Get a top-level claim, by integer label that is a text string.
[in] | me | The token decoder context. |
[in] | label | The integer label identifying the claim. |
[out] | claim | The byte string or NULL_Q_USEFUL_BUF_C . |
ATTEST_TOKEN_ERR_CBOR_STRUCTURE | General structure of the token is incorrect, for example the top level is not a map or some map wasn't closed. |
ATTEST_TOKEN_ERR_CBOR_NOT_WELL_FORMED | CBOR syntax is wrong and it is not decodable. |
ATTEST_TOKEN_ERR_CBOR_TYPE | Returned if the claim is not a byte string. |
ATTEST_TOKEN_ERR_NOT_FOUND | Data item for label was not found in token. |
Even though this is a text string, it is not NULL-terminated.
If an error occurs, the claim will be set to NULL_Q_USEFUL_BUF_C
and the error state inside attest_token_decode_context
will be set.
Definition at line 96 of file attest_token_decode_common.c.
enum attest_token_err_t attest_token_decode_get_uint | ( | struct attest_token_decode_context * | me, |
int32_t | label, | ||
uint64_t * | claim | ||
) |
Get a top-level claim by integer label who's value is an unsigned integer.
[in] | me | The token decoder context. |
[in] | label | The integer label identifying the claim. |
[out] | claim | The unsigned integer or 0. |
ATTEST_TOKEN_ERR_CBOR_STRUCTURE | General structure of the token is incorrect, for example the top level is not a map or some map wasn't closed. |
ATTEST_TOKEN_ERR_CBOR_NOT_WELL_FORMED | CBOR syntax is wrong and it is not decodable. |
ATTEST_TOKEN_ERR_CBOR_TYPE | Returned if the claim is not a byte string. |
ATTEST_TOKEN_ERR_NOT_FOUND | Data item for label was not found in token. |
ATTEST_TOKEN_ERR_INTEGER_VALUE | Returned if the integer value is negative. |
This will succeed if the CBOR type of the claim is either a positive or negative integer as long as the value is between 0 and MAX_UINT64
.
See also attest_token_decode_get_int().
If an error occurs the value 0 will be returned and the error inside the attest_token_decode_context
will be set.
Definition at line 176 of file attest_token_decode_common.c.
void attest_token_decode_init | ( | struct attest_token_decode_context * | me, |
uint32_t | options | ||
) |
Initialize token decoder.
[in] | me | The token decoder context to be initialized. |
[in] | options | Decoding options. |
Must be called on a attest_token_decode_context before use. An instance of attest_token_decode_context can be used again by calling this on it again.
Definition at line 52 of file attest_token_decode_common.c.
enum attest_token_err_t attest_token_get_num_sw_components | ( | struct attest_token_decode_context * | me, |
uint32_t * | num_sw_components | ||
) |
Get the number of SW components in the token.
[in] | me | The token decoder context. |
[out] | num_sw_components | The number of SW components in the token. |
If there are explicitly no SW components, this will return successfully and the num_sw_components
will be zero.
Per Arm's IAT specification the only two ways this will succeed are.
Definition at line 358 of file attest_token_decode_common.c.
enum attest_token_err_t attest_token_get_sw_component | ( | struct attest_token_decode_context * | me, |
uint32_t | requested_index, | ||
struct attest_token_sw_component_t * | sw_components | ||
) |
Get the nth SW component.
[in] | me | The token decoder context. |
[in] | requested_index | Index, from 0 to num_sw_components, of request component. |
[out] | sw_components | Place to return the details of the SW component |
ATTEST_TOKEN_ERR_NOT_FOUND | There were not requested_index in the token. |
ATTEST_TOKEN_ERR_CBOR_TYPE | The claim labeled to contain SW components is not an array. |
Definition at line 531 of file attest_token_decode_common.c.