1 /*
2 * Copyright (c) 2019, Laurence Lundblade. All rights reserved.
3 * Copyright (c) 2020-2023, Arm Limited. All rights reserved.
4 *
5 * SPDX-License-Identifier: BSD-3-Clause
6 */
7
8 #ifndef __T_COSE_MAC0_VERIFY_H_
9 #define __T_COSE_MAC0_VERIFY_H_
10
11 #include <stdint.h>
12 #include "qcbor/qcbor.h"
13 #include "t_cose_common.h"
14
15 #ifdef __cplusplus
16 extern "C" {
17 #endif
18
19
20 /**
21 * Context for tag verification. It is about 24 bytes on a
22 * 64-bit machine and 12 bytes on a 32-bit machine.
23 */
24 struct t_cose_mac0_verify_ctx {
25 /* Private data structure */
26 struct t_cose_key verification_key;
27 int32_t option_flags;
28 };
29
30
31 /**
32 * \brief Initialize for \c COSE_Mac0 message verification.
33 *
34 * \param[in,out] context The context to initialize.
35 * \param[in] option_flags Options controlling the verification.
36 *
37 * This must be called before using the verification context.
38 */
39 static void
40 t_cose_mac0_verify_init(struct t_cose_mac0_verify_ctx *context,
41 int32_t option_flags);
42
43
44 /**
45 * \brief Set key for \c COSE_Mac0 message verification.
46 *
47 * \param[in,out] context The context of COSE_Mac0 verification
48 * \param[in] verify_key The verification key to use.
49 *
50 * Look up by kid parameter and fetch the key for MAC verification.
51 * Setup the \ref verify_key structure and fill it in \ref context.
52 */
53 static void
54 t_cose_mac0_set_verify_key(struct t_cose_mac0_verify_ctx *context,
55 struct t_cose_key verify_key);
56
57 /**
58 * \brief Verify a COSE_Mac0
59 *
60 * \param[in] context The context of COSE_Mac0 verification
61 * \param[in] cose_mac0 Pointer and length of CBOR encoded \c COSE_Mac0
62 * that is to be verified.
63 * \param[out] payload Pointer and length of the still CBOR encoded
64 * payload
65 *
66 * \return This returns one of the error codes defined by \ref t_cose_err_t.
67 *
68 * Verification involves the following steps.
69 *
70 * The CBOR structure is parsed and verified. It makes sure \c COSE_Mac0
71 * is valid CBOR and that it is tagged as a \c COSE_Mac0.
72 *
73 * The signing algorithm is pulled out of the protected headers.
74 *
75 * The kid (key ID) is parsed out of the unprotected headers if it exists.
76 *
77 * The payload is identified. It doesn't have to be parsed in detail
78 * because it is wrapped in a bstr.
79 *
80 * Finally, the MAC verification is performed if \ref T_COSE_OPT_DECODE_ONLY
81 * is not set in option flag. Otherwise, the verification will be skipped.
82 * The MAC algorithm to use comes from the signing algorithm in the
83 * protected headers.
84 * If the algorithm is not known or not supported this will error out.
85 *
86 * If it is successful, the pointer of the CBOR-encoded payload is
87 * returned.
88 */
89 enum t_cose_err_t t_cose_mac0_verify(struct t_cose_mac0_verify_ctx *context,
90 struct q_useful_buf_c cose_mac0,
91 struct q_useful_buf_c *payload,
92 struct t_cose_parameters *parameters);
93
94 /* ------------------------------------------------------------------------
95 * Inline implementations of public functions defined above.
96 */
97 static inline void
t_cose_mac0_verify_init(struct t_cose_mac0_verify_ctx * context,int32_t option_flags)98 t_cose_mac0_verify_init(struct t_cose_mac0_verify_ctx *context,
99 int32_t option_flags)
100 {
101 context->option_flags = option_flags;
102 context->verification_key = T_COSE_NULL_KEY;
103 }
104
105 static inline void
t_cose_mac0_set_verify_key(struct t_cose_mac0_verify_ctx * context,struct t_cose_key verify_key)106 t_cose_mac0_set_verify_key(struct t_cose_mac0_verify_ctx *context,
107 struct t_cose_key verify_key)
108 {
109 context->verification_key = verify_key;
110 }
111
112 #ifdef __cplusplus
113 }
114 #endif
115
116 #endif /* __T_COSE_MAC0_VERIFY_H_ */
117
