![]() |
TF-M Reference Manual
1.2.0
TrustedFirmware-M
|
Attestation Token Creation Interface. More...
#include <stdint.h>
#include "qcbor.h"
#include "t_cose_sign1_sign.h"
Go to the source code of this file.
Data Structures | |
struct | attest_token_encode_ctx |
Macros | |
#define | TOKEN_OPT_OMIT_CLAIMS 0x40000000 |
#define | TOKEN_OPT_SHORT_CIRCUIT_SIGN 0x80000000 |
Functions | |
enum attest_token_err_t | attest_token_encode_start (struct attest_token_encode_ctx *me, uint32_t opt_flags, int32_t key_select, int32_t cose_alg_id, const struct q_useful_buf *out_buffer) |
Initialize a token creation context. More... | |
QCBOREncodeContext * | attest_token_encode_borrow_cbor_cntxt (struct attest_token_encode_ctx *me) |
Get a copy of the CBOR encoding context. More... | |
void | attest_token_encode_add_integer (struct attest_token_encode_ctx *me, int32_t label, int64_t value) |
Add a 64-bit signed integer claim. More... | |
void | attest_token_encode_add_bstr (struct attest_token_encode_ctx *me, int32_t label, const struct q_useful_buf_c *value) |
Add a binary string claim. More... | |
void | attest_token_encode_add_tstr (struct attest_token_encode_ctx *me, int32_t label, const struct q_useful_buf_c *value) |
Add a text string claim. More... | |
void | attest_token_encode_add_cbor (struct attest_token_encode_ctx *me, int32_t label, const struct q_useful_buf_c *encoded) |
Add some already-encoded CBOR to payload. More... | |
enum attest_token_err_t | attest_token_encode_finish (struct attest_token_encode_ctx *me, struct q_useful_buf_c *completed_token) |
Finish the token, complete the signing and get the result. More... | |
Attestation Token Creation Interface.
The context and functions here are the way to create an attestation token. The steps are roughly:
Definition in file attest_token.h.
#define TOKEN_OPT_OMIT_CLAIMS 0x40000000 |
Request that the claims internally generated not be added to the token. This is a test mode that results in a static token that never changes. Only the nonce is included. The nonce is under the callers control unlike the other claims.
Definition at line 107 of file attest_token.h.
#define TOKEN_OPT_SHORT_CIRCUIT_SIGN 0x80000000 |
A special test mode where a proper signature is not produced. In its place there is a concatenation of hashes of the payload to be the same size as the signature. This works and can be used to verify all of the SW stack except the public signature part. The token has no security value in this mode because anyone can replicate it.
Definition at line 117 of file attest_token.h.
enum attest_token_err_t |
Error codes returned from attestation token creation.
Definition at line 50 of file attest_token.h.
void attest_token_encode_add_bstr | ( | struct attest_token_encode_ctx * | me, |
int32_t | label, | ||
const struct q_useful_buf_c * | value | ||
) |
Add a binary string claim.
[in] | me | Token creation context. |
[in] | label | Integer label for claim. |
[in] | value | The binary claim data. |
Definition at line 355 of file attest_token_encode.c.
void attest_token_encode_add_cbor | ( | struct attest_token_encode_ctx * | me, |
int32_t | label, | ||
const struct q_useful_buf_c * | encoded | ||
) |
Add some already-encoded CBOR to payload.
[in] | me | Token creation context. |
[in] | label | Integer label for claim. |
[in] | encoded | The already-encoded CBOR. |
Encoded CBOR must be a full map or full array or a non-aggregate type. It cannot be a partial map or array. It can be nested maps and arrays, but they must all be complete.
void attest_token_encode_add_integer | ( | struct attest_token_encode_ctx * | me, |
int32_t | label, | ||
int64_t | value | ||
) |
Add a 64-bit signed integer claim.
[in] | me | Token creation context. |
[in] | label | Integer label for claim. |
[in] | value | The integer claim data. |
Definition at line 344 of file attest_token_encode.c.
void attest_token_encode_add_tstr | ( | struct attest_token_encode_ctx * | me, |
int32_t | label, | ||
const struct q_useful_buf_c * | value | ||
) |
Add a text string claim.
[in] | me | Token creation context. |
[in] | label | Integer label for claim. |
[in] | value | The text claim data. |
Definition at line 368 of file attest_token_encode.c.
QCBOREncodeContext* attest_token_encode_borrow_cbor_cntxt | ( | struct attest_token_encode_ctx * | me | ) |
Get a copy of the CBOR encoding context.
[in] | me | Token creation context. |
Allows the caller to encode CBOR right into the output buffer using any of the QCBOREncode_AddXXXX()
methods. Anything added here will be part of the payload that gets hashed. This can be used to make complex CBOR structures. All open arrays and maps must be close before calling any other attest_token_encode
methods. QCBOREncode_Finish()
should not be closed on this context.
Definition at line 335 of file attest_token_encode.c.
enum attest_token_err_t attest_token_encode_finish | ( | struct attest_token_encode_ctx * | me, |
struct q_useful_buf_c * | completed_token | ||
) |
Finish the token, complete the signing and get the result.
[in] | me | Token Creation Context. |
[out] | completed_token | Pointer and length to completed token. |
This completes the token after the payload has been added. When this is called the signing algorithm is run and the final formatting of the token is completed.
Definition at line 293 of file attest_token_encode.c.
enum attest_token_err_t attest_token_encode_start | ( | struct attest_token_encode_ctx * | me, |
uint32_t | opt_flags, | ||
int32_t | key_select, | ||
int32_t | cose_alg_id, | ||
const struct q_useful_buf * | out_buffer | ||
) |
Initialize a token creation context.
[in] | me | The token creation context to be initialized. |
[in] | opt_flags | Flags to select different custom options, for example TOKEN_OPT_OMIT_CLAIMS. |
[in] | key_select | Selects which attestation key to sign with. |
[in] | cose_alg_id | The algorithm to sign with. The IDs are defined in COSE (RFC 8152) or in the IANA COSE Registry. |
[out] | out_buffer | The output buffer to write the encoded token into. |
The size of the buffer in out_buffer->len
determines the size of the token that can be created. It must be able to hold the final encoded and signed token. The data encoding overhead is just that of CBOR. The signing overhead depends on the signing key size. It is about 150 bytes for 256-bit ECDSA.
If out_buffer->ptr
is NULL
and out_buffer_ptr->len
is large like UINT32_MAX
no token will be created but the length of the token that would be created will be in completed_token
as returned by attest_token_encode_finish(). None of the cryptographic functions run during this, but the sizes of what they would output is taken into account.
Definition at line 229 of file attest_token_encode.c.