TF-M Reference Manual  1.2.0
TrustedFirmware-M
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
attest_token_decode_common.c File Reference

Common functions in attestation token decoder. More...

#include "attest_token_decode.h"
#include "attest.h"
#include "q_useful_buf.h"
#include "qcbor_util.h"
Include dependency graph for attest_token_decode_common.c:

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

Detailed Description

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.

Macro Definition Documentation

#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.

Function Documentation

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.

Parameters
[in]meThe token decoder context.
[in]labelThe integer label identifying the claim.
[out]claimThe byte string or NULL_Q_USEFUL_BUF_C.
Returns
An error from attest_token_err_t.
Return values
ATTEST_TOKEN_ERR_CBOR_STRUCTUREGeneral 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_FORMEDCBOR syntax is wrong and it is not decodable.
ATTEST_TOKEN_ERR_CBOR_TYPEReturned if the claim is not a byte string.
ATTEST_TOKEN_ERR_NOT_FOUNDData 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.

Parameters
[in]meThe token decoder context.
[out]itemsStructure into which all found items are placed.
Returns
An error from attest_token_err_t.
Return values
ATTEST_TOKEN_ERR_SUCCESSIndicates 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.

Here is the call graph for this function:

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.

Parameters
[in]meThe token decoder context.
[in]labelThe integer label identifying the claim.
[out]claimThe signed integer or 0.
Returns
An error from attest_token_err_t.
Return values
ATTEST_TOKEN_ERR_CBOR_STRUCTUREGeneral 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_FORMEDCBOR syntax is wrong and it is not decodable.
ATTEST_TOKEN_ERR_CBOR_TYPEReturned if the claim is not a byte string.
ATTEST_TOKEN_ERR_NOT_FOUNDData item for label was not found in token.
ATTEST_TOKEN_ERR_INTEGER_VALUEReturned 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.

Parameters
[in]meThe token decoder context.
[out]payloadThe returned, verified token payload.
Returns
An error from attest_token_err_t.

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.

Parameters
[in]meThe token decoder context.
[in]labelThe integer label identifying the claim.
[out]claimThe byte string or NULL_Q_USEFUL_BUF_C.
Returns
An error from attest_token_err_t.
Return values
ATTEST_TOKEN_ERR_CBOR_STRUCTUREGeneral 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_FORMEDCBOR syntax is wrong and it is not decodable.
ATTEST_TOKEN_ERR_CBOR_TYPEReturned if the claim is not a byte string.
ATTEST_TOKEN_ERR_NOT_FOUNDData 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.

Parameters
[in]meThe token decoder context.
[in]labelThe integer label identifying the claim.
[out]claimThe unsigned integer or 0.
Returns
An error from attest_token_err_t.
Return values
ATTEST_TOKEN_ERR_CBOR_STRUCTUREGeneral 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_FORMEDCBOR syntax is wrong and it is not decodable.
ATTEST_TOKEN_ERR_CBOR_TYPEReturned if the claim is not a byte string.
ATTEST_TOKEN_ERR_NOT_FOUNDData item for label was not found in token.
ATTEST_TOKEN_ERR_INTEGER_VALUEReturned 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.

Parameters
[in]meThe token decoder context to be initialized.
[in]optionsDecoding 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.

Here is the call graph for this function:

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.

Parameters
[in]meThe token decoder context.
[out]num_sw_componentsThe number of SW components in the token.
Returns
An error from attest_token_err_t.

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.

  • The SW components array is present and has one or more (not zero) SW components and the "no SW Components" claim is absent.
  • The "no SW Components" integer claim is present, its value is 1, and the SW Components array is absent.

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.

Parameters
[in]meThe token decoder context.
[in]requested_indexIndex, from 0 to num_sw_components, of request component.
[out]sw_componentsPlace to return the details of the SW component
Return values
ATTEST_TOKEN_ERR_NOT_FOUNDThere were not requested_index in the token.
ATTEST_TOKEN_ERR_CBOR_TYPEThe claim labeled to contain SW components is not an array.

Definition at line 531 of file attest_token_decode_common.c.