From 1216f81621e24d1672b47c2c277195562c9e3917 Mon Sep 17 00:00:00 2001 From: Laurence Lundblade Date: Wed, 6 Sep 2023 17:40:06 -0700 Subject: [PATCH] documentation and terminology --- inc/t_cose/t_cose_common.h | 8 +- inc/t_cose/t_cose_encrypt_dec.h | 19 +- inc/t_cose/t_cose_encrypt_enc.h | 26 +- inc/t_cose/t_cose_mac_compute.h | 24 +- inc/t_cose/t_cose_mac_validate.h | 19 +- inc/t_cose/t_cose_sign1_sign.h | 65 +++-- inc/t_cose/t_cose_sign1_verify.h | 32 +-- inc/t_cose/t_cose_sign_sign.h | 300 +++++++++++---------- inc/t_cose/t_cose_sign_verify.h | 19 +- inc/t_cose/t_cose_signature_sign.h | 4 +- inc/t_cose/t_cose_signature_sign_eddsa.h | 2 +- inc/t_cose/t_cose_signature_verify.h | 2 +- inc/t_cose/t_cose_signature_verify_eddsa.h | 2 +- src/t_cose_encrypt_dec.c | 4 +- src/t_cose_encrypt_enc.c | 4 +- src/t_cose_mac_compute.c | 2 +- src/t_cose_mac_validate.c | 2 +- src/t_cose_sign_sign.c | 90 +++---- src/t_cose_sign_verify.c | 4 +- src/t_cose_util.c | 8 +- test/t_cose_make_test_messages.c | 2 +- 21 files changed, 330 insertions(+), 308 deletions(-) diff --git a/inc/t_cose/t_cose_common.h b/inc/t_cose/t_cose_common.h index de37da77..6f451995 100644 --- a/inc/t_cose/t_cose_common.h +++ b/inc/t_cose/t_cose_common.h @@ -9,7 +9,6 @@ * See BSD-3-Clause license in README.md */ - #ifndef __T_COSE_COMMON_H__ #define __T_COSE_COMMON_H__ @@ -285,6 +284,7 @@ enum t_cose_key_usage_flags { * 50-plus lines to figure out the actual value. */ // TODO: renumber grouping unsupported algorithm errors together +// TODO: review the buffer-too-small errors; are there too many of them? enum t_cose_err_t { /** Operation completed successfully. */ T_COSE_SUCCESS = 0, @@ -774,7 +774,7 @@ enum t_cose_err_t { /* Default size allowed for Enc_structure for COSE_Encrypt and COSE_Encrypt0. - * If there are a lot or header parameters or AAD passed in is large, + * If there are a lot or header parameters or the externally supplied data (Section 4.3, RFC 9052) passed in is large, * this may not be big enough and error TODO will be returned. Call * TODO to give a bigger buffer.*/ #define T_COSE_ENCRYPT_STRUCT_DEFAULT_SIZE 64 @@ -815,7 +815,7 @@ t_cose_is_algorithm_supported(int32_t cose_algorithm_id); * These are the inputs to create a Sig_structure * from section 4.4 in RFC 9052. * - * aad and sign_protected may be \ref NULL_Q_USEFUL_BUF_C. + * ext_sup_data and sign_protected may be \ref NULL_Q_USEFUL_BUF_C. * * payload is a CBOR encoded byte string that may * contain CBOR or other. @@ -825,7 +825,7 @@ t_cose_is_algorithm_supported(int32_t cose_algorithm_id); */ struct t_cose_sign_inputs { struct q_useful_buf_c body_protected; - struct q_useful_buf_c aad; + struct q_useful_buf_c ext_sup_data; struct q_useful_buf_c sign_protected; struct q_useful_buf_c payload; }; diff --git a/inc/t_cose/t_cose_encrypt_dec.h b/inc/t_cose/t_cose_encrypt_dec.h index ba583def..c666ac78 100644 --- a/inc/t_cose/t_cose_encrypt_dec.h +++ b/inc/t_cose/t_cose_encrypt_dec.h @@ -220,19 +220,19 @@ t_cose_encrypt_add_param_storage(struct t_cose_encrypt_dec_ctx *context, // TODO: Add equivalent of t_cose_signature_verify_main_set_special_param_decoder() /** - * \brief Setup buffer for larger AAD or header parameters. + * \brief Setup buffer for larger externally supplied data or header parameters. * * \param[in] context The encryption context * \param[in] enc_buffer Pointer and length of buffer to add. * * By default there is a limit of T_COSE_ENCRYPT_STRUCT_DEFAULT_SIZE - * (typically 64 bytes) for the AAD and protected header + * (typically 64 bytes) for the externally supplied data and protected header * parameters. Normally this is quite adequate, but it may not be in * all cases. If not call this with a larger buffer. * * Specifically, this is the buffer to create the Enc_structure * described in RFC 9052 section 5.2. It needs to be the size of the - * CBOR-encoded protected headers, the AAD and some overhead. + * CBOR-encoded protected headers, the externally supplied data and some overhead. * * TODO: size calculation mode that will tell the caller how bit it should be */ @@ -246,8 +246,7 @@ t_cose_decrypt_set_enc_struct_buffer(struct t_cose_encrypt_dec_ctx *context, * \param[in,out] context The t_cose_encrypt_dec_ctx context. * \param[in] message The COSE message (a COSE_Encrypt0 * or COSE_Encrypt). - * \param[in] aad Additional data that is verified or - * \ref NULL_Q_USEFUL_BUF if none. + * \param[in] ext_sup_data Externally supplied data or \ref NULL_Q_USEFUL_BUF. * \param[in] plaintext_buffer A buffer for plaintext. * \param[out] plaintext Place to return pointer and length of * the plaintext. @@ -279,7 +278,7 @@ t_cose_decrypt_set_enc_struct_buffer(struct t_cose_encrypt_dec_ctx *context, static enum t_cose_err_t t_cose_encrypt_dec(struct t_cose_encrypt_dec_ctx *context, struct q_useful_buf_c message, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf plaintext_buffer, struct q_useful_buf_c *plaintext, struct t_cose_parameter **returned_parameters); @@ -291,7 +290,7 @@ t_cose_encrypt_dec(struct t_cose_encrypt_dec_ctx *context, * \param[in,out] context The t_cose_encrypt_dec_ctx context. * \param[in] message The COSE message (a COSE_Encrypt0 * or COSE_Encrypt). - * \param[in] aad Additional data that is verified or \ref NULL_Q_USEFUL_BUF if none. + * \param[in] ext_sup_data Externally supplied data or \ref NULL_Q_USEFUL_BUF. * \param[in] detached_ciphertext The detached ciphertext. * \param[in] plaintext_buffer A buffer for plaintext. * \param[out] plaintext Place to return pointer and length of the plaintext. @@ -306,7 +305,7 @@ t_cose_encrypt_dec(struct t_cose_encrypt_dec_ctx *context, enum t_cose_err_t t_cose_encrypt_dec_detached(struct t_cose_encrypt_dec_ctx *context, struct q_useful_buf_c message, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c detached_ciphertext, struct q_useful_buf plaintext_buffer, struct q_useful_buf_c *plaintext, @@ -389,14 +388,14 @@ t_cose_decrypt_set_enc_struct_buffer(struct t_cose_encrypt_dec_ctx *context, static inline enum t_cose_err_t t_cose_encrypt_dec(struct t_cose_encrypt_dec_ctx *me, struct q_useful_buf_c message, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf plaintext_buffer, struct q_useful_buf_c *plaintext, struct t_cose_parameter **returned_parameters) { return t_cose_encrypt_dec_detached(me, message, - aad, + ext_sup_data, NULL_Q_USEFUL_BUF_C, plaintext_buffer, plaintext, diff --git a/inc/t_cose/t_cose_encrypt_enc.h b/inc/t_cose/t_cose_encrypt_enc.h index b58a61d4..b500f115 100644 --- a/inc/t_cose/t_cose_encrypt_enc.h +++ b/inc/t_cose/t_cose_encrypt_enc.h @@ -288,19 +288,19 @@ t_cose_encrypt_set_cek(struct t_cose_encrypt_enc *context, /** - * \brief Setup buffer for larger AAD or header parameters. + * \brief Setup buffer for larger externally supplied data or header parameters. * * \param[in] context The encryption context * \param[in] enc_buffer Pointer and length of buffer to add. * * By default there is a limit of T_COSE_ENCRYPT_STRUCT_DEFAULT_SIZE - * (typically 64 bytes) for the AAD and protected header + * (typically 64 bytes) for the externally supplied data and protected header * parameters. Normally this is quite adequate, but it may not be in * all cases. If not call this with a larger buffer. * * Specifically, this is the buffer to create the Enc_structure * described in RFC 9052 section 5.2. It needs to be the size of the - * CBOR-encoded protected headers, the AAD and some overhead. + * CBOR-encoded protected headers, the externally supplied data and some overhead. * * TODO: size calculation mode that will tell the caller how bit it should be */ @@ -315,7 +315,7 @@ t_cose_encrypt_set_enc_struct_buffer(struct t_cose_encrypt_enc *context, * * \param[in] context The t_cose_encrypt_enc_ctx context. * \param[in] payload Plaintext to be encypted. - * \param[in] aad Additional authenticated data or \ref NULL_Q_USEFUL_BUF if none. + * \param[in] ext_sup_data External supplied data or \ref NULL_Q_USEFUL_BUF. * \param[in] buffer_for_message Buffer for COSE message. * \param[out] encrypted_message Completed COSE message. * @@ -327,7 +327,13 @@ t_cose_encrypt_set_enc_struct_buffer(struct t_cose_encrypt_enc *context, * COSE_Recipients. Only when direct encryption is used are they not * called. * - * The size of encoded protected parameters plus the aad is limited to + * \c ext_sup_data is additional data to be integrity protected by the AEAD + * algorthim. This the data described in section 4.3 of RFC 9052. Note that this + * data (nor the payload) is authenticated in the same way it is when signed. + * TODO: sort out what happens with no AEAD + * TODO: describe this all better. + * + * The size of encoded protected parameters plus the externally supplied data is limited to * TODO by default. If it is exceeded the error TODO: will be * returned. See TODO to increase this. * @@ -343,7 +349,7 @@ t_cose_encrypt_set_enc_struct_buffer(struct t_cose_encrypt_enc *context, static enum t_cose_err_t t_cose_encrypt_enc(struct t_cose_encrypt_enc *context, struct q_useful_buf_c payload, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf buffer_for_message, struct q_useful_buf_c *encrypted_message); @@ -354,7 +360,7 @@ t_cose_encrypt_enc(struct t_cose_encrypt_enc *context, * * \param[in] context The t_cose_encrypt_enc_ctx context. * \param[in] payload Plaintext to be encypted. - * \param[in] aad Additional authenticated data or \ref NULL_Q_USEFUL_BUF if none. + * \param[in] ext_sup_data External supplimentary data or \ref NULL_Q_USEFUL_BUF. * \param[in] buffer_for_detached Buffer for detached cipher text. * \param[in] buffer_for_message Buffer for COSE message. * \param[out] encrypted_detached Detached ciphertext. @@ -379,7 +385,7 @@ t_cose_encrypt_enc(struct t_cose_encrypt_enc *context, enum t_cose_err_t t_cose_encrypt_enc_detached(struct t_cose_encrypt_enc *context, struct q_useful_buf_c payload, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf buffer_for_detached, struct q_useful_buf buffer_for_message, struct q_useful_buf_c *encrypted_detached, @@ -440,13 +446,13 @@ t_cose_encrypt_set_enc_struct_buffer(struct t_cose_encrypt_enc *context, static inline enum t_cose_err_t t_cose_encrypt_enc(struct t_cose_encrypt_enc *context, struct q_useful_buf_c payload, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf buffer_for_message, struct q_useful_buf_c *encrypted_cose_message) { return t_cose_encrypt_enc_detached(context, payload, - aad, + ext_sup_data, NULL_Q_USEFUL_BUF, buffer_for_message, NULL, diff --git a/inc/t_cose/t_cose_mac_compute.h b/inc/t_cose/t_cose_mac_compute.h index 80902e66..e1db31a3 100644 --- a/inc/t_cose/t_cose_mac_compute.h +++ b/inc/t_cose/t_cose_mac_compute.h @@ -171,8 +171,7 @@ t_cose_mac_encode_tag(struct t_cose_mac_calculate_ctx *context, * \brief Create and compute a \c COSE_Mac0 message with a payload in one call. * * \param[in] context The t_cose MAC context. - * \param[in] aad The Additional Authenticated Data or - * \c NULL_Q_USEFUL_BUF_C. + * \param[in] ext_sup_data Externally supplied data or \c NULL_Q_USEFUL_BUF_C. * \param[in] payload Pointer and length of payload to be MACed. * \param[in] out_buf Pointer and length of buffer to output to. * \param[out] result Pointer and length of the resulting \c COSE_Mac0. @@ -215,7 +214,7 @@ t_cose_mac_encode_tag(struct t_cose_mac_calculate_ctx *context, */ static enum t_cose_err_t t_cose_mac_compute(struct t_cose_mac_calculate_ctx *context, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c payload, struct q_useful_buf out_buf, struct q_useful_buf_c *result); @@ -226,7 +225,7 @@ t_cose_mac_compute(struct t_cose_mac_calculate_ctx *context, * payload in one call. * * \param[in] context The t_cose MAC context. - * \param[in] aad The Additional Authenticated Data or + * \param[in] ext_sup_data Externally supplied data or * \c NULL_Q_USEFUL_BUF_C. * \param[in] datached_payload Pointer and length of the detached payload * to be MACed. @@ -244,7 +243,7 @@ t_cose_mac_compute(struct t_cose_mac_calculate_ctx *context, */ static enum t_cose_err_t t_cose_mac_compute_detached(struct t_cose_mac_calculate_ctx *context, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c datached_payload, struct q_useful_buf out_buf, struct q_useful_buf_c *result); @@ -262,8 +261,7 @@ t_cose_mac_compute_detached(struct t_cose_mac_calculate_ctx *context, * * \param[in] context The t_cose MAC context. * \param[in] payload_is_detached If \c true, then \c payload is detached. - * \param[in] aad The Additional Authenticated Data or - * \c NULL_Q_USEFUL_BUF_C. + * \param[in] ext_sup_data Externally supplied data or \c NULL_Q_USEFUL_BUF_C. * \param[in] payload The payload to be MACed, inline or detached. * \param[in] out_buf Pointer and length of buffer to output to. * \param[out] result Pointer and length of the resulting @@ -272,7 +270,7 @@ t_cose_mac_compute_detached(struct t_cose_mac_calculate_ctx *context, * \return This returns one of the error codes defined by \ref t_cose_err_t. * * This is where the work actually gets done for computing MAC that is done - * all in one call with or without AAD and for included or detached payloads. + * all in one call with or without externally supplied data and for included or detached payloads. * * This is a private function internal to the implementation. Call * t_cose_mac_compute() or t_cose_mac_compute_detached() instead of this. @@ -280,7 +278,7 @@ t_cose_mac_compute_detached(struct t_cose_mac_calculate_ctx *context, enum t_cose_err_t t_cose_mac_compute_private(struct t_cose_mac_calculate_ctx *context, bool payload_is_detached, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c payload, struct q_useful_buf out_buf, struct q_useful_buf_c *result); @@ -317,14 +315,14 @@ t_cose_mac_add_body_header_params(struct t_cose_mac_calculate_ctx *me, static inline enum t_cose_err_t t_cose_mac_compute(struct t_cose_mac_calculate_ctx *me, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c payload, struct q_useful_buf out_buf, struct q_useful_buf_c *result) { return t_cose_mac_compute_private(me, false, - aad, + ext_sup_data, payload, out_buf, result); @@ -333,12 +331,12 @@ t_cose_mac_compute(struct t_cose_mac_calculate_ctx *me, static inline enum t_cose_err_t t_cose_mac_compute_detached(struct t_cose_mac_calculate_ctx *me, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c detached_payload, struct q_useful_buf out_buf, struct q_useful_buf_c *result) { - (void)aad; + (void)ext_sup_data; return t_cose_mac_compute_private(me, true, NULL_Q_USEFUL_BUF_C, diff --git a/inc/t_cose/t_cose_mac_validate.h b/inc/t_cose/t_cose_mac_validate.h index dcd58963..5997bf66 100644 --- a/inc/t_cose/t_cose_mac_validate.h +++ b/inc/t_cose/t_cose_mac_validate.h @@ -75,8 +75,7 @@ t_cose_mac_set_validate_key(struct t_cose_mac_validate_ctx *context, * \param[in] context The context of COSE_Mac0 validation. * \param[in] cose_mac Pointer and length of CBOR encoded \c COSE_Mac0 * that is to be validated. - * \param[in] aad The Additional Authenticated Data or - * \c NULL_Q_USEFUL_BUF_C. + * \param[in] ext_sup_data Externally supplied data or \c NULL_Q_USEFUL_BUF_C. * \param[out] payload Pointer and length of the still * CBOR encoded payload. * \param[out] return_params Place to return decoded parameters. @@ -109,7 +108,7 @@ t_cose_mac_set_validate_key(struct t_cose_mac_validate_ctx *context, static enum t_cose_err_t t_cose_mac_validate(struct t_cose_mac_validate_ctx *context, struct q_useful_buf_c cose_mac, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c *payload, struct t_cose_parameter **return_params); @@ -120,7 +119,7 @@ t_cose_mac_validate(struct t_cose_mac_validate_ctx *context, static enum t_cose_err_t t_cose_mac_validate_detached(struct t_cose_mac_validate_ctx *context, struct q_useful_buf_c cose_mac, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c detached_payload, struct t_cose_parameter **return_params); @@ -160,7 +159,7 @@ t_cose_mac_validate_nth_tag(const struct t_cose_mac_validate_ctx *context, * \param[in] context The context of COSE_Mac0 validation. * \param[in] cose_mac Pointer and length of CBOR encoded \c COSE_Mac0 * that is to be validated. - * \param[in] aad The Additional Authenticated Data or + * \param[in] ext_sup_data The Additional Authenticated Data or * \c NULL_Q_USEFUL_BUF_C. * \param[in] payload_is_detached If \c true, indicates the \c payload * is detached. @@ -178,7 +177,7 @@ t_cose_mac_validate_nth_tag(const struct t_cose_mac_validate_ctx *context, enum t_cose_err_t t_cose_mac_validate_private(struct t_cose_mac_validate_ctx *context, struct q_useful_buf_c cose_mac, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, bool payload_is_detached, struct q_useful_buf_c *payload, struct t_cose_parameter **return_params); @@ -205,13 +204,13 @@ t_cose_mac_set_validate_key(struct t_cose_mac_validate_ctx *me, static inline enum t_cose_err_t t_cose_mac_validate(struct t_cose_mac_validate_ctx *me, struct q_useful_buf_c cose_mac, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c *payload, struct t_cose_parameter **return_params) { return t_cose_mac_validate_private(me, cose_mac, - aad, + ext_sup_data, false, payload, return_params); @@ -221,13 +220,13 @@ t_cose_mac_validate(struct t_cose_mac_validate_ctx *me, static inline enum t_cose_err_t t_cose_mac_validate_detached(struct t_cose_mac_validate_ctx *me, struct q_useful_buf_c cose_mac, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c detached_payload, struct t_cose_parameter **return_params) { return t_cose_mac_validate_private(me, cose_mac, - aad, + ext_sup_data, true, &detached_payload, return_params); diff --git a/inc/t_cose/t_cose_sign1_sign.h b/inc/t_cose/t_cose_sign1_sign.h index 04a64c05..473f33a1 100644 --- a/inc/t_cose/t_cose_sign1_sign.h +++ b/inc/t_cose/t_cose_sign1_sign.h @@ -210,7 +210,7 @@ t_cose_sign1_set_content_type_tstr(struct t_cose_sign1_sign_ctx *context, * allows the user to configure such a buffer. * * The buffer must be big enough to accomodate the Sig_Structure type, - * which is roughly the sum of sizes of the encoded protected parameters, aad + * which is roughly the sum of sizes of the encoded protected parameters, externally supplied data * and payload, along with a few dozen bytes of overhead. * * To compute the exact size needed, an auxiliary buffer with a NULL @@ -308,24 +308,23 @@ t_cose_sign1_sign(struct t_cose_sign1_sign_ctx *context, * \brief Create and sign a \c COSE_Sign1 message with a payload in one call. * * \param[in] context The t_cose signing context. - * \param[in] aad The Additional Authenticated Data or \c NULL_Q_USEFUL_BUF_C. + * \param[in] ext_sup_data Externally supplied data or \c NULL_Q_USEFUL_BUF_C. * \param[in] payload Pointer and length of payload to sign. * \param[in] out_buf Pointer and length of buffer to output to. * \param[out] result Pointer and length of the resulting \c COSE_Sign1. * - * This is the same as t_cose_sign1_sign() additionally allowing AAD. - * AAD (Additional Authenticated Data) is extra bytes to be covered by the - * signature. See t_cose_sign1_encode_signature_aad() for more details - * about AAD. + * This is the same as t_cose_sign1_sign() additionally allowing externally supplied data. + * Externally supplied data (formerly "AAD") is extra bytes to be authenticated by the + * signature. See t_cose_sign1_encode_signature_aad() for more details. * - * Calling this with \c aad as \c NULL_Q_USEFUL_BUF_C is equivalent to + * Calling this with \c ext_sup_data as \c NULL_Q_USEFUL_BUF_C is equivalent to * t_cose_sign1_sign(). * * See also t_cose_sign1_sign_detached(). */ static enum t_cose_err_t t_cose_sign1_sign_aad(struct t_cose_sign1_sign_ctx *context, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c payload, struct q_useful_buf out_buf, struct q_useful_buf_c *result); @@ -335,7 +334,7 @@ t_cose_sign1_sign_aad(struct t_cose_sign1_sign_ctx *context, * \brief Create and sign a \c COSE_Sign1 message with detached payload in one call. * * \param[in] context The t_cose signing context. - * \param[in] aad The Additional Authenticated Data or \c NULL_Q_USEFUL_BUF_C. + * \param[in] ext_sup_data Externally supplied data or \c NULL_Q_USEFUL_BUF_C. * \param[in] detached_payload Pointer and length of the detached payload to sign. * \param[in] out_buf Pointer and length of buffer to output to. * \param[out] result Pointer and length of the resulting \c COSE_Sign1. @@ -348,12 +347,12 @@ t_cose_sign1_sign_aad(struct t_cose_sign1_sign_ctx *context, * \c COSE_Sign1. The recipient will be unable to verify the \c * COSE_Sign1 without it. * - * This may be called with \c aad as \c NULL_Q_USEFUL_BUF_C if there is - * no AAD. + * This may be called with \c ext_sup_data as \c NULL_Q_USEFUL_BUF_C if there is + * no externally supplied data. */ static enum t_cose_err_t t_cose_sign1_sign_detached(struct t_cose_sign1_sign_ctx *context, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c detached_payload, struct q_useful_buf out_buf, struct q_useful_buf_c *result); @@ -422,27 +421,27 @@ t_cose_sign1_encode_signature(struct t_cose_sign1_sign_ctx *context, /** - * \brief Finish a \c COSE_Sign1 message with AAD by outputting the signature. + * \brief Finish a \c COSE_Sign1 message with externally supplied data by outputting the signature. * * \param[in] context The t_cose signing context. - * \param[in] aad The Additional Authenticated Data. + * \param[in] ext_sup_data Externally supplied data. * \param[in] cbor_encode_ctx Encoding context to output to. * * \return This returns one of the error codes defined by \ref t_cose_err_t. * * This is the same as t_cose_sign1_encode_signature() and it allows - * passing in AAD (Additional Authenticated Data) to be covered by the + * passing in externally supplied data (formerly "AAD") to be covered by the * signature. * - * AAD is simply any data that should also be covered by the - * signature. The verifier of the \c COSE_Sign1 must also have exactly + * Externally supplied data is simply any data that should also be covered by the + * signature. It is describe in RFC 9052, section 4.3. The verifier of the \c COSE_Sign1 must also have exactly * this data to be able to successfully verify the signature. Often * this data is some parameters or fields in the protocol carrying the * COSE message. */ static inline enum t_cose_err_t t_cose_sign1_encode_signature_aad(struct t_cose_sign1_sign_ctx *context, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, QCBOREncodeContext *cbor_encode_ctx); @@ -491,7 +490,7 @@ t_cose_sign1_encode_parameters(struct t_cose_sign1_sign_ctx *context, * \c COSE_Sign1 message. * * \param[in] context The t_cose signing context. - * \param[in] aad The Additional Authenticated Data or + * \param[in] ext_sup_data Externally supplied data or * \c NULL_Q_USEFUL_BUF_C. * \param[in] detached_payload The detached payload or \c NULL_Q_USEFUL_BUF_C. * \param[in] cbor_encode_ctx Encoding context to output to. @@ -508,7 +507,7 @@ t_cose_sign1_encode_parameters(struct t_cose_sign1_sign_ctx *context, */ static enum t_cose_err_t t_cose_sign1_encode_signature_aad_private(struct t_cose_sign1_sign_ctx *context, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c detached_payload, QCBOREncodeContext *cbor_encode_ctx); @@ -518,7 +517,7 @@ t_cose_sign1_encode_signature_aad_private(struct t_cose_sign1_sign_ctx *context, * \param[in] context The t_cose signing context. * \param[in] payload_is_detached If \c true, then \c payload is detached. * \param[in] payload The payload, inline or detached. - * \param[in] aad The Additional Authenticated Data or + * \param[in] ext_sup_data Externally supplied data or * \c NULL_Q_USEFUL_BUF_C. * \param[in] out_buf Pointer and length of buffer to output to. * \param[out] result Pointer and length of the resulting @@ -527,7 +526,7 @@ t_cose_sign1_encode_signature_aad_private(struct t_cose_sign1_sign_ctx *context, * \return This returns one of the error codes defined by \ref t_cose_err_t. * * This is where the work actually gets done for signing that is done - * all in one call with or without AAD and for included or detached + * all in one call with or without externally supplied data and for included or detached * payloads. * * This is a private function internal to the implementation. Call @@ -536,7 +535,7 @@ t_cose_sign1_encode_signature_aad_private(struct t_cose_sign1_sign_ctx *context, static enum t_cose_err_t t_cose_sign1_sign_aad_private(struct t_cose_sign1_sign_ctx *context, bool payload_is_detached, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c payload, struct q_useful_buf out_buf, struct q_useful_buf_c *result); @@ -544,14 +543,14 @@ t_cose_sign1_sign_aad_private(struct t_cose_sign1_sign_ctx *context, static inline enum t_cose_err_t t_cose_sign1_sign_aad(struct t_cose_sign1_sign_ctx *me, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c payload, struct q_useful_buf out_buf, struct q_useful_buf_c *result) { return t_cose_sign1_sign_aad_private(me, false, - aad, + ext_sup_data, payload, out_buf, result); @@ -575,7 +574,7 @@ t_cose_sign1_sign(struct t_cose_sign1_sign_ctx *me, static inline enum t_cose_err_t t_cose_sign1_sign_detached(struct t_cose_sign1_sign_ctx *me, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c detached_payload, struct q_useful_buf out_buf, struct q_useful_buf_c *result) @@ -583,7 +582,7 @@ t_cose_sign1_sign_detached(struct t_cose_sign1_sign_ctx *me, return t_cose_sign1_sign_aad_private(me, true, detached_payload, - aad, + ext_sup_data, out_buf, result); } @@ -591,11 +590,11 @@ t_cose_sign1_sign_detached(struct t_cose_sign1_sign_ctx *me, static inline enum t_cose_err_t t_cose_sign1_encode_signature_aad(struct t_cose_sign1_sign_ctx *me, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, QCBOREncodeContext *cbor_encode_ctx) { return t_cose_sign1_encode_signature_aad_private(me, - aad, + ext_sup_data, NULL_Q_USEFUL_BUF_C, cbor_encode_ctx); } @@ -635,7 +634,7 @@ t_cose_sign1_encode_parameters_private(struct t_cose_sign1_sign_ctx *me, */ static inline enum t_cose_err_t t_cose_sign1_encode_signature_aad_private(struct t_cose_sign1_sign_ctx *me, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c signed_payload, QCBOREncodeContext *cbor_encode_ctx) { @@ -644,7 +643,7 @@ t_cose_sign1_encode_signature_aad_private(struct t_cose_sign1_sign_ctx *me, QCBOREncode_CloseBstrWrap2(cbor_encode_ctx, false, &signed_payload); } return t_cose_sign_encode_finish(&(me->me2), - aad, + ext_sup_data, signed_payload, cbor_encode_ctx); } @@ -657,14 +656,14 @@ static inline enum t_cose_err_t t_cose_sign1_sign_aad_private(struct t_cose_sign1_sign_ctx *me, bool payload_is_detached, struct q_useful_buf_c payload, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf out_buf, struct q_useful_buf_c *result) { return t_cose_sign_sign_private(&(me->me2), payload_is_detached, payload, - aad, + ext_sup_data, out_buf, result); } diff --git a/inc/t_cose/t_cose_sign1_verify.h b/inc/t_cose/t_cose_sign1_verify.h index c6dd3edd..375fea75 100644 --- a/inc/t_cose/t_cose_sign1_verify.h +++ b/inc/t_cose/t_cose_sign1_verify.h @@ -162,7 +162,7 @@ t_cose_sign1_set_verification_key(struct t_cose_sign1_verify_ctx *context, * * The buffer must be big enough to accomodate the Sig_Structure type, * which is roughly the sum of sizes of the encoded protected parameters, - * aad and payload, along with a few dozen bytes of overhead. + * externally supplied data and payload, along with a few dozen bytes of overhead. * * To compute the exact size needed, initialize the context with * the \ref T_COSE_OPT_DECODE_ONLY option, and call the @@ -261,31 +261,31 @@ t_cose_sign1_verify(struct t_cose_sign1_verify_ctx *context, * \param[in,out] context The t_cose signature verification context. * \param[in] sign1 Pointer and length of CBOR encoded \c COSE_Sign1 * message that is to be verified. - * \param[in] aad The Additional Authenticated Data or \c NULL_Q_USEFUL_BUF_C. + * \param[in] ext_sup_data Externally supplied data or \c NULL_Q_USEFUL_BUF_C. * \param[out] payload Pointer and length of the payload. * \param[out] parameters Place to return parsed parameters. May be \c NULL. * * \return This returns one of the error codes defined by \ref t_cose_err_t. * - * This is just like t_cose_sign1_verify(), but allows passing AAD - * (Additional Authenticated Data) for verification. + * This is just like t_cose_sign1_verify(), but allows passing externally supplied data + * (fomerly referred to as "AAD") for verification. * - * AAD is some additional bytes that are covered by the signature in + * Externally supplied data is some additional bytes that are covered by the signature in * addition to the payload. They may be any bytes, but are often some * options or commands that are sent along with the \c COSE_Sign1. If - * a \c COSE_Sign1 was created with AAD, that AAD must be passed in + * a \c COSE_Sign1 was created with externally supplied data, that data must be passed in * here to successfully verify the signature. If it is not, a \ref * T_COSE_ERR_SIG_VERIFY will occur. There is no indication in the \c - * COSE_Sign1 to know whether there was AAD input when it was + * COSE_Sign1 to know whether there was externally supplied data input when it was * created. It has to be known by context. * - * Calling this with \c aad as \c NULL_Q_USEFUL_BUF_C is the same as + * Calling this with \c ext_sup_data as \c NULL_Q_USEFUL_BUF_C is the same as * calling t_cose_sign1_verify(). */ static enum t_cose_err_t t_cose_sign1_verify_aad(struct t_cose_sign1_verify_ctx *context, struct q_useful_buf_c sign1, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c *payload, struct t_cose_parameters *parameters); @@ -296,7 +296,7 @@ t_cose_sign1_verify_aad(struct t_cose_sign1_verify_ctx *context, * \param[in,out] context The t_cose signature verification context. * \param[in] cose_sign1 Pointer and length of CBOR encoded \c COSE_Sign1 * message that is to be verified. - * \param[in] aad The Additional Authenticated Data or \c NULL_Q_USEFUL_BUF_C. + * \param[in] ext_sup_data Externally supplied data or \c NULL_Q_USEFUL_BUF_C. * \param[in] detached_payload Pointer and length of the payload. * \param[out] parameters Place to return parsed parameters. May be \c NULL. * @@ -312,12 +312,12 @@ t_cose_sign1_verify_aad(struct t_cose_sign1_verify_ctx *context, * \c COSE_Sign1. The signature covers it so it must be passed in to * complete the verification. * - * \c aad may be \c NULL_Q_USEFUL_BUF_C if there is no AAD. + * \c ext_sup_data may be \c NULL_Q_USEFUL_BUF_C if there is none. */ static inline enum t_cose_err_t t_cose_sign1_verify_detached(struct t_cose_sign1_verify_ctx *context, struct q_useful_buf_c cose_sign1, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c detached_payload, struct t_cose_parameters *parameters); @@ -355,7 +355,7 @@ t_cose_sign1_get_nth_tag(const struct t_cose_sign1_verify_ctx *context, static inline enum t_cose_err_t t_cose_sign1_verify_aad(struct t_cose_sign1_verify_ctx *me, struct q_useful_buf_c cose_sign1, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c *payload, struct t_cose_parameters *parameters) { @@ -364,7 +364,7 @@ t_cose_sign1_verify_aad(struct t_cose_sign1_verify_ctx *me, return_value = t_cose_sign_verify(&(me->me2), cose_sign1, - aad, + ext_sup_data, payload, &decoded_params); if(parameters != NULL) { @@ -378,7 +378,7 @@ t_cose_sign1_verify_aad(struct t_cose_sign1_verify_ctx *me, static inline enum t_cose_err_t t_cose_sign1_verify_detached(struct t_cose_sign1_verify_ctx *me, struct q_useful_buf_c cose_sign1, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c detached_payload, struct t_cose_parameters *parameters) { @@ -387,7 +387,7 @@ t_cose_sign1_verify_detached(struct t_cose_sign1_verify_ctx *me, return_value = t_cose_sign_verify_detached(&(me->me2), cose_sign1, - aad, + ext_sup_data, detached_payload, &decoded_params); diff --git a/inc/t_cose/t_cose_sign_sign.h b/inc/t_cose/t_cose_sign_sign.h index 2f2a1e3e..d34b77f1 100644 --- a/inc/t_cose/t_cose_sign_sign.h +++ b/inc/t_cose/t_cose_sign_sign.h @@ -23,6 +23,9 @@ #ifdef __cplusplus extern "C" { +#if 0 +} /* Keep editor indention formatting happy */ +#endif #endif @@ -32,41 +35,57 @@ extern "C" { * \brief Create a \c COSE_Sign or \c COSE_Sign1 message. * * This creates a \c COSE_Sign1 or \c COSE_Sign message in compliance - * with [COSE (RFC 9052)](https://tools.ietf.org/html/rfc9052). A + * with [COSE (RFC 9052)](https://tools.ietf.org/html/rfc9052). A * \c COSE_Sign1 or \c COSE_Sign message is a CBOR-encoded binary blob - * that contains header parameters, a payload and a signature or - * signatures. - * - * This must be configured with a signer, an instance of - * \ref t_cose_signature_sign, to function. This signer is what runs - * the cryptographic algorithms and produces the actual signature. An - * example of a signer is \ref t_cose_signature_sign_main. See - * t_cose_sign_add_signer(). - * - * This implementation has a mode where a CBOR-format payload can be - * output directly into the output buffer. This saves having two - * copies of the payload in memory. For this mode use - * t_cose_sign_encode_start() and - * t_cose_sign_encode_finish(). For a simpler API that just takes - * the payload as an input buffer use t_cose_sign_sign(). + * that contains a payload that is to be authenticated, header + * parameters that carry things like the algorithm and key ID and a + * signature or signatures. Since it is CBOR, it is compact with low + * overhead and simple to decode. + * + * This implementation is in the form of an "object" called + * \c t_cose_sign_sign. The object is constituted of a signing context + * data structure and functions that operate on it. Further, this + * object delegates the actual signing to another object called + * \c t_cose_signature_sign. This is to accommodate different signing + * algorithms and schemes in a runtime pluggable manner. No + * modification of the source code for \c t_cose_sign_sign is required + * to add new algorithms. + * + * This can be used in one of two ways. + * + * The first and simplest does the bulk of the work in one call, + * t_cose_sign_sign(). It requires the payload be supplied in a single + * contiguous buffer and outputs the COSE message to a single + * contiguous buffer. This results in two copies of the payload in + * memory. + * + * The second way uses two calls, t_cose_sign_encode_start() and + * t_cose_sign_encode_finish(). Between the two calls the payload can + * be output to the CBOR encoder resulting in only one copy of the + * payload memory. + * + * This has a mode that can calculate the size of the output buffer + * for the COSE message. + * + * This is a largely complete implementation of COSE signing. It + * accommodates detached signatures and externally supplied data. * * This replaces t_cose_sign1_sign which supported only COSE_Sign1. */ /** - * The context for creating a \c COSE_Sign1 or \c COSE_Sign message. The - * allocates it and pass it to the functions here. At - * about 44 bytes it fits easily on the stack. + * The context for creating a \c COSE_Sign1 or \c COSE_Sign + * message. The caller allocates this and passes it to the functions + * here. At about 48 bytes, it fits easily on the stack. */ struct t_cose_sign_sign_ctx { /* Private data structure */ struct q_useful_buf_c encoded_prot_params; uint32_t option_flags; struct t_cose_signature_sign *signers; - struct t_cose_parameter *added_body_parameters; - /* Fields related to restartable operation */ - bool started; + struct t_cose_parameter *added_body_params; + bool started; /* For restartable operation */ }; @@ -98,28 +117,28 @@ struct t_cose_sign_sign_ctx { /** - * \brief Initialize to start creating a \c COSE_Sign1 or \c COSE_Sign. + * \brief Initialize to start creating a \c COSE_Sign1 or \c COSE_Sign. * - * \param[in] context The t_cose signing context. + * \param[in] context The signing context. * \param[in] option_flags One of \c T_COSE_OPT_XXXX. * * This initializes the \ref t_cose_sign_sign_ctx context. * Either \ref T_COSE_OPT_MESSAGE_TYPE_SIGN1 or - * \ref T_COSE_OPT_MESSAGE_TYPE_SIGN must be given for + * \ref T_COSE_OPT_MESSAGE_TYPE_SIGN must be given in * \c option_flags to indicate which COSE message to produce. * - * A \c COSE_Sign1 is simple and has only one signature. + * A \c COSE_Sign1 is simple having only one signature. * t_cose_sign_add_signer() should be called only once for it. A - \c COSE_Sign can have multiple signatures using different algorithms - * for different recipients. t_cose_sign_add_signer can be called one + * \c COSE_Sign can have multiple signatures using different algorithms + * for different recipients. t_cose_sign_add_signer() can be called one * more more times. * * \ref T_COSE_OPT_OMIT_CBOR_TAG can be or'd into \c option_flags if * the CBOR tag for \c COSE_Sign1, 18, or the tag for \c COSE_SIgn, * 98, is to be omitted. * - * The signature algorithm ID(s) is(are) set in the - * t_cose_signature_sign instance(s). + * The signature algorithm or algorithms are configured in the + * t_cose_signature_sign instance or instances. */ static void t_cose_sign_sign_init(struct t_cose_sign_sign_ctx *context, @@ -129,149 +148,160 @@ t_cose_sign_sign_init(struct t_cose_sign_sign_ctx *context, /** * \brief Add a signer that is configured with a key and algorithm ID. * - * \param[in] context The t_cose signing context. + * \param[in] context The signing context. * \param[in] signer An initialized instance of \ref t_cose_signature_sign. * * Call this at least once to configure one or more signers. The * signer, an instance of \ref t_cose_signature_sign, is an object - * that is configured with the signing algorithm, signing key and - * related. + * configured with the signing algorithm, signing key and + * related and computes the actual signature. * * When producing a \c COSE_Sign1, this must be called only * once. When producing a \c COSE_Sign, this must be called at least * once, but can be called many more times if there are to be multiple - * signatures. Note that each call can be with a different key and/or - * different signer implementations for different algorithm entirely. + * signatures. Note that each added signer can be with for a different key and/or + * different signer implementation for a different algorithm. * * This must be called with a concrete instance, such as a \ref * t_cose_signature_sign_main. The concrete instance must be * configured with a key and algorithm ID before this is called. + * Several signers are part of t_cose, but the caller may also design + * and implement their own. */ static void -t_cose_sign_add_signer(struct t_cose_sign_sign_ctx *context, - struct t_cose_signature_sign *signer); +t_cose_sign_add_signer(struct t_cose_sign_sign_ctx *context, + struct t_cose_signature_sign *signer); /** - * \brief Add header parameters to the \c COSE_Sign or \c COSE_Sign1 main body. + * \brief Add body header parameters to the \c COSE_Sign or \c COSE_Sign1. * - * \param[in] context The t_cose signing context. + * \param[in] context The signing context. * \param[in] parameters Linked list of parameters to add. * - * For simple use cases it is not necessary to call this as the - * algorithm ID, the only mandatory parameter, is automatically - * added. + * This adds parameters to the \c COSE_Sign1 or \c COSE_Sign + * body. Signature parameters in \c COSE_Signatures in \c COSE_Sign + * are handed through \ref t_cose_signature_sign. * - * It is not necessary to call this to add the kid either as that - * is handled by configuring the \ref t_cose_signature_sign with the kid. + * For simple use cases, it is unnecessary to call this as the + * algorithm ID is automatically added. * - * This adds parameters to the \c COSE_Sign1 \c COSE_Sign - * body. Parameters in \c COSE_Signatures in \c COSE_Sign are handed - * through \ref t_cose_signature_sign. + * It is unnecessary to call this to add the kid either. The kid is added + * by configuring the \ref t_cose_signature_sign. * - * This is called only once to add a linked list of - * \ref t_cose_parameter. Each node is filled in with the type, - * value, criticality and protected ness of the parameter. Integer and - * strings values go in the node. Other types are allowed through a - * parameter encode callback. Only integer parameter labels are - * supported (so far). + * This is typically called only once as subsequent calls do not + * accumulate a linked list. + * + * This adds a linked list of \ref t_cose_parameter. Each node is + * filled in with the label, type, value, criticality and + * protectedness of the parameter. Integer and string values go in the + * list node. Other types are allowed through a parameter encode + * callback. Only integer parameter labels are supported (so far). * * This mechanism replaces t_cose_sign1_set_content_type_uint() and * t_cose_sign1_set_content_type_tstr() that is used by t_cose_sign1. */ static void -t_cose_sign_add_body_header_params(struct t_cose_sign_sign_ctx *context, - struct t_cose_parameter *parameters); +t_cose_sign_add_body_header_params(struct t_cose_sign_sign_ctx *context, + struct t_cose_parameter *parameters); /** - * \brief Create and sign a \c COSE_Sign1 or \c COSE_Sign message with a payload in one call. + * \brief Create and sign a \c COSE_Sign1 or \c COSE_Sign message. * - * \param[in] context The \ref t_cose signing context. - * \param[in] aad The Additional Authenticated Data or \c NULL_Q_USEFUL_BUF_C. + * \param[in] context The signing context. + * \param[in] ext_sup_data Externally supplied data or \c NULL_Q_USEFUL_BUF_C. * \param[in] payload Pointer and length of payload to sign. * \param[in] out_buf Pointer and length of buffer to output to. - * \param[out] result Pointer and length of the resulting \c COSE_Sign1 or - * \c COSE_Sign. + * \param[out] result Pointer and length of the resulting message. * * The \c context must have been initialized with - * t_cose_sign_sign_init() and the key set through - * t_cose_sign_add_signer() before this is called. + * t_cose_sign_sign_init() and a signer object with a signing key + * added using t_cose_sign_add_signer(). * * This creates the COSE header parameter, hashes and signs the * payload and creates the signature all in one go. \c out_buf gives * the pointer and length of the memory into which the output is - * written. The pointer and length of the completed \c COSE_Sign1 is - * returned in \c result. (\c out_buf and \c result are used instead - * of the usual in/out parameter for length because it is the - * convention for q_useful_buf and is more const correct.) + * written. The pointer and length of the completed message is + * returned in \c result. + * + * The externally supplied data simply any data that should also be + * covered by the signature as described in section 4.3 of RFC 9052. + * The verifier of the message must also have exactly this data to be + * able to successfully verify the signature. Often this data is some + * parameters or fields in the protocol carrying the COSE message. + * For many use cases there is none and \c ext_sup_data is + * \c NULL_Q_USEFUL_BUF_C. * * The size of \c out_buf must be the size of the payload plus - * overhead for formating, the signature and the key id (if used). The - * formatting overhead is minimal at about 30 bytes.The total overhead - * is about 150 bytes for ECDSA 256 with a 32-byte key ID. + * overhead for formating, the signature and any added parameters like + * the key id and content type (if used). The COSE standard + * formatting overhead is minimal at about 30 bytes.For example, total + * overhead is about 150 bytes for an ECDSA 256 signature with a + * 32-byte key ID. * * To compute the size of the buffer needed before it is allocated * call this with \c out_buf containing a \c NULL pointer and large - * length like \c UINT32_MAX. The algorithm and key, kid and such - * must be set up just as if the real COSE message were to be created - * as these values are needed to compute the size correctly. The + * length like \c UINT32_MAX. The algorithm, key, kid and such must + * be set up just as if the real COSE message were to be created as + * these values are needed to compute the size correctly. The * contents of \c result will be a \c NULL pointer and the length of - * the COSE message. When run like this, the cryptographic - * functions will not actually run, but the size of their output will - * be taken into account to give an exact size. - * - * This function requires the payload be complete and formatted in a - * contiguous buffer. The resulting COSE message also - * contains the payload preceded by the header parameters and followed - * by the signature, all CBOR formatted. This function thus requires - * two copies of the payload to be in memory. Alternatively - * t_cose_sign_encode_start() and - * t_cose_sign_encode_finish() can be used. They are more complex - * to use, but avoid the two copies of the payload and can reduce - * memory requirements by close to half. - * - * TODO: rename to externally supplied data, reference section 4.3 - * See t_cose_sign_encode_finish() for more details - * about AAD. For many use cases there is no AAD and \c aad is \c NULL_Q_USEFUL_BUF_C. + * the COSE message. When run like this, the cryptographic functions + * will not actually run, but the size of their output will be taken + * into account to give an exact size. + * + * It is also possible to not do the size calculation if the size can + * be reliably estimated. Perhaps no kid or other header parameters + * are used and the algorithm is fixed. It is always safe to do this + * because t_cose will never write off the end of the output buffer. + * If the message is too long, \ref T_COSE_ERR_TOO_SMALL + * will be returned. + * + * This function requires the input payload to be complete and contiguous + * in a buffer. The resulting COSE message also contains the payload + * preceded by the header parameters and followed by the + * signature. This function thus requires two copies of the payload to + * be in memory. Alternatively t_cose_sign_encode_start() and + * t_cose_sign_encode_finish() can be used. They are more complex to + * use, but avoid the two copies of the payload and can reduce memory + * requirements by close to half. */ static enum t_cose_err_t t_cose_sign_sign(struct t_cose_sign_sign_ctx *context, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c payload, struct q_useful_buf out_buf, struct q_useful_buf_c *result); /** - * \brief Create and sign a \c COSE_Sign1 or \c COSE_Sign message with detached payload in one call. + * \brief Create and sign a \c COSE_Sign1 or \c COSE_Sign message with detached payload. * - * \param[in] context The t_cose signing context. - * \param[in] aad The Additional Authenticated Data or \c NULL_Q_USEFUL_BUF_C. + * \param[in] context The signing context. + * \param[in] ext_sup_data Externally supplied data or \c NULL_Q_USEFUL_BUF_C. * \param[in] detached_payload Pointer and length of the detached payload to sign. - * \param[in] out_buf Pointer and length of buffer to output to. - * \param[out] result Pointer and length of the resulting \c COSE_Sign1 - * or \c COSE_Sign. + * \param[in] out_buf Pointer and length of buffer to output to. + * \param[out] result Pointer and length of the resulting message. * * This is similar to, but not the same as t_cose_sign_sign(). Here * the payload is detached and conveyed separately. The signature is - * still over the payload as with t_cose_sign_sign(). The payload - * must be conveyed to recipient by some other means than by being - * inside the \c COSE_Sign1 or \c COSE_Sign. The recipient will be - * unable to verify the received message without it. + * still over the payload as with t_cose_sign_sign(). The payload must + * be conveyed to recipient by some other means than by being inside + * the \c COSE_Sign1 or \c COSE_Sign. The recipient will be unable to + * verify the received message without it. */ static enum t_cose_err_t t_cose_sign_sign_detached(struct t_cose_sign_sign_ctx *context, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c detached_payload, struct q_useful_buf out_buf, struct q_useful_buf_c *result); /** - * \brief Output first part and parameters for a \c COSE_Sign1 or \c COSE_Sign message. + * \brief Output first part of a \c COSE_Sign1 or \c COSE_Sign message. * - * \param[in] context The t_cose signing context. + * \param[in] context The signing context. * \param[in] cbor_encoder Encoding context to output to. * * This is the more complex and more memory efficient alternative to @@ -279,12 +309,11 @@ t_cose_sign_sign_detached(struct t_cose_sign_sign_ctx *context, * t_cose_sign_sign_init() and t_cose_sign_add_signer() must be called * before calling this. * - * When this is called, the opening parts of the \c COSE_Sign1 or \c - * COSE_Sign message are output to the \c cbor_encoder -- openning - * the array and the header parameters. + * When this is called, the first parts of the \c COSE_Sign1 or + * \c COSE_Sign message are output to the \c cbor_encoder. * * After this is call completes, the payload must be written to the - * \c cbor_encoder. If payload is detached add a CBOR NULL by calling + * \c cbor_encoder. If payload is detached, add a CBOR NULL by calling * QCBOREncode_AddNULL(). If the payload is not CBOR or has already * been CBOR-encoded, add it with QCBOREncode_AddBytes(). To CBOR * encode the payload directly into the output buffer call @@ -306,7 +335,7 @@ t_cose_sign_sign_detached(struct t_cose_sign_sign_ctx *context, * initialized with the options, signer and additional header * parameters just as normal as these are needed to calculate the * size. Then set up the output buffer for \c cbor_encoder with a \c - * NULL pointer and large length like \c UINT32_MAX. Call + * \c NULL pointer and large length like \c UINT32_MAX. Call * t_cose_sign_encode_start(), then format the payload into the * encoder context, then call t_cose_sign_encode_finish(). Finally * call \c QCBOREncode_FinishGetSize() to get the length. @@ -317,36 +346,30 @@ t_cose_sign_encode_start(struct t_cose_sign_sign_ctx *context, /** - * \brief Finish a \c COSE_Sign1 message by outputting the signature. + * \brief Finish a \c COSE_Sign1 or \c COSE_Sign message by outputting the signature. * - * \param[in] context The t_cose signing context. - * \param[in] aad The Additional Authenticated Data or - * \c NULL_Q_USEFUL_BUF_C. + * \param[in] context The signing context. + * \param[in] ext_sup_data Externally supplied data or \c NULL_Q_USEFUL_BUF_C. * \param[in] signed_payload The detached payload or \c NULL_Q_USEFUL_BUF_C. * \param[in] cbor_encoder Encoding context to output to. * * \return This returns one of the error codes defined by \ref t_cose_err_t. * - * Call this to complete creation of a signed \c COSE_Sign1 or \c - * COSE_Sign started with t_cose_sign_encode_start(). + * Call this to complete a signed message started with t_cose_sign_encode_start(). * * This is when the callback into the t_cose_signature_sign object(s) * is(are) called and when cryptographic signature algorithm is run. * - * AAD is simply any data that should also be covered by the - * signature. The verifier of the \c COSE_Sign1 or \c COSE_Sign must - * also have exactly this data to be able to successfully verify the - * signature. Often this data is some parameters or fields in the - * protocol carrying the COSE message. + * See t_cose_sign_sign() for a detailed description of \c ext_sup_data. * - * The completed \c COSE_Sign1 or \c COSE_Sign message is retrieved + * The completed COSE message is retrieved * from the \c cbor_encoder by calling \c QCBOREncode_Finish(). Check * the return value from QCBOREncode_Finish() to be sure there were no * encoding errors. */ enum t_cose_err_t t_cose_sign_encode_finish(struct t_cose_sign_sign_ctx *context, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c signed_payload, QCBOREncodeContext *cbor_encoder); @@ -356,6 +379,9 @@ t_cose_sign_encode_finish(struct t_cose_sign_sign_ctx *context, /* ------------------------------------------------------------------------ * Inline implementations of public functions defined above. */ + + +/* Pubic inline function; see above */ static inline void t_cose_sign_sign_init(struct t_cose_sign_sign_ctx *me, uint32_t option_flags) @@ -368,36 +394,35 @@ t_cose_sign_sign_init(struct t_cose_sign_sign_ctx *me, /** * \brief Semi-private function that does a complete signing in one call. * - * \param[in] context The t_cose signing context. + * \param[in] context The signing context. * \param[in] payload_is_detached If \c true, then \c payload is detached. * \param[in] payload The payload, inline or detached. - * \param[in] aad The Additional Authenticated Data or - * \c NULL_Q_USEFUL_BUF_C. + * \param[in] ext_sup_data Externally supplied data or \c NULL_Q_USEFUL_BUF_C. * \param[in] out_buf Pointer and length of buffer to output to. - * \param[out] result Pointer and length of the resulting - * \c COSE_Sign1. + * \param[out] result Pointer and length of the resulting message. * * \return This returns one of the error codes defined by \ref t_cose_err_t. * * This is where the work actually gets done for signing that is done - * all in one call with or without AAD and for included or detached - * payloads. + * all in one call with or without externally supplied data and for + * included or detached payloads. * * This is a private function internal to the implementation. Call - * t_cose_sign_sign_aad() instead of this. + * t_cose_sign_sign() or t_cose_sign_sign_detached() instead of this. */ enum t_cose_err_t t_cose_sign_sign_private(struct t_cose_sign_sign_ctx *context, bool payload_is_detached, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c payload, struct q_useful_buf out_buf, struct q_useful_buf_c *result); +/* Pubic inline function; see above */ static inline enum t_cose_err_t t_cose_sign_sign(struct t_cose_sign_sign_ctx *me, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c payload, struct q_useful_buf out_buf, struct q_useful_buf_c *result) @@ -405,15 +430,16 @@ t_cose_sign_sign(struct t_cose_sign_sign_ctx *me, return t_cose_sign_sign_private(me, false, payload, - aad, + ext_sup_data, out_buf, result); } +/* Pubic inline function; see above */ static inline enum t_cose_err_t t_cose_sign_sign_detached(struct t_cose_sign_sign_ctx *me, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c detached_payload, struct q_useful_buf out_buf, struct q_useful_buf_c *result) @@ -421,20 +447,22 @@ t_cose_sign_sign_detached(struct t_cose_sign_sign_ctx *me, return t_cose_sign_sign_private(me, true, detached_payload, - aad, + ext_sup_data, out_buf, result); } +/* Pubic inline function; see above */ static inline void t_cose_sign_add_body_header_params(struct t_cose_sign_sign_ctx *me, - struct t_cose_parameter *parameters) + struct t_cose_parameter *params) { - me->added_body_parameters = parameters; + me->added_body_params = params; } +/* Pubic inline function; see above */ static inline void t_cose_sign_add_signer(struct t_cose_sign_sign_ctx *context, struct t_cose_signature_sign *signer) diff --git a/inc/t_cose/t_cose_sign_verify.h b/inc/t_cose/t_cose_sign_verify.h index 2266820a..9ed47a72 100644 --- a/inc/t_cose/t_cose_sign_verify.h +++ b/inc/t_cose/t_cose_sign_verify.h @@ -200,7 +200,7 @@ t_cose_sign_set_special_param_decoder(struct t_cose_sign_verify_ctx *context, * \param[in,out] context The t_cose signature verification context. * \param[in] message Pointer and length of CBOR encoded \c COSE_Sign1 * or \c COSE_Sign message that is to be verified. - * \param[in] aad The Additional Authenticated Data or \c NULL_Q_USEFUL_BUF_C. + * \param[in] ext_sup_data Externally supplied data or \c NULL_Q_USEFUL_BUF_C. * \param[out] payload Pointer and length of the payload that is returned. * Must not be \c NULL. * \param[out] parameters Place to return decoded parameters. May be \c NULL. @@ -241,13 +241,14 @@ t_cose_sign_set_special_param_decoder(struct t_cose_sign_verify_ctx *context, * they are in the input \c COSE_Sign1 messages. For example, if the * payload is an indefinite-length byte string, this error will be * returned. + * TODO: discuss ext_sup_data like t_cose_verify1 does. * * See also t_cose_sign_verify_detached(). */ static enum t_cose_err_t t_cose_sign_verify(struct t_cose_sign_verify_ctx *context, struct q_useful_buf_c message, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c *payload, struct t_cose_parameter **parameters); @@ -258,7 +259,7 @@ t_cose_sign_verify(struct t_cose_sign_verify_ctx *context, static enum t_cose_err_t t_cose_sign_verify_detached(struct t_cose_sign_verify_ctx *context, struct q_useful_buf_c message, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c payload, struct t_cose_parameter **parameters); @@ -307,7 +308,7 @@ t_cose_sign_verify_get_last(struct t_cose_sign_verify_ctx *context); * \param[in,out] me The t_cose signature verification context. * \param[in] message Pointer and length of CBOR encoded \c COSE_Sign1 * or \c COSE_Sign message that is to be verified. - * \param[in] aad The Additional Authenticated Data or \c NULL_Q_USEFUL_BUF_C. + * \param[in] ext_sup_data Externally supplied data or \c NULL_Q_USEFUL_BUF_C. * \param[in] is_detached Indicates the payload is detached. * \param[in,out] payload Pointer and length of the payload. * \param[out] parameters Place to return parsed parameters. May be \c NULL. @@ -322,7 +323,7 @@ t_cose_sign_verify_get_last(struct t_cose_sign_verify_ctx *context); enum t_cose_err_t t_cose_sign_verify_private(struct t_cose_sign_verify_ctx *me, struct q_useful_buf_c message, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, bool is_detached, struct q_useful_buf_c *payload, struct t_cose_parameter **parameters); @@ -332,13 +333,13 @@ t_cose_sign_verify_private(struct t_cose_sign_verify_ctx *me, static inline enum t_cose_err_t t_cose_sign_verify(struct t_cose_sign_verify_ctx *me, struct q_useful_buf_c message, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c *payload, struct t_cose_parameter **parameters) { return t_cose_sign_verify_private(me, message, - aad, + ext_sup_data, false, payload, parameters); @@ -348,13 +349,13 @@ t_cose_sign_verify(struct t_cose_sign_verify_ctx *me, static inline enum t_cose_err_t t_cose_sign_verify_detached(struct t_cose_sign_verify_ctx *me, struct q_useful_buf_c message, - struct q_useful_buf_c aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf_c detached_payload, struct t_cose_parameter **parameters) { return t_cose_sign_verify_private(me, message, - aad, + ext_sup_data, true, &detached_payload, parameters); diff --git a/inc/t_cose/t_cose_signature_sign.h b/inc/t_cose/t_cose_signature_sign.h index e3ba4b3b..add195e4 100644 --- a/inc/t_cose/t_cose_signature_sign.h +++ b/inc/t_cose/t_cose_signature_sign.h @@ -95,7 +95,7 @@ struct t_cose_signature_sign; * * \param [in] me The context, the t_cose_signature_sign * instance. - * \param[in] sign_inputs Payload, aad and header parameters to sign. + * \param[in] sign_inputs Payload, externally supplied data and header parameters to sign. * \param[in] qcbor_encoder The CBOR encoder context to ouput the * simple byte string signature for a * COSE_Sign1. @@ -117,7 +117,7 @@ t_cose_signature_sign1_cb(struct t_cose_signature_sign *me, * instance. This will actually be some * thing like t_cose_signature_sign_main * that implements t_cose_signature_sign - * \param[in] sign_inputs Payload, aad and header parameters to sign. + * \param[in] sign_inputs Payload, externally supplied data and header parameters to sign. * \param[in] qcbor_encoder The CBOR encoder context to ouput * a COSE_Signature. * diff --git a/inc/t_cose/t_cose_signature_sign_eddsa.h b/inc/t_cose/t_cose_signature_sign_eddsa.h index 0b731095..828bd9b1 100644 --- a/inc/t_cose/t_cose_signature_sign_eddsa.h +++ b/inc/t_cose/t_cose_signature_sign_eddsa.h @@ -102,7 +102,7 @@ t_cose_signature_sign_eddsa_set_header_parameter(struct t_cose_signature_sign_ed * allows the user to configure such a buffer. * * The buffer must be big enough to accomodate the Sig_Structure type, - * which is roughly the sum of sizes of the encoded protected parameters, aad + * which is roughly the sum of sizes of the encoded protected parameters, externally supplied data * and payload, along with a few dozen bytes of overhead. * * To compute the exact size needed, an auxiliary buffer with a NULL diff --git a/inc/t_cose/t_cose_signature_verify.h b/inc/t_cose/t_cose_signature_verify.h index f06756d1..603f2576 100644 --- a/inc/t_cose/t_cose_signature_verify.h +++ b/inc/t_cose/t_cose_signature_verify.h @@ -41,7 +41,7 @@ struct t_cose_signature_verify; * t_cose_signature_verify. * \param[in] option_flags Option flags from t_cose_sign_verify_init(). * Mostly for \ref T_COSE_OPT_DECODE_ONLY. - * \param[in] sign_inputs Payload, aad and header parameters to verify. + * \param[in] sign_inputs Payload, externally supplied data and header parameters to verify. * \param[in] parameter_list Parameter list in which algorithm and kid is * found. * \param[in] signature The signature. diff --git a/inc/t_cose/t_cose_signature_verify_eddsa.h b/inc/t_cose/t_cose_signature_verify_eddsa.h index 1ff94721..79aba21f 100644 --- a/inc/t_cose/t_cose_signature_verify_eddsa.h +++ b/inc/t_cose/t_cose_signature_verify_eddsa.h @@ -86,7 +86,7 @@ t_cose_signature_verify_eddsa_set_special_param_decoder(struct t_cose_signature_ * * The buffer must be big enough to accomodate the Sig_Structure type, * which is roughly the sum of sizes of the encoded protected parameters, - * aad and payload, along with a few dozen bytes of overhead. + * externally supplied data and payload, along with a few dozen bytes of overhead. * * To compute the exact size needed, initialize the context with * the \ref T_COSE_OPT_DECODE_ONLY option, and call the diff --git a/src/t_cose_encrypt_dec.c b/src/t_cose_encrypt_dec.c index 8e25a08d..0b816077 100644 --- a/src/t_cose_encrypt_dec.c +++ b/src/t_cose_encrypt_dec.c @@ -125,7 +125,7 @@ decrypt_one_recipient(struct t_cose_encrypt_dec_ctx *me, enum t_cose_err_t t_cose_encrypt_dec_detached(struct t_cose_encrypt_dec_ctx* me, const struct q_useful_buf_c message, - const struct q_useful_buf_c aad, + const struct q_useful_buf_c ext_sup_data, const struct q_useful_buf_c detached_ciphertext, struct q_useful_buf plaintext_buffer, struct q_useful_buf_c *plaintext, @@ -316,7 +316,7 @@ t_cose_encrypt_dec_detached(struct t_cose_encrypt_dec_ctx* me, create_enc_structure( msg_type_string, /* in: message type context string */ protected_params, /* in: body protected parameters */ - aad, /* in: AAD from caller to integrity protect */ + ext_sup_data, /* in: externally supplied data to protect */ enc_struct_buffer, /* in: buffer for encoded Enc_structure */ &enc_structure /* out: CBOR encoded Enc_structure */ ); diff --git a/src/t_cose_encrypt_enc.c b/src/t_cose_encrypt_enc.c index acfb9013..4438fa48 100644 --- a/src/t_cose_encrypt_enc.c +++ b/src/t_cose_encrypt_enc.c @@ -27,7 +27,7 @@ enum t_cose_err_t t_cose_encrypt_enc_detached(struct t_cose_encrypt_enc *me, struct q_useful_buf_c payload, - struct q_useful_buf_c external_aad, + struct q_useful_buf_c ext_sup_data, struct q_useful_buf buffer_for_detached, struct q_useful_buf buffer_for_message, struct q_useful_buf_c *encrypted_detached, @@ -127,7 +127,7 @@ t_cose_encrypt_enc_detached(struct t_cose_encrypt_enc *me, return_value = create_enc_structure(enc_struct_string, /* in: message context string */ body_prot_headers, /* in: CBOR encoded prot hdrs */ - external_aad, /* in: external AAD */ + ext_sup_data, /* in: external AAD */ enc_struct_buffer, /* in: output buffer */ &enc_structure); /* out: encoded Enc_structure */ if(return_value != T_COSE_SUCCESS) { diff --git a/src/t_cose_mac_compute.c b/src/t_cose_mac_compute.c index 2002547d..6e1ae64e 100644 --- a/src/t_cose_mac_compute.c +++ b/src/t_cose_mac_compute.c @@ -127,7 +127,7 @@ t_cose_mac_encode_tag(struct t_cose_mac_calculate_ctx *me, * MAC are the protected parameters, the payload that is * getting MACed. */ - mac_input.aad = NULL_Q_USEFUL_BUF_C; // TODO: this won't be NULL when AAD is supported + mac_input.ext_sup_data = NULL_Q_USEFUL_BUF_C; // TODO: this won't be NULL when AAD is supported mac_input.payload = payload; mac_input.body_protected = me->protected_parameters; mac_input.sign_protected = NULL_Q_USEFUL_BUF_C; /* Never sign-protected for MAC */ diff --git a/src/t_cose_mac_validate.c b/src/t_cose_mac_validate.c index 4392ede4..4dc173f1 100644 --- a/src/t_cose_mac_validate.c +++ b/src/t_cose_mac_validate.c @@ -129,7 +129,7 @@ t_cose_mac_validate_private(struct t_cose_mac_validate_ctx *me, } /* -- Compute the ToBeMaced -- */ - mac_input.aad = aad; + mac_input.ext_sup_data = aad; mac_input.payload = *payload; mac_input.body_protected = protected_parameters; mac_input.sign_protected = NULL_Q_USEFUL_BUF_C; /* Never sign-protected for MAC */ diff --git a/src/t_cose_sign_sign.c b/src/t_cose_sign_sign.c index 7427cbd7..9aa11927 100644 --- a/src/t_cose_sign_sign.c +++ b/src/t_cose_sign_sign.c @@ -19,11 +19,10 @@ /** * \file t_cose_sign_sign.c * - * \brief This implements creation of COSE_Sign and COSE_Sign1 messages. + * \brief Creation of COSE_Sign and COSE_Sign1 messages. * - * This relies on instances of t_cose_signature_sign to create the - * actual signatures. The work done here is encoding the message with - * the headers, payload and signature(s). + * This does the encoding of a signed message, particularly the header and + * payload. The signatures are created by instances of t_cose_signature_sign. */ @@ -36,7 +35,7 @@ t_cose_sign_encode_start(struct t_cose_sign_sign_ctx *me, { enum t_cose_err_t return_value; struct t_cose_signature_sign *signer; - struct t_cose_parameter *parameters; + struct t_cose_parameter *params_list; uint64_t message_type_tag_number; /* --- Basic set up and error checks --- */ @@ -49,12 +48,10 @@ t_cose_sign_encode_start(struct t_cose_sign_sign_ctx *me, return T_COSE_ERR_BAD_OPT; } /* There must be at least one signer configured (a "signer" is an - * object that makes a signature; see struct - * t_cose_signature_sign). The signer object must be configured - * with the key material and such. - */ + * object that makes a signature; see struct t_cose_signature_sign). + * The signer object must be configured with the key material and such. */ if(signer == NULL) { - /* No signers configured. */ + /* No signers configured */ return T_COSE_ERR_NO_SIGNERS; } if(message_type_tag_number == CBOR_TAG_COSE_SIGN1 && signer->rs.next != NULL) { @@ -67,33 +64,32 @@ t_cose_sign_encode_start(struct t_cose_sign_sign_ctx *me, /* --- Make list of the body header parameters --- */ /* Form up the full list of body header parameters which may * include the COSE_Sign1 algorithm ID and kid. It may also - * include the caller-added parameters like content type. */ - parameters = NULL; + * include the caller-added body parameters like content type. */ + params_list = NULL; if(message_type_tag_number == CBOR_TAG_COSE_SIGN1) { /* For a COSE_Sign1, the parameters go in the main body header * parameter section, and the signature part just contains raw * signature bytes, not an array of COSE_Signature. This gets * the parameters from the signer. */ - signer->headers_cb(signer, ¶meters); + signer->headers_cb(signer, ¶ms_list); } - t_cose_params_append(¶meters, me->added_body_parameters); + t_cose_params_append(¶ms_list, me->added_body_params); /* --- Add the CBOR tag indicating COSE message type --- */ if(!(me->option_flags & T_COSE_OPT_OMIT_CBOR_TAG)) { QCBOREncode_AddTag(cbor_encoder, message_type_tag_number); } - /* --- Open array-of-four that holds all COSE_Sign(1) messages --- */ + /* --- Open array-of-four for either COSE_Sign or COSE_Sign1 --- */ QCBOREncode_OpenArray(cbor_encoder); /* --- Encode both protected and unprotected headers --- */ return_value = t_cose_headers_encode(cbor_encoder, - parameters, + params_list, &me->encoded_prot_params); - /* Failures in CBOR encoding will be caught in t_cose_sign_encode_finish() - * or other. No need to track here as the QCBOR encoder tracks them internally. - */ + /* CBOR encode errors are tracked internally by the encoder and + * will be caught later when the encoding is closed out. */ return return_value; } @@ -103,8 +99,8 @@ t_cose_sign_encode_start(struct t_cose_sign_sign_ctx *me, */ enum t_cose_err_t t_cose_sign_encode_finish(struct t_cose_sign_sign_ctx *me, - struct q_useful_buf_c aad, - struct q_useful_buf_c signed_payload, + const struct q_useful_buf_c ext_sup_data, + const struct q_useful_buf_c signed_payload, QCBOREncodeContext *cbor_encoder) { enum t_cose_err_t return_value; @@ -117,31 +113,28 @@ t_cose_sign_encode_finish(struct t_cose_sign_sign_ctx *me, /* Check that there are no CBOR encoding errors before proceeding * with hashing and signing. This is not actually necessary as the * errors will be caught correctly later, but it does make it a - * bit easier for the caller to debug problems. - */ + * bit easier for the caller to debug problems. */ return_value = qcbor_encode_error_to_t_cose_error(cbor_encoder); if(return_value != T_COSE_SUCCESS) { return return_value;; } #endif /* !T_COSE_DISABLE_USAGE_GUARDS */ - message_type_tag_number = me->option_flags & T_COSE_OPT_MESSAGE_TYPE_MASK; - /* --- Signature for COSE_Sign1 or signatures for COSE_Sign --- */ sign_inputs.body_protected = me->encoded_prot_params; sign_inputs.sign_protected = NULL_Q_USEFUL_BUF_C; /* filled in by sign_cb */ sign_inputs.payload = signed_payload; - sign_inputs.aad = aad; + sign_inputs.ext_sup_data = ext_sup_data; signer = me->signers; + message_type_tag_number = me->option_flags & T_COSE_OPT_MESSAGE_TYPE_MASK; if(message_type_tag_number == CBOR_TAG_COSE_SIGN1) { - /* --- Single signature for COSE_Sign1 --- */ + /* --- A single signature for COSE_Sign1 --- */ /* This calls the signer object to output the signature bytes - * as a byte string to the CBOR encode context. - */ + * as a byte string to the CBOR encode context. */ return_value = signer->sign1_cb(signer, &sign_inputs, cbor_encoder); if(return_value != T_COSE_SUCCESS) { if(return_value == T_COSE_ERR_SIG_IN_PROGRESS) { @@ -154,10 +147,8 @@ t_cose_sign_encode_finish(struct t_cose_sign_sign_ctx *me, #ifndef T_COSE_DISABLE_COSE_SIGN /* --- One or more COSE_Signatures for COSE_Sign --- */ - /* Output the arrray of signers, each of which is an array of - * headers and signature. The surrounding array is handled - * here. - */ + /* Output the array of signers, each of which is an array of + * headers and signature. The surrounding array is handled here. */ return_value = T_COSE_ERR_NO_SIGNERS; QCBOREncode_OpenArray(cbor_encoder); while(signer != NULL) { @@ -179,8 +170,7 @@ t_cose_sign_encode_finish(struct t_cose_sign_sign_ctx *me, /* The layer above this must check for and handle CBOR encoding * errors. Some are detected at the start of this function, but - * they cannot all be deteced there. - */ + * they cannot all be deteced there. */ Done: return return_value; } @@ -191,10 +181,10 @@ t_cose_sign_encode_finish(struct t_cose_sign_sign_ctx *me, */ enum t_cose_err_t t_cose_sign_sign_private(struct t_cose_sign_sign_ctx *me, - bool payload_is_detached, - struct q_useful_buf_c payload, - struct q_useful_buf_c aad, - struct q_useful_buf out_buf, + const bool payload_is_detached, + const struct q_useful_buf_c payload, + const struct q_useful_buf_c ext_sup_data, + const struct q_useful_buf out_buf, struct q_useful_buf_c *result) { QCBOREncodeContext cbor_encoder; @@ -212,28 +202,30 @@ t_cose_sign_sign_private(struct t_cose_sign_sign_ctx *me, if(payload_is_detached) { /* --- Output NULL for the payload --- */ /* In detached content mode, the output COSE message does not - * contain the payload. It is delivered in another channel. - */ + * contain the payload. It is delivered in another channel. */ QCBOREncode_AddNULL(&cbor_encoder); } else { /* --- Output the payload into the encoder context --- */ /* Payload may or may not actually be CBOR format here. This * function does the job just fine because it just adds bytes - * to the encoded output without anything extra. - */ - + * to the encoded output without anything extra. */ QCBOREncode_AddBytes(&cbor_encoder, payload); } - return_value = t_cose_sign_encode_finish(me, - aad, - payload, - &cbor_encoder); - if(return_value) { + /* --- Create the signature or signatures --- */ + return_value = t_cose_sign_encode_finish(me, ext_sup_data, payload, &cbor_encoder); + if(return_value != T_COSE_SUCCESS) { goto Done; } /* --- Close off and get the resulting encoded CBOR --- */ +#ifndef T_COSE_DISABLE_USAGE_GUARDS + /* This provides a more accurate error at the cost more object code. */ + return_value = qcbor_encode_error_to_t_cose_error(&cbor_encoder); + if(return_value != T_COSE_SUCCESS) { + goto Done; + } +#endif /* !T_COSE_DISABLE_USAGE_GUARDS */ if(QCBOREncode_Finish(&cbor_encoder, result)) { return_value = T_COSE_ERR_CBOR_FORMATTING; goto Done; diff --git a/src/t_cose_sign_verify.c b/src/t_cose_sign_verify.c index 80d7aa10..95961747 100644 --- a/src/t_cose_sign_verify.c +++ b/src/t_cose_sign_verify.c @@ -455,7 +455,7 @@ call_sign1_verifiers(struct t_cose_sign_verify_ctx *me, enum t_cose_err_t t_cose_sign_verify_private(struct t_cose_sign_verify_ctx *me, const struct q_useful_buf_c message, - const struct q_useful_buf_c aad, + const struct q_useful_buf_c ext_sup_data, const bool is_detached, struct q_useful_buf_c *payload, struct t_cose_parameter **returned_params) @@ -519,7 +519,7 @@ t_cose_sign_verify_private(struct t_cose_sign_verify_ctx *me, /* --- The signature or COSE_Signature(s) --- */ sign_inputs.body_protected = protected_params; sign_inputs.sign_protected = NULL_Q_USEFUL_BUF_C; - sign_inputs.aad = aad; + sign_inputs.ext_sup_data = ext_sup_data; sign_inputs.payload = *payload; if(message_type_tag_number == T_COSE_OPT_MESSAGE_TYPE_SIGN1) { /* --- The signature bytes for a COSE_Sign1, not COSE_Signatures */ diff --git a/src/t_cose_util.c b/src/t_cose_util.c index 3509f161..4ac765a0 100644 --- a/src/t_cose_util.c +++ b/src/t_cose_util.c @@ -304,7 +304,7 @@ create_tbs(const struct t_cose_sign_inputs *sign_inputs, if(!q_useful_buf_c_is_empty(sign_inputs->sign_protected)) { QCBOREncode_AddBytes(&cbor_context, sign_inputs->sign_protected); } - QCBOREncode_AddBytes(&cbor_context, sign_inputs->aad); + QCBOREncode_AddBytes(&cbor_context, sign_inputs->ext_sup_data); QCBOREncode_AddBytes(&cbor_context, sign_inputs->payload); QCBOREncode_CloseArray(&cbor_context); @@ -440,7 +440,7 @@ create_tbs_hash(const int32_t cose_algorithm_id, } /* external_aad */ - hash_bstr(&hash_ctx, sign_inputs->aad); + hash_bstr(&hash_ctx, sign_inputs->ext_sup_data); /* payload */ hash_bstr(&hash_ctx, sign_inputs->payload); @@ -458,7 +458,7 @@ create_tbs_hash(const int32_t cose_algorithm_id, enum t_cose_err_t create_enc_structure(const char *context_string, struct q_useful_buf_c protected_headers, - struct q_useful_buf_c aad, + struct q_useful_buf_c extern_aad, struct q_useful_buf buffer_for_enc, struct q_useful_buf_c *enc_structure) { @@ -480,7 +480,7 @@ create_enc_structure(const char *context_string, QCBOREncode_OpenArray(&cbor_encoder); QCBOREncode_AddSZString(&cbor_encoder, context_string); QCBOREncode_AddBytes(&cbor_encoder, protected_headers); - QCBOREncode_AddBytes(&cbor_encoder, aad); + QCBOREncode_AddBytes(&cbor_encoder, extern_aad); QCBOREncode_CloseArray(&cbor_encoder); err = QCBOREncode_Finish(&cbor_encoder, enc_structure); if(err) { diff --git a/test/t_cose_make_test_messages.c b/test/t_cose_make_test_messages.c index 325f4fb4..ab7aee5c 100644 --- a/test/t_cose_make_test_messages.c +++ b/test/t_cose_make_test_messages.c @@ -473,7 +473,7 @@ t_cose_sign1_test_message_output_signature(struct t_cose_sign1_sign_ctx *me, * doesn't need to be checked here. */ sign_inputs.body_protected = me->protected_parameters; - sign_inputs.aad = NULL_Q_USEFUL_BUF_C; + sign_inputs.ext_sup_data = NULL_Q_USEFUL_BUF_C; sign_inputs.sign_protected = NULL_Q_USEFUL_BUF_C; sign_inputs.payload = signed_payload;