Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

documentation and terminology improvements #262

Merged
merged 1 commit into from
Nov 4, 2023
Merged

documentation and terminology improvements #262

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions inc/t_cose/t_cose_common.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,6 @@
* See BSD-3-Clause license in README.md
*/


#ifndef __T_COSE_COMMON_H__
#define __T_COSE_COMMON_H__

Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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;
};
Expand Down
19 changes: 9 additions & 10 deletions inc/t_cose/t_cose_encrypt_dec.h
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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