Detailed Description

Attestation driver header.

============================================================================

Overview

This file contains the APIs to generate an attestation token and obtain the expected token size to create a buffer to store the generated token. Attestation_PSA APIs are only available when TF-M is enabled and this file provides the non-secure interface to the Attestation_PSA driver.

Usage

After calling the Attestation initialization function, a token can be generated using the challenge provided by the attestation service to Attestation_PSA API. To generate a token, Attestation_PSA APIs assume that attestation keys are pre-provisioned in the pre-provisioned key sector.

Generating an attestation token

#include <ti/drivers/attestation/Attestation_PSA.h>
....
// Initialize Attestation_PSA driver
Attestation_PSA_init();
// A buffer of maximum allowed token size to store the generated token
// Alternatively, application can obtain the size of token using Attestation_PSA_getTokenSize()
// to dynamically allocate buffer of required size
uint8_t token[ATTESTATION_PSA_MAX_TOKEN_SIZE];
// A buffer for nonce or challenge provided by the attestation service to prevent replay or re-use of token
uint8_t nonce[32];
int_fast16_t status;
size_t tokenLength;
// Generate the token
status = Attestation_PSA_getToken(&nonce[0], sizeof(nonce), &token[0], sizeof(token), &tokenLength);
if (status != ATTESTATION_PSA_STATUS_SUCCESS)
{
     // Handle error
}

#include <stdint.h>
#include <stddef.h>
#include <psa/initial_attestation.h>

Include dependency graph for Attestation_PSA.h:

Go to the source code of this file.

Macros
#define	ATTESTATION_PSA_MAX_TOKEN_SIZE (PSA_INITIAL_ATTEST_MAX_TOKEN_SIZE)
	Maximum attestation token size. More...

#define	ATTESTATION_PSA_STATUS_SUCCESS ((int_fast16_t)0)
	Successful status code. More...

#define	ATTESTATION_PSA_STATUS_ERROR ((int_fast16_t)-1)
	Generic error status code. More...

#define	ATTESTATION_PSA_STATUS_RESOURCE_UNAVAILABLE ((int_fast16_t)-2)
	An error status code returned if the hardware or software resource is currently unavailable. More...

#define	ATTESTATION_PSA_STATUS_INVALID_INPUTS ((int_fast16_t)-3)
	Operation failed due to invalid inputs. More...

Functions
int_fast16_t	Attestation_PSA_getToken (const uint8_t auth_challenge, size_t challenge_size, uint8_t token_buf, size_t token_buf_size, size_t *token_size)
	Get initial attestation token. More...

int_fast16_t	Attestation_PSA_getTokenSize (size_t challenge_size, size_t *token_size)
	Get the exact size of initial attestation token in bytes. More...

void	Attestation_PSA_init (void)
	This function initializes the Attestation module. More...

Macro Definition Documentation

§ ATTESTATION_PSA_MAX_TOKEN_SIZE

#define ATTESTATION_PSA_MAX_TOKEN_SIZE (PSA_INITIAL_ATTEST_MAX_TOKEN_SIZE)

Maximum attestation token size.

The maximum size of an attestation token that can be generated by the attestation service. Used to configure buffers for services that verify the produced tokens.

§ ATTESTATION_PSA_STATUS_SUCCESS

#define ATTESTATION_PSA_STATUS_SUCCESS ((int_fast16_t)0)

Successful status code.

Functions return ATTESTATION_PSA_STATUS_SUCCESS if the function was executed successfully.

§ ATTESTATION_PSA_STATUS_ERROR

#define ATTESTATION_PSA_STATUS_ERROR ((int_fast16_t)-1)

Generic error status code.

Functions return ATTESTATION_PSA_STATUS_ERROR if the function was not executed successfully and no more pertinent error code could be returned.

§ ATTESTATION_PSA_STATUS_RESOURCE_UNAVAILABLE

#define ATTESTATION_PSA_STATUS_RESOURCE_UNAVAILABLE ((int_fast16_t)-2)

An error status code returned if the hardware or software resource is currently unavailable.

Attestation driver implementations may have hardware or software limitations on how many clients can simultaneously perform operations. This status code is returned if the mutual exclusion mechanism signals that an operation cannot currently be performed.

§ ATTESTATION_PSA_STATUS_INVALID_INPUTS

#define ATTESTATION_PSA_STATUS_INVALID_INPUTS ((int_fast16_t)-3)

Operation failed due to invalid inputs.

Functions return ATTESTATION_PSA_STATUS_INVALID_INPUTS if input validation fails.

Function Documentation

§ Attestation_PSA_getToken()

int_fast16_t Attestation_PSA_getToken	(	const uint8_t *	auth_challenge,
		size_t	challenge_size,
		uint8_t *	token_buf,
		size_t	token_buf_size,
		size_t *	token_size
	)

Get initial attestation token.

Parameters

[in]	auth_challenge	Pointer to buffer where challenge input is stored.
[in]	challenge_size	Size of challenge object in bytes. Must be 32, 48, or 64-bytes.
[out]	token_buf	Pointer to the buffer where attestation token will be stored, with a maximum buffer size of ATTESTATION_PSA_MAX_TOKEN_SIZE.
[in]	token_buf_size	Size of allocated buffer for token, in bytes.
[out]	token_size	Size of the token that has been returned, in bytes.

Return values

ATTESTATION_PSA_STATUS_SUCCESS	The operation succeeded.
ATTESTATION_PSA_STATUS_ERROR	The operation failed.
ATTESTATION_PSA_STATUS_RESOURCE_UNAVAILABLE	The required hardware resource was not available. Try again later.
ATTESTATION_PSA_STATUS_INVALID_INPUTS	Input validation failed.

§ Attestation_PSA_getTokenSize()

int_fast16_t Attestation_PSA_getTokenSize	(	size_t	challenge_size,
		size_t *	token_size
	)

Get the exact size of initial attestation token in bytes.

Returns the size of the IAT token. It can be used if the caller dynamically allocates memory for the token buffer.