Attestation Token Creation Interface. More...

#include <stdint.h>
#include "qcbor.h"
#include "t_cose_sign1_sign.h"

Data Structures
struct	attest_token_ctx
	The context for creating an attestation token. More...

Macros
#define	TOKEN_OPT_OMIT_CLAIMS 0x40000000
	Request that the claims internally generated not be added to the token. More...

#define	TOKEN_OPT_SHORT_CIRCUIT_SIGN 0x80000000
	A special test mode where a proper signature is not produced. More...

Enumerations
enum	attest_token_err_t { ATTEST_TOKEN_ERR_SUCCESS = 0 , ATTEST_TOKEN_ERR_TOO_SMALL , ATTEST_TOKEN_ERR_CBOR_FORMATTING , ATTEST_TOKEN_ERR_GENERAL , ATTEST_TOKEN_ERR_HASH_UNAVAILABLE , ATTEST_TOKEN_ERR_CBOR_NOT_WELL_FORMED , ATTEST_TOKEN_ERR_CBOR_STRUCTURE , ATTETST_TOKEN_ERR_CBOR_TYPE , ATTEST_TOKEN_ERR_INTEGER_VALUE , ATTEST_TOKEN_ERR_COSE_SIGN1_FORMAT , ATTEST_TOKEN_ERR_COSE_SIGN1_VALIDATION , ATTEST_TOKEN_ERR_UNSUPPORTED_SIG_ALG , ATTEST_TOKEN_ERR_INSUFFICIENT_MEMORY , ATTEST_TOKEN_ERR_TAMPERING_DETECTED , ATTEST_TOKEN_ERR_VERIFICATION_KEY }
	Error codes returned from attestation token creation. More...

Functions
enum attest_token_err_t	attest_token_start (struct attest_token_ctx me, uint32_t opt_flags, int32_t key_select, int32_t cose_alg_id, const struct useful_buf out_buffer)
	Initialize a token creation context. More...

QCBOREncodeContext *	attest_token_borrow_cbor_cntxt (struct attest_token_ctx *me)
	Get a copy of the CBOR encoding context. More...

void	attest_token_add_integer (struct attest_token_ctx *me, int32_t label, int64_t value)
	Add a 64-bit signed integer claim. More...

void	attest_token_add_bstr (struct attest_token_ctx me, int32_t label, const struct useful_buf_c value)
	Add a binary string claim. More...

void	attest_token_add_tstr (struct attest_token_ctx me, int32_t label, const struct useful_buf_c value)
	Add a text string claim. More...

void	attest_token_add_encoded (struct attest_token_ctx me, int32_t label, const struct useful_buf_c encoded)
	Add some already-encoded CBOR to payload. More...

enum attest_token_err_t	attest_token_finish (struct attest_token_ctx me, struct useful_buf_c completed_token)
	Finish the token, complete the signing and get the result. More...

Detailed Description

Attestation Token Creation Interface.

The context and functions here are the way to create an attestation token. The steps are roughly:

Creation and initialize an attest_token_ctx indicating the options, key and such using attest_token_start().
Use various add methods to fill in the payload with claims. The encoding context can also be borrowed for more rich payloads.
Call attest_token_finish() to create the signature and finish formatting the COSE signed output.

Definition in file attest_token.h.

Macro Definition Documentation

◆ TOKEN_OPT_OMIT_CLAIMS

#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 89 of file attest_token.h.

◆ TOKEN_OPT_SHORT_CIRCUIT_SIGN

#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 99 of file attest_token.h.

Enumeration Type Documentation

◆ attest_token_err_t

enum attest_token_err_t

Error codes returned from attestation token creation.

