4. API reference¶
The Attestation API defines a header file that is provided by the implementation. The header is psa/initial_attestation.h.
All the elements are defined in the C language. The Attestation API makes use of standard C data types, including the fixed-width integer types from the ISO C99 specification update [C99].
4.1. API conventions¶
All functions return a status indication of type psa_status_t, which is defined by PSA Certified Status code API [PSA-STAT]. The value 0 (PSA_SUCCESS) indicates successful operation, and a negative value indicates an error. Each API documents the specific error codes that might be returned, and the meaning of each error.
All parameters of pointer type must be valid, non-null pointers unless the pointer is to a buffer of length 0 or the function’s documentation explicitly describes the behavior when the pointer is null. For implementations where a null pointer dereference usually aborts the application, passing NULL as a function parameter where a null pointer is not allowed should abort the caller in the habitual manner.
Pointers to input parameters may be in read-only memory. Output parameters must be in writable memory. Output parameters that are not buffers must also be readable, and the implementation must be able to write to a non-buffer output parameter and read back the same value.
4.2. Status codes¶
The Attestation API uses the status code definitions that are shared with the other PSA Certified APIs.
The following elements are defined in psa/error.h from PSA Certified Status code API [PSA-STAT] (previously defined in [PSA-FF-M]):
typedef int32_t psa_status_t; #define PSA_SUCCESS ((psa_status_t)0) #define PSA_ERROR_GENERIC_ERROR ((psa_status_t)-132) #define PSA_ERROR_INVALID_ARGUMENT ((psa_status_t)-135) #define PSA_ERROR_BUFFER_TOO_SMALL ((psa_status_t)-138) #define PSA_ERROR_SERVICE_FAILURE ((psa_status_t)-144)
These definitions must be available to an application that includes the psa/initial_attestation.h header file.
Implementation note
An implementation is permitted to define the status code interface elements within psa/initial_attestation.h, or to define them via inclusion of a psa/error.h header file that is shared with the implementation of other PSA Certified APIs.
4.3. General definitions¶
4.3.1. PSA_INITIAL_ATTEST_API_VERSION_MAJOR (macro)¶
The major version of this implementation of the Attestation API.
#define PSA_INITIAL_ATTEST_API_VERSION_MAJOR 1
4.3.2. PSA_INITIAL_ATTEST_API_VERSION_MINOR (macro)¶
The minor version of this implementation of the Attestation API.
#define PSA_INITIAL_ATTEST_API_VERSION_MINOR 0
4.3.3. PSA_INITIAL_ATTEST_MAX_TOKEN_SIZE (macro)¶
The maximum possible size of a token.
#define PSA_INITIAL_ATTEST_MAX_TOKEN_SIZE /* implementation-specific value */
The value of this constant is implementation defined.
4.4. Challenge sizes¶
The following constants define the valid challenge sizes that must be supported by the function
psa_initial_attest_get_token() and psa_initial_attest_get_token_size().
An implementation must not support other challenge sizes.
4.4.1. PSA_INITIAL_ATTEST_CHALLENGE_SIZE_32 (macro)¶
A challenge size of 32 bytes (256 bits).
#define PSA_INITIAL_ATTEST_CHALLENGE_SIZE_32 (32u)
4.4.2. PSA_INITIAL_ATTEST_CHALLENGE_SIZE_48 (macro)¶
A challenge size of 48 bytes (384 bits).
#define PSA_INITIAL_ATTEST_CHALLENGE_SIZE_48 (48u)
4.4.3. PSA_INITIAL_ATTEST_CHALLENGE_SIZE_64 (macro)¶
A challenge size of 64 bytes (512 bits).
#define PSA_INITIAL_ATTEST_CHALLENGE_SIZE_64 (64u)
4.5. Attestation¶
4.5.1. psa_initial_attest_get_token (function)¶
Retrieve the Initial Attestation Token.
psa_status_t psa_initial_attest_get_token(const uint8_t *auth_challenge, size_t challenge_size, uint8_t *token_buf, size_t token_buf_size, size_t *token_size);
Parameters
auth_challengeBuffer with a challenge object. The challenge object is data provided by the caller. For example, it may be a cryptographic nonce or a hash of data (such as an external object record).
If a hash of data is provided then it is the caller’s responsibility to ensure that the data is protected against replay attacks (for example, by including a cryptographic nonce within the data).
challenge_sizeSize of the buffer
auth_challengein bytes. The size must always be a supported challenge size. Supported challenge sizes are defined in Challenge sizes.token_bufOutput buffer where the attestation token is to be written.
token_buf_sizeSize of
token_buf. The expected size can be determined by using thepsa_initial_attest_get_token_sizefunction.token_sizeOutput variable for the actual token size.
Outputs
*token_bufOn success, the attestation token.
*token_sizeOn success, the number of bytes written into
token_buf.
Returns: psa_status_t
PSA_SUCCESSAction was performed successfully.
PSA_ERROR_SERVICE_FAILUREThe implementation failed to fully initialize.
PSA_ERROR_BUFFER_TOO_SMALLtoken_bufis too small for the attestation token.PSA_ERROR_INVALID_ARGUMENTThe challenge size is not supported.
PSA_ERROR_GENERIC_ERRORAn unspecified internal error has occurred.
Description
Retrieves the Initial Attestation Token. A challenge can be passed as an input to mitigate replay attacks.
4.5.2. psa_initial_attest_get_token_size (function)¶
Calculate the size of an Initial Attestation Token.
psa_status_t psa_initial_attest_get_token_size(size_t challenge_size, size_t *token_size);
Parameters
challenge_sizeSize of a challenge object in bytes. This must be a supported challenge size as specified in Challenge sizes.
token_sizeOutput variable for the token size.
Outputs
*token_sizeOn success, the maximum size of an attestation token in bytes when using the specified
challenge_size
Returns: psa_status_t
PSA_SUCCESSAction was performed successfully.
PSA_ERROR_SERVICE_FAILUREThe implementation failed to fully initialize.
PSA_ERROR_INVALID_ARGUMENTThe challenge size is not supported.
PSA_ERROR_GENERIC_ERRORAn unspecified internal error has occurred.
Description
Retrieve the exact size of the Initial Attestation Token in bytes, given a specific challenge size.
