Contiki-NG
Loading...
Searching...
No Matches
cose.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2024, RISE Research Institutes of Sweden AB
3 * Copyright (c) 2020, Industrial Systems Institute (ISI), Patras, Greece
4 * All rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions
8 * are met:
9 * 1. Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 * 2. Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the distribution.
14 * 3. Neither the name of the copyright holder nor the names of its contributors
15 * may be used to endorse or promote products derived from this software
16 * without specific prior written permission.
17 *
18 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND
19 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
22 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 * SUCH DAMAGE.
29 *
30 */
31
32/**
33 * \file
34 * Public API declarations for COSE (RFC 9052).
35 * \author
36 * Lidia Pocero <pocero@isi.gr>, Rikard Höglund, Marco Tiloca
37 * Christos Koulamas <cklm@isi.gr>, Niclas Finne <niclas.finne@ri.se>,
38 * Nicolas Tsiftes <nicolas.tsiftes@ri.se>
39 */
40
41/**
42 * \defgroup COSE A COSE implementation (RFC 9052)
43 * @{
44 *
45 * Stateless helpers for the small subset of COSE used by EDHOC:
46 * COSE_Encrypt0 with AES-CCM* and COSE_Sign1 with ES256.
47 */
48
49#ifndef _COSE_H_
50#define _COSE_H_
51
52#include <stdbool.h>
53#include <stddef.h>
54#include <stdint.h>
55#include "edhoc-config.h"
56
57/* COSE algorithm: AES-CCM-16-64-128. */
58#define COSE_ALG_AES_CCM_16_64_128 10
59#define COSE_ALG_AES_CCM_16_64_128_KEY_LEN 16
60#define COSE_ALG_AES_CCM_16_64_128_IV_LEN 13
61#define COSE_ALG_AES_CCM_16_64_128_TAG_LEN 8
62
63/* COSE algorithm: AES-CCM-16-128-128. */
64#define COSE_ALG_AES_CCM_16_128_128 30
65#define COSE_ALG_AES_CCM_16_128_128_KEY_LEN 16
66#define COSE_ALG_AES_CCM_16_128_128_IV_LEN 13
67#define COSE_ALG_AES_CCM_16_128_128_TAG_LEN 16
68
69/* Maxima across all supported COSE AEAD algorithms. */
70#define COSE_MAX_KEY_LEN 16
71#define COSE_MAX_IV_LEN 13
72#define COSE_MAX_TAG_LEN 16
73
74/*
75 * Signature algorithm identifiers from the IANA "COSE Algorithms" registry
76 * (RFC 9053). The values are CBOR integer labels, not magnitudes; signature
77 * algorithms are registered with negative identifiers. Only ES256 is supported
78 * here; EDDSA and ES384 are listed for reference.
79 */
80#define ES256 (-7)
81#define EDDSA (-8)
82#define ES384 (-35)
83
84/**
85 * \brief AEAD-encrypt a buffer in place as a COSE_Encrypt0.
86 * \param alg COSE AEAD algorithm identifier.
87 * \param key Symmetric key (length implied by \p alg).
88 * \param nonce Nonce/IV (length implied by \p alg).
89 * \param external_aad CBOR-encoded external Additional Authenticated Data.
90 * \param external_aad_len Length of \p external_aad in bytes.
91 * \param buf In/out buffer; on entry holds the plaintext, on
92 * return holds plaintext || authentication tag.
93 * \param plaintext_len Length of the plaintext in \p buf.
94 * \param buf_capacity Total number of bytes available in \p buf. Must be at
95 * least \p plaintext_len plus the tag length for \p alg,
96 * or the call fails without writing the tag.
97 * \return Total ciphertext length on success, 0 on failure.
98 *
99 * The protected header is treated as empty, matching how EDHOC uses
100 * COSE_Encrypt0. The \c Enc_structure built internally is
101 * <tt>[ "Encrypt0", h'', external_aad ]</tt>.
102 */
103size_t cose_encrypt0_seal(uint8_t alg,
104 const uint8_t *key, const uint8_t *nonce,
105 const uint8_t *external_aad, size_t external_aad_len,
106 uint8_t *buf, size_t plaintext_len,
107 size_t buf_capacity);
108
109/**
110 * \brief AEAD-decrypt a buffer in place as a COSE_Encrypt0.
111 * \param alg COSE AEAD algorithm identifier.
112 * \param key Symmetric key (length implied by \p alg).
113 * \param nonce Nonce/IV (length implied by \p alg).
114 * \param external_aad CBOR-encoded external Additional Authenticated Data.
115 * \param external_aad_len Length of \p external_aad in bytes.
116 * \param buf In/out buffer; on entry holds plaintext || tag, on
117 * return holds the recovered plaintext.
118 * \param ciphertext_len Length of plaintext || tag in \p buf.
119 * \return Plaintext length on success, 0 on failure
120 * (including authentication failure).
121 *
122 * The protected header is treated as empty, matching how EDHOC uses
123 * COSE_Encrypt0.
124 *
125 * \warning Decryption happens in place before the tag is verified, so on
126 * failure (return 0) \p buf holds unauthenticated, attacker-influenced
127 * data. Callers must discard \p buf unless the return value is nonzero.
128 */
129size_t cose_encrypt0_open(uint8_t alg,
130 const uint8_t *key, const uint8_t *nonce,
131 const uint8_t *external_aad, size_t external_aad_len,
132 uint8_t *buf, size_t ciphertext_len);
133
134/**
135 * \brief Produce a COSE_Sign1 signature.
136 * \param alg Signing algorithm identifier (only \c ES256 is supported).
137 * \param private_key ECDSA private key.
138 * \param protected_hdr CBOR-encoded protected header bytes.
139 * \param protected_hdr_len Length of \p protected_hdr.
140 * \param external_aad CBOR-encoded external Additional Authenticated Data.
141 * \param external_aad_len Length of \p external_aad.
142 * \param payload Payload bytes to sign.
143 * \param payload_len Length of \p payload.
144 * \param signature Output buffer for the signature
145 * (\c P256_SIGNATURE_LEN bytes for ES256).
146 * \return Signature length on success, 0 on failure.
147 */
148size_t cose_sign1_sign(int8_t alg, const uint8_t *private_key,
149 const uint8_t *protected_hdr, size_t protected_hdr_len,
150 const uint8_t *external_aad, size_t external_aad_len,
151 const uint8_t *payload, size_t payload_len,
152 uint8_t *signature);
153
154/**
155 * \brief Verify a COSE_Sign1 signature.
156 * \param alg Signing algorithm identifier (only \c ES256 is supported).
157 * \param public_key ECDSA public key (\c 2 * \c ECC_KEY_LEN bytes for ES256).
158 * \param protected_hdr CBOR-encoded protected header bytes.
159 * \param protected_hdr_len Length of \p protected_hdr.
160 * \param external_aad CBOR-encoded external Additional Authenticated Data.
161 * \param external_aad_len Length of \p external_aad.
162 * \param payload Payload bytes that were signed.
163 * \param payload_len Length of \p payload.
164 * \param signature Signature to verify.
165 * \param signature_len Length of \p signature.
166 * \return true on a valid signature, false otherwise.
167 */
168bool cose_sign1_verify(int8_t alg, const uint8_t *public_key,
169 const uint8_t *protected_hdr, size_t protected_hdr_len,
170 const uint8_t *external_aad, size_t external_aad_len,
171 const uint8_t *payload, size_t payload_len,
172 const uint8_t *signature, size_t signature_len);
173
174/**
175 * \brief Get the symmetric key length for a COSE AEAD algorithm.
176 * \param alg_id COSE algorithm identifier.
177 * \return Key length in bytes, 0 if the algorithm is unknown.
178 */
179uint8_t cose_get_key_len(uint8_t alg_id);
180
181/**
182 * \brief Get the nonce/IV length for a COSE AEAD algorithm.
183 * \param alg_id COSE algorithm identifier.
184 * \return IV length in bytes, 0 if the algorithm is unknown.
185 */
186uint8_t cose_get_iv_len(uint8_t alg_id);
187
188/**
189 * \brief Get the authentication tag length for a COSE AEAD algorithm.
190 * \param alg_id COSE algorithm identifier.
191 * \return Tag length in bytes, 0 if the algorithm is unknown.
192 */
193uint8_t cose_get_tag_len(uint8_t alg_id);
194
195#endif /* _COSE_H_ */
196/** @} */
edhoc-config.h
EDHOC configuration file.
cose_get_key_len
uint8_t cose_get_key_len(uint8_t alg_id)
Get the symmetric key length for a COSE AEAD algorithm.
Definition cose.c:280
cose_encrypt0_open
size_t cose_encrypt0_open(uint8_t alg, const uint8_t *key, const uint8_t *nonce, const uint8_t *external_aad, size_t external_aad_len, uint8_t *buf, size_t ciphertext_len)
AEAD-decrypt a buffer in place as a COSE_Encrypt0.
Definition cose.c:149
cose_get_iv_len
uint8_t cose_get_iv_len(uint8_t alg_id)
Get the nonce/IV length for a COSE AEAD algorithm.
Definition cose.c:294
cose_get_tag_len
uint8_t cose_get_tag_len(uint8_t alg_id)
Get the authentication tag length for a COSE AEAD algorithm.
Definition cose.c:308
cose_encrypt0_seal
size_t cose_encrypt0_seal(uint8_t alg, const uint8_t *key, const uint8_t *nonce, const uint8_t *external_aad, size_t external_aad_len, uint8_t *buf, size_t plaintext_len, size_t buf_capacity)
AEAD-encrypt a buffer in place as a COSE_Encrypt0.
Definition cose.c:103
cose_sign1_sign
size_t cose_sign1_sign(int8_t alg, const uint8_t *private_key, const uint8_t *protected_hdr, size_t protected_hdr_len, const uint8_t *external_aad, size_t external_aad_len, const uint8_t *payload, size_t payload_len, uint8_t *signature)
Produce a COSE_Sign1 signature.
Definition cose.c:209
cose_sign1_verify
bool cose_sign1_verify(int8_t alg, const uint8_t *public_key, const uint8_t *protected_hdr, size_t protected_hdr_len, const uint8_t *external_aad, size_t external_aad_len, const uint8_t *payload, size_t payload_len, const uint8_t *signature, size_t signature_len)
Verify a COSE_Sign1 signature.
Definition cose.c:242