Enumerator
ATTEST_TOKEN_ERR_SUCCESS	Success.
ATTEST_TOKEN_ERR_TOO_SMALL	The buffer passed in to receive the output is too small.
ATTEST_TOKEN_ERR_CBOR_FORMATTING	Something went wrong formatting the CBOR, most likely the payload has maps or arrays that are not closed.
ATTEST_TOKEN_ERR_GENERAL	A general, unspecific error when creating or decoding the token.
ATTEST_TOKEN_ERR_HASH_UNAVAILABLE	A hash function that is needed to make the token is not available.
ATTEST_TOKEN_ERR_CBOR_NOT_WELL_FORMED	CBOR Syntax not well-formed – a CBOR syntax error.
ATTEST_TOKEN_ERR_CBOR_STRUCTURE	Bad CBOR structure, for example not a map when was is required.
ATTETST_TOKEN_ERR_CBOR_TYPE	Bad CBOR type, for example an not a text string, when a text string is required.
ATTEST_TOKEN_ERR_INTEGER_VALUE	Integer too large, for example an `int32_t` is required, but value only fits in `int64_t`.
ATTEST_TOKEN_ERR_COSE_SIGN1_FORMAT	Something is wrong with the COSE signing structure, missing headers or such.
ATTEST_TOKEN_ERR_COSE_SIGN1_VALIDATION	COSE signature is invalid, data is corrupted.
ATTEST_TOKEN_ERR_UNSUPPORTED_SIG_ALG	The signing algorithm is not supported.
ATTEST_TOKEN_ERR_INSUFFICIENT_MEMORY	Out of memory.
ATTEST_TOKEN_ERR_TAMPERING_DETECTED	Tampering detected in cryptographic function.
ATTEST_TOKEN_ERR_VERIFICATION_KEY	Verification key is not found or of wrong type.

Definition at line 41 of file attest_token.h.

Function Documentation

◆ attest_token_start()

enum attest_token_err_t attest_token_start	(	struct attest_token_ctx *	me,
		uint32_t	opt_flags,
		int32_t	key_select,
		int32_t	cose_alg_id,
		const struct useful_buf *	out_buffer
	)

Initialize a token creation context.

Parameters

[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)] (https://tools.ietf.org/html/rfc8152) or in the [IANA COSE Registry] (https://www.iana.org/assignments/cose/cose.xhtml).
[out]	out_buffer	The output buffer to write the encoded token into.

Returns: one of the attest_token_err_t errors.

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_finish(). None of the cryptographic functions run during this, but the sizes of what they would output is taken into account.

◆ attest_token_borrow_cbor_cntxt()

QCBOREncodeContext * attest_token_borrow_cbor_cntxt ( struct attest_token_ctx * me )

Get a copy of the CBOR encoding context.

Parameters

[in] me Token creation context.

Returns: The CBOR encoding 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 methods. QCBOREncode_Finish() should not be closed on this context.

◆ attest_token_add_integer()

void attest_token_add_integer	(	struct attest_token_ctx *	me,
		int32_t	label,
		int64_t	value
	)

Add a 64-bit signed integer claim.

Parameters

[in]	me	Token creation context.
[in]	label	Integer label for claim.
[in]	value	The integer claim data.

◆ attest_token_add_bstr()

void attest_token_add_bstr	(	struct attest_token_ctx *	me,
		int32_t	label,
		const struct useful_buf_c *	value
	)

Add a binary string claim.

Parameters

[in]	me	Token creation context.
[in]	label	Integer label for claim.
[in]	value	The binary claim data.

◆ attest_token_add_tstr()

void attest_token_add_tstr	(	struct attest_token_ctx *	me,
		int32_t	label,
		const struct useful_buf_c *	value
	)

Add a text string claim.

Parameters

[in]	me	Token creation context.
[in]	label	Integer label for claim.
[in]	value	The text claim data.

◆ attest_token_add_encoded()

void attest_token_add_encoded	(	struct attest_token_ctx *	me,
		int32_t	label,
		const struct useful_buf_c *	encoded
	)

Add some already-encoded CBOR to payload.

Parameters

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

◆ attest_token_finish()

enum attest_token_err_t attest_token_finish	(	struct attest_token_ctx *	me,
		struct useful_buf_c *	completed_token
	)

Finish the token, complete the signing and get the result.

Parameters

[in]	me	Token Creation Context.
[out]	completed_token	Pointer and length to completed token.

Returns: one of the attest_token_err_t errors.

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.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ TOKEN_OPT_OMIT_CLAIMS

◆ TOKEN_OPT_SHORT_CIRCUIT_SIGN

Enumeration Type Documentation

◆ attest_token_err_t

Function Documentation

◆ attest_token_start()

◆ attest_token_borrow_cbor_cntxt()

◆ attest_token_add_integer()

◆ attest_token_add_bstr()

◆ attest_token_add_tstr()

◆ attest_token_add_encoded()

◆ attest_token_finish()