| Laurence Lundblade | affd65a | 2018-12-18 10:50:48 -0800 | [diff] [blame] | 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__ */ |