Attest: Extend the naming of token encoding related functionality
Emphasize the token encoding related functionality with
extending the name of relevant functions and structures
with the 'encode' word.
Change-Id: I96683c4be7fd3e6d8c79c131d93f58cfc57470c7
Signed-off-by: Laurence Lundblade <lgl@securitytheory.com>
Signed-off-by: Tamas Ban <tamas.ban@arm.com>
diff --git a/docs/reference/services/tfm_attestation_integration_guide.rst b/docs/reference/services/tfm_attestation_integration_guide.rst
index 5d29861..2a2f483 100644
--- a/docs/reference/services/tfm_attestation_integration_guide.rst
+++ b/docs/reference/services/tfm_attestation_integration_guide.rst
@@ -174,7 +174,7 @@
- Initial Attestation Service:
- ``attestation_core.c`` : Implements core functionalities such as
implementation of APIs, retrieval of claims and token creation.
- - ``attest_token.c``: Implements the token creation function such as
+ - ``attest_token_encode.c``: Implements the token creation functions such as
start and finish token creation and adding claims to the token.
- ``attestation_key.c``: Get the asymmetric attestation key from platform
layer and register it to the TF-M Crypto service for further usage.
diff --git a/secure_fw/partitions/initial_attestation/CMakeLists.inc b/secure_fw/partitions/initial_attestation/CMakeLists.inc
index 587f632..ed81818 100644
--- a/secure_fw/partitions/initial_attestation/CMakeLists.inc
+++ b/secure_fw/partitions/initial_attestation/CMakeLists.inc
@@ -41,7 +41,7 @@
"${INITIAL_ATTESTATION_DIR}/tfm_attestation.c"
"${INITIAL_ATTESTATION_DIR}/tfm_attestation_req_mngr.c"
"${INITIAL_ATTESTATION_DIR}/attestation_core.c"
- "${INITIAL_ATTESTATION_DIR}/attest_token.c"
+ "${INITIAL_ATTESTATION_DIR}/attest_token_encode.c"
)
if (SYMMETRIC_INITIAL_ATTESTATION)
diff --git a/secure_fw/partitions/initial_attestation/attest_token.h b/secure_fw/partitions/initial_attestation/attest_token.h
index 33c9354..b7bf58a 100644
--- a/secure_fw/partitions/initial_attestation/attest_token.h
+++ b/secure_fw/partitions/initial_attestation/attest_token.h
@@ -33,13 +33,13 @@
* The context and functions here are the way to create an attestation
* token. The steps are roughly:
*
- * -# Create and initialize an attest_token_ctx indicating the
- * options, key and such using attest_token_start().
+ * -# Create and initialize an attest_token_encode_ctx indicating the
+ * options, key and such using attest_token_encode_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
+ * -# Call attest_token_encode_finish() to create the signature and finish
* formatting the COSE signed output.
*/
@@ -119,7 +119,7 @@
/**
* The context for creating an attestation token. The caller of
- * attest_token must create one of these and pass it to the functions
+ * attest_token_encode must create one of these and pass it to the functions
* here. It is small enough that it can go on the stack. It is most of
* the memory needed to create a token except the output buffer and
* any memory requirements for the cryptographic operations.
@@ -128,7 +128,7 @@
*
* This is roughly 148 + 8 + 32 = 188 bytes
*/
-struct attest_token_ctx {
+struct attest_token_encode_ctx {
/* Private data structure */
QCBOREncodeContext cbor_enc_ctx;
uint32_t opt_flags;
@@ -146,7 +146,7 @@
*
* \param[in] me The token creation context to be initialized.
* \param[in] opt_flags Flags to select different custom options,
- for example \ref TOKEN_OPT_OMIT_CLAIMS.
+ * for example \ref TOKEN_OPT_OMIT_CLAIMS.
* \param[in] key_select Selects which attestation key to sign with.
* \param[in] cose_alg_id The algorithm to sign with. The IDs are
* defined in [COSE (RFC 8152)]
@@ -166,16 +166,16 @@
* If \c out_buffer->ptr is \c NULL and \c out_buffer_ptr->len is
* large like \c UINT32_MAX no token will be created but the length of
* the token that would be created will be in \c completed_token as
- * returned by attest_token_finish(). None of the cryptographic
+ * 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.
*/
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 q_useful_buf *out_buffer);
+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);
@@ -190,10 +190,11 @@
* any of the \c 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 \c attest_token methods. \c
+ * close before calling any other \c attest_token_encode methods. \c
* QCBOREncode_Finish() should not be closed on this context.
*/
-QCBOREncodeContext *attest_token_borrow_cbor_cntxt(struct attest_token_ctx *me);
+QCBOREncodeContext *
+attest_token_encode_borrow_cbor_cntxt(struct attest_token_encode_ctx *me);
/**
* \brief Add a 64-bit signed integer claim
@@ -202,9 +203,9 @@
* \param[in] label Integer label for claim.
* \param[in] value The integer claim data.
*/
-void attest_token_add_integer(struct attest_token_ctx *me,
- int32_t label,
- int64_t value);
+void attest_token_encode_add_integer(struct attest_token_encode_ctx *me,
+ int32_t label,
+ int64_t value);
/**
* \brief Add a binary string claim
@@ -213,9 +214,9 @@
* \param[in] label Integer label for claim.
* \param[in] value The binary claim data.
*/
-void attest_token_add_bstr(struct attest_token_ctx *me,
- int32_t label,
- const struct q_useful_buf_c *value);
+void attest_token_encode_add_bstr(struct attest_token_encode_ctx *me,
+ int32_t label,
+ const struct q_useful_buf_c *value);
/**
* \brief Add a text string claim
@@ -224,9 +225,9 @@
* \param[in] label Integer label for claim.
* \param[in] value The text claim data.
*/
-void attest_token_add_tstr(struct attest_token_ctx *me,
- int32_t label,
- const struct q_useful_buf_c *value);
+void attest_token_encode_add_tstr(struct attest_token_encode_ctx *me,
+ int32_t label,
+ const struct q_useful_buf_c *value);
/**
* \brief Add some already-encoded CBOR to payload
@@ -239,9 +240,9 @@
* 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_add_encoded(struct attest_token_ctx *me,
- int32_t label,
- const struct q_useful_buf_c *encoded);
+void attest_token_encode_add_cbor(struct attest_token_encode_ctx *me,
+ int32_t label,
+ const struct q_useful_buf_c *encoded);
/**
@@ -257,8 +258,9 @@
* formatting of the token is completed.
*/
enum attest_token_err_t
-attest_token_finish(struct attest_token_ctx *me,
- struct q_useful_buf_c *completed_token);
+attest_token_encode_finish(struct attest_token_encode_ctx *me,
+ struct q_useful_buf_c *completed_token);
+
#ifdef __cplusplus
}
diff --git a/secure_fw/partitions/initial_attestation/attest_token.c b/secure_fw/partitions/initial_attestation/attest_token_encode.c
similarity index 82%
rename from secure_fw/partitions/initial_attestation/attest_token.c
rename to secure_fw/partitions/initial_attestation/attest_token_encode.c
index 31b8db5..84d0647 100644
--- a/secure_fw/partitions/initial_attestation/attest_token.c
+++ b/secure_fw/partitions/initial_attestation/attest_token_encode.c
@@ -1,5 +1,5 @@
/*
- * attest_token.c
+ * attest_token_encode.c
*
* Copyright (c) 2018-2019, Laurence Lundblade. All rights reserved.
* Copyright (c) 2020, Arm Limited.
@@ -24,18 +24,17 @@
/**
- * \file attest_token.c
+ * \file attest_token_encode.c
*
* \brief Attestation token creation implementation
*/
-/*
+/**
* \brief Map t_cose error to attestation token error.
*
* \param[in] err The t_cose error to map.
*
* \return the attestation token error.
- *
*/
static enum attest_token_err_t t_cose_err_to_attest_err(enum t_cose_err_t err)
{
@@ -72,7 +71,7 @@
* - Unprotected Headers
* - Key ID
* - Open payload bstr
- * - Write payload data… lots of it…
+ * - Write payload data, maybe lots of it
* - Get bstr that is the encoded payload
* - Compute tag
* - Create a separate encoder context for \c MAC_structure
@@ -93,11 +92,12 @@
/*
* Public function. See attest_token.h
*/
-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 q_useful_buf *out_buf)
+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_buf)
{
psa_key_handle_t key_handle = 0;
struct t_cose_key attest_key;
@@ -157,8 +157,8 @@
* Public function. See attest_token.h
*/
enum attest_token_err_t
-attest_token_finish(struct attest_token_ctx *me,
- struct q_useful_buf_c *completed_token)
+attest_token_encode_finish(struct attest_token_encode_ctx *me,
+ struct q_useful_buf_c *completed_token)
{
enum attest_token_err_t return_value = ATTEST_TOKEN_ERR_SUCCESS;
/* The completed and tagged encoded COSE_Mac0 */
@@ -206,7 +206,7 @@
* - Unprotected Headers
* - Key ID
* - Open payload bstr
- * - Write payload data lots of it
+ * - Write payload data, maybe lots of it
* - Get bstr that is the encoded payload
* - Compute signature
* - Create a separate encoder context for \c Sig_structure
@@ -224,13 +224,14 @@
*/
/*
- Public function. See attest_token.h
+ * Public function. See attest_token.h
*/
-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 q_useful_buf *out_buf)
+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_buf)
{
enum t_cose_err_t cose_ret;
enum attest_token_err_t return_value = ATTEST_TOKEN_ERR_SUCCESS;
@@ -287,11 +288,11 @@
}
/*
- Public function. See attest_token.h
+ * Public function. See attest_token.h
*/
enum attest_token_err_t
-attest_token_finish(struct attest_token_ctx *me,
- struct q_useful_buf_c *completed_token)
+attest_token_encode_finish(struct attest_token_encode_ctx *me,
+ struct q_useful_buf_c *completed_token)
{
enum attest_token_err_t return_value = ATTEST_TOKEN_ERR_SUCCESS;
/* The completed and signed encoded cose_sign1 */
@@ -329,31 +330,32 @@
#endif /* SYMMETRIC_INITIAL_ATTESTATION */
/*
- Public function. See attest_token.h
+ * Public function. See attest_token.h
*/
-QCBOREncodeContext *attest_token_borrow_cbor_cntxt(struct attest_token_ctx *me)
+QCBOREncodeContext *
+attest_token_encode_borrow_cbor_cntxt(struct attest_token_encode_ctx *me)
{
return &(me->cbor_enc_ctx);
}
/*
- Public function. See attest_token.h
+ * Public function. See attest_token.h
*/
-void attest_token_add_integer(struct attest_token_ctx *me,
- int32_t label,
- int64_t Value)
+void attest_token_encode_add_integer(struct attest_token_encode_ctx *me,
+ int32_t label,
+ int64_t Value)
{
QCBOREncode_AddInt64ToMapN(&(me->cbor_enc_ctx), label, Value);
}
/*
- Public function. See attest_token.h
+ * Public function. See attest_token.h
*/
-void attest_token_add_bstr(struct attest_token_ctx *me,
- int32_t label,
- const struct q_useful_buf_c *bstr)
+void attest_token_encode_add_bstr(struct attest_token_encode_ctx *me,
+ int32_t label,
+ const struct q_useful_buf_c *bstr)
{
QCBOREncode_AddBytesToMapN(&(me->cbor_enc_ctx),
label,
@@ -362,22 +364,22 @@
/*
- Public function. See attest_token.h
+ * Public function. See attest_token.h
*/
-void attest_token_add_tstr(struct attest_token_ctx *me,
- int32_t label,
- const struct q_useful_buf_c *tstr)
+void attest_token_encode_add_tstr(struct attest_token_encode_ctx *me,
+ int32_t label,
+ const struct q_useful_buf_c *tstr)
{
QCBOREncode_AddTextToMapN(&(me->cbor_enc_ctx), label, *tstr);
}
/*
- See attest_token.h
+ * Public function. See attest_token.h
*/
-void attest_token_add_encoded(struct attest_token_ctx *me,
- int32_t label,
- const struct q_useful_buf_c *encoded)
+void attest_token_encode_add_encoded(struct attest_token_encode_ctx *me,
+ int32_t label,
+ const struct q_useful_buf_c *encoded)
{
QCBOREncode_AddEncodedToMapN(&(me->cbor_enc_ctx), label, *encoded);
}
diff --git a/secure_fw/partitions/initial_attestation/attestation_core.c b/secure_fw/partitions/initial_attestation/attestation_core.c
index e0df017..641b35e 100644
--- a/secure_fw/partitions/initial_attestation/attestation_core.c
+++ b/secure_fw/partitions/initial_attestation/attestation_core.c
@@ -290,7 +290,7 @@
* \return Returns error code as specified in \ref psa_attest_err_t
*/
static enum psa_attest_err_t
-attest_add_all_sw_components(struct attest_token_ctx *token_ctx)
+attest_add_all_sw_components(struct attest_token_encode_ctx *token_ctx)
{
uint16_t tlv_len;
uint8_t *tlv_ptr;
@@ -301,7 +301,7 @@
QCBOREncodeContext *cbor_encode_ctx = NULL;
UsefulBufC encoded = NULLUsefulBufC;
- cbor_encode_ctx = attest_token_borrow_cbor_cntxt(token_ctx);
+ cbor_encode_ctx = attest_token_encode_borrow_cbor_cntxt(token_ctx);
/* Starting from module 1, because module 0 contains general claims which
* are not related to SW module(i.e: boot_seed, etc.)
@@ -354,9 +354,9 @@
/* If there is not any SW components' measurement in the boot status
* then include this claim to indicate that this state is intentional
*/
- attest_token_add_integer(token_ctx,
- EAT_CBOR_ARM_LABEL_NO_SW_COMPONENTS,
- (int64_t)NO_SW_COMPONENT_FIXED_VALUE);
+ attest_token_encode_add_integer(token_ctx,
+ EAT_CBOR_ARM_LABEL_NO_SW_COMPONENTS,
+ (int64_t)NO_SW_COMPONENT_FIXED_VALUE);
}
return PSA_ATTEST_ERR_SUCCESS;
@@ -370,7 +370,7 @@
* \return Returns error code as specified in \ref psa_attest_err_t
*/
static enum psa_attest_err_t
-attest_add_boot_seed_claim(struct attest_token_ctx *token_ctx)
+attest_add_boot_seed_claim(struct attest_token_encode_ctx *token_ctx)
{
uint8_t boot_seed[BOOT_SEED_SIZE];
enum tfm_plat_err_t res;
@@ -399,9 +399,9 @@
claim_value.len = BOOT_SEED_SIZE;
}
- attest_token_add_bstr(token_ctx,
- EAT_CBOR_ARM_LABEL_BOOT_SEED,
- &claim_value);
+ attest_token_encode_add_bstr(token_ctx,
+ EAT_CBOR_ARM_LABEL_BOOT_SEED,
+ &claim_value);
return PSA_ATTEST_ERR_SUCCESS;
}
@@ -417,7 +417,7 @@
* \return Returns error code as specified in \ref psa_attest_err_t
*/
static enum psa_attest_err_t
-attest_add_instance_id_claim(struct attest_token_ctx *token_ctx)
+attest_add_instance_id_claim(struct attest_token_encode_ctx *token_ctx)
{
struct q_useful_buf_c claim_value;
enum psa_attest_err_t err;
@@ -428,9 +428,9 @@
return err;
}
- attest_token_add_bstr(token_ctx,
- EAT_CBOR_ARM_LABEL_UEID,
- &claim_value);
+ attest_token_encode_add_bstr(token_ctx,
+ EAT_CBOR_ARM_LABEL_UEID,
+ &claim_value);
return PSA_ATTEST_ERR_SUCCESS;
}
@@ -443,7 +443,7 @@
* \return Returns error code as specified in \ref psa_attest_err_t
*/
static enum psa_attest_err_t
-attest_add_implementation_id_claim(struct attest_token_ctx *token_ctx)
+attest_add_implementation_id_claim(struct attest_token_encode_ctx *token_ctx)
{
uint8_t implementation_id[IMPLEMENTATION_ID_MAX_SIZE];
enum tfm_plat_err_t res_plat;
@@ -457,9 +457,9 @@
claim_value.ptr = implementation_id;
claim_value.len = size;
- attest_token_add_bstr(token_ctx,
- EAT_CBOR_ARM_LABEL_IMPLEMENTATION_ID,
- &claim_value);
+ attest_token_encode_add_bstr(token_ctx,
+ EAT_CBOR_ARM_LABEL_IMPLEMENTATION_ID,
+ &claim_value);
return PSA_ATTEST_ERR_SUCCESS;
}
@@ -472,7 +472,7 @@
* \return Returns error code as specified in \ref psa_attest_err_t
*/
static enum psa_attest_err_t
-attest_add_caller_id_claim(struct attest_token_ctx *token_ctx)
+attest_add_caller_id_claim(struct attest_token_encode_ctx *token_ctx)
{
enum psa_attest_err_t res;
int32_t caller_id;
@@ -482,9 +482,9 @@
return res;
}
- attest_token_add_integer(token_ctx,
- EAT_CBOR_ARM_LABEL_CLIENT_ID,
- (int64_t)caller_id);
+ attest_token_encode_add_integer(token_ctx,
+ EAT_CBOR_ARM_LABEL_CLIENT_ID,
+ (int64_t)caller_id);
return PSA_ATTEST_ERR_SUCCESS;
}
@@ -497,7 +497,7 @@
* \return Returns error code as specified in \ref psa_attest_err_t
*/
static enum psa_attest_err_t
-attest_add_security_lifecycle_claim(struct attest_token_ctx *token_ctx)
+attest_add_security_lifecycle_claim(struct attest_token_encode_ctx *token_ctx)
{
enum tfm_security_lifecycle_t security_lifecycle;
uint32_t slc_value;
@@ -534,9 +534,9 @@
return PSA_ATTEST_ERR_GENERAL;
}
- attest_token_add_integer(token_ctx,
- EAT_CBOR_ARM_LABEL_SECURITY_LIFECYCLE,
- (int64_t)security_lifecycle);
+ attest_token_encode_add_integer(token_ctx,
+ EAT_CBOR_ARM_LABEL_SECURITY_LIFECYCLE,
+ (int64_t)security_lifecycle);
return PSA_ATTEST_ERR_SUCCESS;
}
@@ -550,10 +550,12 @@
* \return Returns error code as specified in \ref psa_attest_err_t
*/
static enum psa_attest_err_t
-attest_add_challenge_claim(struct attest_token_ctx *token_ctx,
- const struct q_useful_buf_c *challenge)
+attest_add_challenge_claim(struct attest_token_encode_ctx *token_ctx,
+ const struct q_useful_buf_c *challenge)
{
- attest_token_add_bstr(token_ctx, EAT_CBOR_ARM_LABEL_CHALLENGE, challenge);
+ attest_token_encode_add_bstr(token_ctx,
+ EAT_CBOR_ARM_LABEL_CHALLENGE,
+ challenge);
return PSA_ATTEST_ERR_SUCCESS;
}
@@ -568,7 +570,7 @@
* \return Returns error code as specified in \ref psa_attest_err_t
*/
static enum psa_attest_err_t
-attest_add_verification_service(struct attest_token_ctx *token_ctx)
+attest_add_verification_service(struct attest_token_encode_ctx *token_ctx)
{
struct q_useful_buf_c service;
uint32_t size;
@@ -577,9 +579,9 @@
if (service.ptr) {
service.len = size;
- attest_token_add_tstr(token_ctx,
- EAT_CBOR_ARM_LABEL_ORIGINATION,
- &service);
+ attest_token_encode_add_tstr(token_ctx,
+ EAT_CBOR_ARM_LABEL_ORIGINATION,
+ &service);
}
return PSA_ATTEST_ERR_SUCCESS;
@@ -593,7 +595,7 @@
* \return Returns error code as specified in \ref psa_attest_err_t
*/
static enum psa_attest_err_t
-attest_add_profile_definition(struct attest_token_ctx *token_ctx)
+attest_add_profile_definition(struct attest_token_encode_ctx *token_ctx)
{
struct q_useful_buf_c profile;
uint32_t size;
@@ -602,9 +604,9 @@
if (profile.ptr) {
profile.len = size;
- attest_token_add_tstr(token_ctx,
- EAT_CBOR_ARM_LABEL_PROFILE_DEFINITION,
- &profile);
+ attest_token_encode_add_tstr(token_ctx,
+ EAT_CBOR_ARM_LABEL_PROFILE_DEFINITION,
+ &profile);
}
return PSA_ATTEST_ERR_SUCCESS;
@@ -618,7 +620,7 @@
* \return Returns error code as specified in \ref psa_attest_err_t
*/
static enum psa_attest_err_t
-attest_add_hw_version_claim(struct attest_token_ctx *token_ctx)
+attest_add_hw_version_claim(struct attest_token_encode_ctx *token_ctx)
{
uint8_t hw_version[HW_VERSION_MAX_SIZE];
enum tfm_plat_err_t res_plat;
@@ -650,9 +652,9 @@
claim_value.len = size;
}
- attest_token_add_tstr(token_ctx,
- EAT_CBOR_ARM_LABEL_HW_VERSION,
- &claim_value);
+ attest_token_encode_add_tstr(token_ctx,
+ EAT_CBOR_ARM_LABEL_HW_VERSION,
+ &claim_value);
return PSA_ATTEST_ERR_SUCCESS;
}
@@ -754,7 +756,7 @@
{
enum psa_attest_err_t attest_err = PSA_ATTEST_ERR_SUCCESS;
enum attest_token_err_t token_err;
- struct attest_token_ctx attest_token_ctx;
+ struct attest_token_encode_ctx attest_token_ctx;
int32_t key_select = 0;
uint32_t option_flags = 0;
@@ -770,11 +772,11 @@
/* Get started creating the token. This sets up the CBOR and COSE contexts
* which causes the COSE headers to be constructed.
*/
- token_err = attest_token_start(&attest_token_ctx,
- option_flags, /* option_flags */
- key_select, /* key_select */
- T_COSE_ALGORITHM, /* alg_select */
- token);
+ token_err = attest_token_encode_start(&attest_token_ctx,
+ option_flags, /* option_flags */
+ key_select, /* key_select */
+ T_COSE_ALGORITHM, /* alg_select */
+ token);
if (token_err != ATTEST_TOKEN_ERR_SUCCESS) {
attest_err = error_mapping_to_psa_attest_err_t(token_err);
@@ -841,7 +843,7 @@
/* Finish up creating the token. This is where the actual signature
* is generated. This finishes up the CBOR encoding too.
*/
- token_err = attest_token_finish(&attest_token_ctx, completed_token);
+ token_err = attest_token_encode_finish(&attest_token_ctx, completed_token);
if (token_err) {
attest_err = error_mapping_to_psa_attest_err_t(token_err);
goto error;