1 /* 2 * t_cose_standard_constants.h 3 * 4 * Copyright (c) 2018-2019, Laurence Lundblade. All rights reserved. 5 * Copyright (c) 2020, Arm Limited. All rights reserved. 6 * 7 * SPDX-License-Identifier: BSD-3-Clause 8 * 9 * See BSD-3-Clause license in README.md 10 */ 11 12 #ifndef __T_COSE_STANDARD_CONSTANTS_H__ 13 #define __T_COSE_STANDARD_CONSTANTS_H__ 14 15 /** 16 * \file t_cose_standard_constants.h 17 * 18 * \brief Constants from COSE standard and IANA registry. 19 * 20 * This file contains constants identifiers defined in 21 * [COSE (RFC 8152)](https://tools.ietf.org/html/rfc8152) and 22 * [IANA COSE Registry](https://www.iana.org/assignments/cose/cose.xhtml). 23 * They include algorithm IDs and other constants. 24 * 25 * Many constants in the IANA registry are not included here yet as 26 * they are not needed by t_cose. They can be added if they become 27 * needed. 28 * 29 * This file is not part of the t_cose public interface as it contains 30 * lots of stuff not needed in the public interface. The parts that 31 * are needed in the public interface are also defined as \ref 32 * T_COSE_ALGORITHM_ES256 and related (there is a pre processor cross 33 * check to make sure they don't get defined differently in 34 * t_cose_sign1_sign.c). 35 */ 36 37 38 /* --------------- COSE Header parameters ----------- 39 * https://www.iana.org/assignments/cose/cose.xhtml#header-parameters 40 */ 41 42 /** 43 * \def COSE_HEADER_PARAM_ALG 44 * 45 * \brief Label of COSE parameter that indicates an algorithm. 46 * 47 * The algorithm assignments are found in the IANA registry here 48 * https://www.iana.org/assignments/cose/cose.xhtml#algorithms 49 * Signing algorithms are identified as combinations of the 50 * public key algorithm, padding mode and hash. This must be 51 * a protected header. They may be string or integers. This 52 * implementation only support integer IDs. 53 */ 54 #define COSE_HEADER_PARAM_ALG 1 55 56 57 /** 58 * \def COSE_HEADER_PARAM_CRIT 59 * 60 * \brief Label of COSE parameter listing critical header parameters 61 * 62 * The contents is an array of header parameter labels, either string or 63 * integer. The implementation must know how to process them or it is 64 * an error. 65 */ 66 #define COSE_HEADER_PARAM_CRIT 2 67 68 69 /** 70 * \def COSE_HEADER_PARAM_CONTENT_TYPE 71 * 72 * \brief Label of COSE parameter with the content type 73 * 74 * Either an integer CoAP content type or a string MIME type. This is 75 * the type of the data in the payload. 76 */ 77 #define COSE_HEADER_PARAM_CONTENT_TYPE 3 78 79 80 /** 81 * \def COSE_HEADER_PARAM_KID 82 * 83 * \brief CBOR map label of COSE parameter that contains a kid (key ID). 84 * 85 * The kid is a byte string identifying the key. It is optional and 86 * there is no required format. They are not even required to be 87 * unique. 88 */ 89 #define COSE_HEADER_PARAM_KID 4 90 91 92 /** 93 * \def COSE_HEADER_PARAM_IV 94 * 95 * \brief CBOR map label of parameter that contains an initialization 96 * vector. 97 * 98 * A binary string initialization vector. 99 * 100 * This implementation only parses this. 101 */ 102 #define COSE_HEADER_PARAM_IV 5 103 104 105 /** 106 * \def COSE_HEADER_PARAM_PARTIAL_IV 107 * 108 * \brief CBOR map label of parameter containing partial 109 * initialization vector. 110 * 111 * A binary string partial initialization vector. 112 * 113 * This implementation only parses this. 114 */ 115 #define COSE_HEADER_PARAM_PARTIAL_IV 6 116 117 118 /** 119 * \def COSE_HEADER_PARAM_COUNTER_SIGNATURE 120 * 121 * \brief CBOR map label of parameter that holds one or more counter signature. 122 * 123 * Counter signatures can be full \c COSE_Sign1, \c COSE_Signature and 124 * such messages. This implementation doesn't support them. 125 */ 126 #define COSE_HEADER_PARAM_COUNTER_SIGNATURE 6 127 128 129 130 131 132 /* ------------ COSE Header Algorithm Parameters -------------- 133 * https://www.iana.org/assignments/cose/cose.xhtml#header-algorithm-parameters 134 * 135 * None of these are defined here yet, as they are not needed by t_cose yet. 136 */ 137 138 139 140 141 /* ------------- COSE Algorithms ---------------------------- 142 * https://www.iana.org/assignments/cose/cose.xhtml#algorithms 143 */ 144 145 /** 146 * This is defined as reserved by IANA. This implementation uses it to 147 * mean the end of a list of algorithm IDs or an unset algorithm ID. 148 */ 149 #define COSE_ALGORITHM_RESERVED 0 150 151 152 /** 153 * \def COSE_ALGORITHM_ES256 154 * 155 * \brief Indicates ECDSA with SHA-256. 156 * 157 * Value for \ref COSE_HEADER_PARAM_ALG to indicate ECDSA with SHA-256. 158 * 159 * RFC 8152 section 8.1 suggests, but does not require, that this 160 * algorithm identifier only be used with keys based on the P-256 161 * curve (also known as prime256v1 or secp256r1). 162 * 163 * See https://tools.ietf.org/search/rfc4492 and https://tools.ietf.org/html/rfc8152 164 */ 165 #define COSE_ALGORITHM_ES256 -7 166 167 /** 168 * \def COSE_ALGORITHM_ES384 169 * 170 * \brief Indicates ECDSA with SHA-384. 171 * 172 * See discussion on \ref COSE_ALGORITHM_ES256. 173 * 174 * RFC 8152 section 8.1 suggests, but does not require, that this 175 * algorithm identifier be used only with keys based on the P-384 176 * curve (also known as secp384r1). 177 */ 178 #define COSE_ALGORITHM_ES384 -35 179 180 /** 181 * \def COSE_ALGORITHM_ES512 182 * 183 * \brief Indicates ECDSA with SHA-512. 184 * 185 * See discussion on \ref COSE_ALGORITHM_ES256. 186 * 187 * RFC 8152 section 8.1 suggests, but does not require, that this 188 * algorithm identifier be used only with keys based on the P-521 189 * curve (also known as secp521r1) 190 */ 191 #define COSE_ALGORITHM_ES512 -36 192 193 194 /** 195 * \def COSE_ALGORITHM_SHA_256 196 * 197 * \brief Indicates simple SHA-256 hash. 198 * 199 * This is not used in the t_cose interface, just used internally. 200 */ 201 #define COSE_ALGORITHM_SHA_256 -16 202 203 /** 204 * \def COSE_ALGORITHM_SHA_384 205 * 206 * \brief Indicates simple SHA-384 hash. 207 * 208 * This is not used in the t_cose interface, just used internally. 209 */ 210 #define COSE_ALGORITHM_SHA_384 -43 211 212 /** 213 * \def COSE_ALGORITHM_SHA_512 214 * 215 * \brief Indicates simple SHA-512 hash. 216 * 217 * This is not used in the t_cose interface, just used internally. 218 */ 219 #define COSE_ALGORITHM_SHA_512 -44 220 221 222 223 224 /* ---------- COSE Key Common Parameters -------------- 225 * https://www.iana.org/assignments/cose/cose.xhtml#key-common-parameters 226 */ 227 228 /** 229 * \def COSE_KEY_COMMON_KTY 230 * 231 * \brief Label for data item containing the key type. 232 * 233 * In a \c COSE_Key, label that indicates the data item containing the 234 * key type. 235 */ 236 #define COSE_KEY_COMMON_KTY 1 237 238 /** 239 * \def COSE_KEY_COMMON_KID 240 * 241 * \brief Label for data item containing the key's kid. 242 * 243 * In a \c COSE_Key, label that indicates the data item containing the 244 * kid of this key. 245 */ 246 #define COSE_KEY_COMMON_KID 2 247 248 249 250 251 /* ---------- COSE Key Type Parameters -------------------- 252 * https://www.iana.org/assignments/cose/cose.xhtml#key-type-parameters 253 * 254 * These are not used by this implementation. 255 */ 256 257 /** 258 * \def COSE_KEY_PARAM_CRV 259 * 260 * \brief Label for data item indicating EC curve. 261 * 262 * In a \c COSE_Key that holds an EC key of either type \ref 263 * COSE_KEY_TYPE_EC2 or \ref COSE_KEY_TYPE_OKP this labels the data 264 * item with the EC curve for the key. 265 */ 266 #define COSE_KEY_PARAM_CRV -1 267 268 /** 269 * \def COSE_KEY_PARAM_X_COORDINATE 270 * 271 * \brief Label for data item that is an X coordinate of an EC key. 272 * 273 * In a \c COSE_Key that holds an EC key, this is label that indicates 274 * the data item containing the X coordinate. 275 * 276 * This is used for both key types \ref COSE_KEY_TYPE_EC2 and \ref 277 * COSE_KEY_TYPE_OKP. 278 */ 279 #define COSE_KEY_PARAM_X_COORDINATE -2 280 281 /** 282 * \def COSE_KEY_PARAM_Y_COORDINATE 283 * 284 * \brief Label for data item that is a y coordinate of an EC key. 285 * 286 * In a COSE_Key that holds an EC key, this is label that indicates 287 * the data item containing the Y coordinate. 288 * 289 * This is used only for key type \ref COSE_KEY_TYPE_EC2. 290 */ 291 #define COSE_KEY_PARAM_Y_COORDINATE -3 292 293 /** 294 * \def COSE_KEY_PARAM_PRIVATE_D 295 * 296 * \brief Label for data item that is d, the private part of EC key. 297 * 298 * In a \c COSE_Key that holds an EC key, this is label that indicates 299 * the data item containing the Y coordinate. 300 * 301 * This is used for both key types \ref COSE_KEY_TYPE_EC2 and \ref 302 * COSE_KEY_TYPE_OKP. 303 */ 304 #define COSE_KEY_PARAM_PRIVATE_D -4 305 306 307 308 309 /* ---------- COSE Key Types -------------------------------- 310 * https://www.iana.org/assignments/cose/cose.xhtml#key-type 311 */ 312 313 /** 314 * \def COSE_KEY_TYPE_OKP 315 * 316 * \brief Key type is Octet Key Pair 317 * 318 * In a \c COSE_Key, this is a value of the data item labeled \ref 319 * COSE_KEY_COMMON_KTY that indicates the \c COSE_Key is some sort of 320 * key pair represented by some octets. It may or may not be an EC 321 * key. 322 */ 323 #define COSE_KEY_TYPE_OKP 1 324 325 /** 326 * \def COSE_KEY_TYPE_EC2 327 * 328 * \brief Key is a 2-parameter EC key. 329 * 330 * In a \c COSE_Key, this is a value of the data item labeled \ref 331 * COSE_KEY_COMMON_KTY that indicates the \c COSE_Key is an EC key 332 * specified with two coordinates, X and Y. 333 */ 334 #define COSE_KEY_TYPE_EC2 2 335 336 /** 337 * \def COSE_KEY_TYPE_SYMMETRIC 338 * 339 * \brief Key is a symmetric key. 340 * 341 * In a \c COSE_Key, this is a value of the data item labeled \ref 342 * COSE_KEY_COMMON_KTY that indicates the \c COSE_Key is a symmetric 343 * key. 344 */ 345 #define COSE_KEY_TYPE_SYMMETRIC 4 346 347 348 349 350 /* ----------- COSE Elliptic Curves --------------------- 351 * https://www.iana.org/assignments/cose/cose.xhtml#elliptic-curves 352 */ 353 354 /** 355 * \def COSE_ELLIPTIC_CURVE_P_256 356 * 357 * \brief Key type for NIST P-256 key 358 * 359 * In a \c COSE_Key, this is a value of the data item labeled \ref 360 * COSE_KEY_PARAM_CRV to indicate the NIST P-256 curve, also known as 361 * secp256r1. 362 * 363 * This key type is always \ref COSE_KEY_TYPE_EC2. 364 */ 365 #define COSE_ELLIPTIC_CURVE_P_256 1 366 367 /** 368 * \def COSE_ELLIPTIC_CURVE_P_384 369 * 370 * \brief Key type for NIST P-384 key 371 * 372 * In a \c COSE_Key, this is a value of the data item labeled \ref 373 * COSE_KEY_PARAM_CRV to indicate the NIST P-384 curve, also known as 374 * secp384r1. 375 * 376 * This key type is always \ref COSE_KEY_TYPE_EC2. 377 */ 378 #define COSE_ELLIPTIC_CURVE_P_384 2 379 380 /** 381 * \def COSE_ELLIPTIC_CURVE_P_521 382 * 383 * \brief Key type for NIST P-521 key 384 * 385 * In a \c COSE_Key, this is a value of the data item labeled \ref 386 * COSE_KEY_PARAM_CRV to indicate the NIST P-521 curve, also known as 387 * secp521r1. 388 */ 389 #define COSE_ELLIPTIC_CURVE_P_521 3 390 391 392 393 394 /* ------- Constants from RFC 8152 --------- 395 */ 396 397 /** 398 * \def COSE_SIG_CONTEXT_STRING_SIGNATURE1 399 * 400 * \brief This is a string constant used by COSE to label \c 401 * COSE_Sign1 structures. See RFC 8152, section 4.4. 402 */ 403 #define COSE_SIG_CONTEXT_STRING_SIGNATURE1 "Signature1" 404 405 /** 406 * \def COSE_MAC_CONTEXT_STRING_MAC0 407 * 408 * \brief This is a string constant used by COSE to label \c COSE_Mac0 409 * structures. See RFC 8152, section 6.3. 410 */ 411 #define COSE_MAC_CONTEXT_STRING_MAC0 "MAC0" 412 413 #endif /* __T_COSE_STANDARD_CONSTANTS_H__ */ 414
