Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
t_cose_util.h
Go to the documentation of this file.
1 /*
2  * t_cose_util.h
3  *
4  * Copyright 2019, Laurence Lundblade
5  *
6  * SPDX-License-Identifier: BSD-3-Clause
7  *
8  * See BSD-3-Clause license in README.mdE.
9  */
10 
11 
12 #ifndef __T_COSE_UTIL_H__
13 #define __T_COSE_UTIL_H__
14 
15 #include <stdint.h>
16 #include "useful_buf.h"
17 #include "t_cose_common.h"
18 
19 /**
20  * \file t_cose_util.h
21  *
22  * \brief Utility functions used internally by the t_cose implementation.
23  *
24  */
25 
26 
27 /**
28  * \brief Return hash algorithm ID from a signature algorithm ID
29  *
30  * \param[in] cose_sig_alg_id A COSE signature algorithm identifier.
31  *
32  * \return \c INT32_MAX when the signature algorithm ID is not known.
33  *
34  * This works off of algorithm identifiers defined in the [IANA COSE
35  * Registry] (https://www.iana.org/assignments/cose/cose.xhtml).
36  * Corresponding local integer constants are defined in
37  * t_cose_defines.h.
38  *
39  * COSE signing algorithms are the combination of public key
40  * algorithm, curve, key size, hash algorithm and hash size. They are
41  * simple integers making them convenient for direct use in code.
42  *
43  * This function returns an identifier for only the hash algorithm
44  * from the combined identifier.
45  *
46  * If the needed algorithm identifiers are not in the IANA registry,
47  * they can be added to it. This will take some time and work. It is
48  * also fine to use algorithms in the proprietary space.
49  */
50 int32_t hash_alg_id_from_sig_alg_id(int32_t cose_sig_alg_id);
51 
52 
53 /**
54  * \brief Create the hash of the to-be-signed (TBS) bytes for COSE.
55  *
56  * \param[in] cose_alg_id The COSE signing algorithm ID. Used to
57  * determine which hash function to use.
58  * \param[in] buffer_for_hash Pointer and length of buffer into which
59  * the resulting hash is put.
60  * \param[out] hash Pointer and length of the
61  * resulting hash.
62  * \param[in] protected_headers The CBOR encoded protected headers.
63  * \param[in] payload The CBOR encoded payload
64  *
65  * \return This returns one of the error codes defined by \ref t_cose_err_t.
66  *
67  * \retval T_COSE_ERR_SIG_STRUCT
68  * Most likely this is because the protected_headers passed in
69  * is larger than \ref T_COSE_SIGN1_MAX_PROT_HEADER.
70  * \retval T_COSE_ERR_UNSUPPORTED_HASH
71  * If the hash algorithm is not known.
72  * \retval T_COSE_ERR_HASH_GENERAL_FAIL
73  * In case of some general hash failure.
74  *
75  * The input to the public key signature algorithm in COSE is the hash
76  * of a CBOR encoded structure containing the protected headers
77  * algorithm ID and a few other things. This formats that structure
78  * and computes the hash of it. These are known as the to-be-signed or
79  * "TBS" bytes.
80  */
81 enum t_cose_err_t create_tbs_hash(int32_t cose_alg_id,
82  struct useful_buf buffer_for_hash,
83  struct useful_buf_c *hash,
84  struct useful_buf_c protected_headers,
85  struct useful_buf_c payload);
86 
87 
88 /**
89  * Size of the key returned by get_short_circuit_kid(). It is always
90  * this size.
91  */
92 #define T_COSE_SHORT_CIRCUIT_KID_SIZE 32
93 
94 
95 /**
96  * \brief Get the special kid for short-circuit signing.
97  *
98  * \param[in] buffer_for_kid Pointer and length of buffer into which
99  * the resulting hash is put. It should
100  * always be at least \ref
101  * T_COSE_SHORT_CIRCUIT_KID_SIZE.
102  * \param[out] kid Pointer and length of the returned kid.
103  *
104  * \retval T_COSE_SUCCESS
105  * The kid was returned.
106  * \retval T_COSE_ERR_KEY_BUFFER_SIZE
107  * \c buffer_for_kid is too small
108  *
109  * This always returns the same key ID. It always indicates
110  * short-circuit signing. It is OK to hard code this as the
111  * probability of collision with this ID is extremely low and the same
112  * as for collision between any two key IDs (kids) of any sort.
113  *
114  * This is the value of the kid.
115  *
116  * 0xef, 0x95, 0x4b, 0x4b, 0xd9, 0xbd, 0xf6, 0x70,
117  * 0xd0, 0x33, 0x60, 0x82, 0xf5, 0xef, 0x15, 0x2a,
118  * 0xf8, 0xf3, 0x5b, 0x6a, 0x6c, 0x00, 0xef, 0xa6,
119  * 0xa9, 0xa7, 0x1f, 0x49, 0x51, 0x7e, 0x18, 0xc6
120  *
121  */
122 enum t_cose_err_t
123 get_short_circuit_kid(struct useful_buf buffer_for_kid,
124  struct useful_buf_c *kid);
125 
126 #endif /* __T_COSE_UTIL_H__ */
useful_buf.h
This is a TF-M coding style version of UsefulBuf.
t_cose_common.h
Defines common to all public t_cose interfaces.
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.
useful_buf
The non-const UsefulBuf typically used for some allocated memory that is to be filled in...
Definition: UsefulBuf.h:160
useful_buf_c
UsefulBufC and UsefulBuf are simple data structures to hold a pointer and length for a binary data...
Definition: UsefulBuf.h:149
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.
t_cose_err_t
t_cose_err_t
Error codes return by t_cose.
Definition: t_cose_common.h:44
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.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.