t_cose_util.h File Reference

Utility functions used internally by the t_cose implementation. More...

#include <stdint.h>
#include "useful_buf.h"
#include "t_cose_common.h"

Go to the source code of this file.

Macros
#define	T_COSE_SHORT_CIRCUIT_KID_SIZE   32
	Size of the key returned by get_short_circuit_kid(). More...

Functions
int32_t	hash_alg_id_from_sig_alg_id (int32_t cose_sig_alg_id)
	Return hash algorithm ID from a signature algorithm ID. More...
enum t_cose_err_t	create_tbs_hash (int32_t cose_alg_id, struct useful_buf buffer_for_hash, struct useful_buf_c *hash, struct useful_buf_c protected_headers, struct useful_buf_c payload)
	Create the hash of the to-be-signed (TBS) bytes for COSE. More...
enum t_cose_err_t	get_short_circuit_kid (struct useful_buf buffer_for_kid, struct useful_buf_c *kid)
	Get the special kid for short-circuit signing. More...

Detailed Description

Utility functions used internally by the t_cose implementation.

Definition in file t_cose_util.h.

Macro Definition Documentation

T_COSE_SHORT_CIRCUIT_KID_SIZE

#define T_COSE_SHORT_CIRCUIT_KID_SIZE   32

Size of the key returned by get_short_circuit_kid().

It is always this size.

Definition at line 92 of file t_cose_util.h.

Function Documentation

hash_alg_id_from_sig_alg_id()

int32_t hash_alg_id_from_sig_alg_id

(

int32_t

cose_sig_alg_id

)

Return hash algorithm ID from a signature algorithm ID.

Parameters

[in]

cose_sig_alg_id

A COSE signature algorithm identifier.

Returns

INT32_MAX when the signature algorithm ID is not known.

This works off of algorithm identifiers defined in the [IANA COSE Registry] (https://www.iana.org/assignments/cose/cose.xhtml). Corresponding local integer constants are defined in t_cose_defines.h.

COSE signing algorithms are the combination of public key algorithm, curve, key size, hash algorithm and hash size. They are simple integers making them convenient for direct use in code.

This function returns an identifier for only the hash algorithm from the combined identifier.

If the needed algorithm identifiers are not in the IANA registry, they can be added to it. This will take some time and work. It is also fine to use algorithms in the proprietary space.

create_tbs_hash()

enum t_cose_err_t create_tbs_hash	(	int32_t	cose_alg_id,
		struct useful_buf	buffer_for_hash,
		struct useful_buf_c *	hash,
		struct useful_buf_c	protected_headers,
		struct useful_buf_c	payload
	)

Create the hash of the to-be-signed (TBS) bytes for COSE.

Parameters

[in]	cose_alg_id	The COSE signing algorithm ID. Used to determine which hash function to use.
[in]	buffer_for_hash	Pointer and length of buffer into which the resulting hash is put.
[out]	hash	Pointer and length of the resulting hash.
[in]	protected_headers	The CBOR encoded protected headers.
[in]	payload	The CBOR encoded payload

Returns

This returns one of the error codes defined by t_cose_err_t.

Return values

T_COSE_ERR_SIG_STRUCT	Most likely this is because the protected_headers passed in is larger than T_COSE_SIGN1_MAX_PROT_HEADER.
T_COSE_ERR_UNSUPPORTED_HASH	If the hash algorithm is not known.
T_COSE_ERR_HASH_GENERAL_FAIL	In case of some general hash failure.

The input to the public key signature algorithm in COSE is the hash of a CBOR encoded structure containing the protected headers algorithm ID and a few other things. This formats that structure and computes the hash of it. These are known as the to-be-signed or "TBS" bytes.

get_short_circuit_kid()

enum t_cose_err_t get_short_circuit_kid	(	struct useful_buf	buffer_for_kid,
		struct useful_buf_c *	kid
	)

Get the special kid for short-circuit signing.

Parameters

[in]	buffer_for_kid	Pointer and length of buffer into which the resulting hash is put. It should always be at least T_COSE_SHORT_CIRCUIT_KID_SIZE.
[out]	kid	Pointer and length of the returned kid.

Return values

T_COSE_SUCCESS	The kid was returned.
T_COSE_ERR_KEY_BUFFER_SIZE	buffer_for_kid is too small

This always returns the same key ID. It always indicates short-circuit signing. It is OK to hard code this as the probability of collision with this ID is extremely low and the same as for collision between any two key IDs (kids) of any sort.

This is the value of the kid.

   0xef, 0x95, 0x4b, 0x4b, 0xd9, 0xbd, 0xf6, 0x70,
   0xd0, 0x33, 0x60, 0x82, 0xf5, 0xef, 0x15, 0x2a,
   0xf8, 0xf3, 0x5b, 0x6a, 0x6c, 0x00, 0xef, 0xa6,
   0xa9, 0xa7, 0x1f, 0x49, 0x51, 0x7e, 0x18, 0xc6