Skip to content

Commit

Permalink
"aad"->"ext_sup_data" and other documentation improvements
Browse files Browse the repository at this point in the history 
Documentation for sign is improved

Comments for sign implementation improved

Rename "aad" to "ext_sup_data" in the interface to align with 4.3 in RFC 9052.

Improved error reporting for signing.
  • Loading branch information
@laurencelundblade
laurencelundblade authored Nov 4, 2023
1 parent fa047af commit bd24e8f
Show file tree
Hide file tree
Showing 21 changed files with 330 additions and 307 deletions.
7 changes: 4 additions & 3 deletions inc/t_cose/t_cose_common.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -284,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,
Expand Down Expand Up @@ -778,7 +779,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
Expand Down Expand Up @@ -819,7 +820,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.
Expand All @@ -829,7 +830,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;
};
Expand Down
19 changes: 9 additions & 10 deletions inc/t_cose/t_cose_encrypt_dec.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
*/
Expand All @@ -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.
Expand Down Expand Up @@ -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);
Expand All @@ -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.
Expand All @@ -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,
Expand Down Expand Up @@ -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,
Expand Down
26 changes: 16 additions & 10 deletions inc/t_cose/t_cose_encrypt_enc.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
*/
Expand All @@ -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.
*
Expand All @@ -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.
*
Expand All @@ -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);

Expand All @@ -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.
Expand All @@ -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,
Expand Down Expand Up @@ -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,
Expand Down
24 changes: 11 additions & 13 deletions inc/t_cose/t_cose_mac_compute.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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);
Expand All @@ -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.
Expand All @@ -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);
Expand All @@ -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
Expand All @@ -272,15 +270,15 @@ 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.
*/
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);
Expand Down Expand Up @@ -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);
Expand All @@ -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,
Expand Down
Loading

0 comments on commit bd24e8f

Please sign in to comment.