aboutsummaryrefslogtreecommitdiff log msg author committer range
path: root/lib/ext/t_cose/inc/t_cose_common.h
blob: c6f2ec6b2b7eee85298e8fe1651be049c75415b5 (plain)
 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495  /* * t_cose_common.h * * Copyright 2019, Laurence Lundblade * Copyright (c) 2020, Arm Limited. All rights reserved. * * SPDX-License-Identifier: BSD-3-Clause * * See BSD-3-Clause license in README.md */ #ifndef __T_COSE_COMMON_H__ #define __T_COSE_COMMON_H__ #include #include "q_useful_buf.h" #ifdef __cplusplus extern "C" { #endif /** * \file t_cose_common.h * * \brief This file contains definitions common to all public t_cose * interfaces. * * t_cose_common.h contains the definitions common to all public * t_cose interfaces, particularly the error codes, algorithm * identification constants and the structure containing a key. * * **Compile Time Configuration Options** * * \c T_COSE_DISABLE_SHORT_CIRCUIT_SIGN -- This disables short-circuit * signing test mode. This saves a small amount of object code * * \c T_COSE_DISABLE_ES512 -- Disables the COSE algorithm ES512 * algorithm. This saves a tiny amount of code and a few hundred bytes * of stack. It saves more than \c T_COSE_DISABLE_ES384. * * \c T_COSE_DISABLE_ES384 -- Disables the COSE algorithm ES384 * algorithm. This saves a tiny amount of code and a few hundred bytes * of stack. No stack will be saved if \c T_COSE_DISABLE_ES512 is not * also defined. * * \c T_COSE_DISABLE_CONTENT_TYPE -- Disables the content type * parameters for both signing and verifying. */ /** * \def T_COSE_ALGORITHM_ES256 * * \brief Indicates ECDSA with SHA-256. * * This value comes from the * [IANA COSE Registry](https://www.iana.org/assignments/cose/cose.xhtml). * * The COSE standard recommends a key using the secp256r1 curve with * this algorithm. This curve is also known as prime256v1 and P-256. */ #define T_COSE_ALGORITHM_ES256 -7 /** * \def T_COSE_ALGORITHM_ES384 * * \brief Indicates ECDSA with SHA-384. * * This value comes from the * [IANA COSE Registry](https://www.iana.org/assignments/cose/cose.xhtml). * * The COSE standard recommends a key using the secp384r1 curve with * this algorithm. This curve is also known as P-384. */ #define T_COSE_ALGORITHM_ES384 -35 /** * \def T_COSE_ALGORITHM_ES512 * * \brief Indicates ECDSA with SHA-512. * * This value comes from the * [IANA COSE Registry](https://www.iana.org/assignments/cose/cose.xhtml). * * The COSE standard recommends a key using the secp521r1 curve with * this algorithm. This curve is also known as P-521. */ #define T_COSE_ALGORITHM_ES512 -36 /** * \def T_COSE_ALGORITHM_HMAC256 * * \brief Indicates HMAC with SHA256 * * This value comes from the * [IANA COSE Registry](https://www.iana.org/assignments/cose/cose.xhtml). * * Value for \ref COSE_HEADER_PARAM_ALG to indicate HMAC w/ SHA-256 */ #define T_COSE_ALGORITHM_HMAC256 5 /** * \def T_COSE_ALGORITHM_HMAC384 * * \brief Indicates HMAC with SHA384 * * This value comes from the * [IANA COSE Registry](https://www.iana.org/assignments/cose/cose.xhtml). * * Value for \ref COSE_HEADER_PARAM_ALG to indicate HMAC w/ SHA-384 */ #define T_COSE_ALGORITHM_HMAC384 6 /** * \def T_COSE_ALGORITHM_HMAC512 * * \brief Indicates HMAC with SHA512 * * This value comes from the * [IANA COSE Registry](https://www.iana.org/assignments/cose/cose.xhtml). * * Value for \ref COSE_HEADER_PARAM_ALG to indicate HMAC w/ SHA-512 */ #define T_COSE_ALGORITHM_HMAC512 7 /** * Indicates the cryptographic library the \ref t_cose_key is intended * for. Usually only one cryptographic library is integrated so this * serves as a cross-check. */ enum t_cose_crypto_lib_t { /** can be used for integrations * that don't have or don't want to have any cross-check. */ T_COSE_CRYPTO_LIB_UNIDENTIFIED = 0, /** \c key_ptr points to a malloced OpenSSL EC_KEY. The caller * needs to free it after the operation is done. */ T_COSE_CRYPTO_LIB_OPENSSL = 1, /** \c key_handle is a \c psa_key_handle_t in Arm's Platform Security * Architecture */ T_COSE_CRYPTO_LIB_PSA = 2 }; /** * This structure is used to indicate or pass a key through the t_cose * implementation to the underlying, platform-specific cryptography * libraries for signing and verifying signature. You must know the * cryptographic library that is integrated with t_cose to know how to * fill in this data structure. * * For example, in the OpenSSL integration, \ref key_ptr should point * to an OpenSSL \c EC_KEY type. */ struct t_cose_key { /** Identifies the crypto library this key was created for. The * crypto library knows if it uses the handle or the pointer so * this indirectly selects the union member. */ enum t_cose_crypto_lib_t crypto_lib; union { /** For libraries that use a pointer to the key or key * handle. \c NULL indicates empty. */ void *key_ptr; /** For libraries that use an integer handle to the key */ uint64_t key_handle; } k; }; /** An empty or \c NULL \c t_cose_key */ #define T_COSE_NULL_KEY \ ((struct t_cose_key){T_COSE_CRYPTO_LIB_UNIDENTIFIED, {0}}) /* Private value. Intentionally not documented for Doxygen. This is * the size allocated for the encoded protected header parameters. It * needs to be big enough for encode_protected_parameters() to * succeed. It currently sized for one parameter with an algorithm ID * up to 32 bits long -- one byte for the wrapping map, one byte for * the label, 5 bytes for the ID. If this is made accidentially too * small, QCBOR will only return an error, and not overrun any * buffers. * * 17 extra bytes are added, rounding it up to 24 total, in case some * other protected header parameter is to be added and so the test * using T_COSE_TEST_CRIT_PARAMETER_EXIST can work. */ #define T_COSE_SIGN1_MAX_SIZE_PROTECTED_PARAMETERS (1+1+5+17) /* Private value. Intentionally not documented for Doxygen. * This is the size allocated for the encoded protected headers. It * needs to be big enough for make_protected_header() to succeed. It * currently sized for one header with an algorithm ID up to 32 bits * long -- one byte for the wrapping map, one byte for the label, 5 * bytes for the ID. If this is made accidentially too small, QCBOR will * only return an error, and not overrun any buffers. * * 9 extra bytes are added, rounding it up to 16 total, in case some * other protected header is to be added. */ #define T_COSE_MAC0_MAX_SIZE_PROTECTED_PARAMETERS (1 + 1 + 5 + 9) /** * Error codes return by t_cose. */ /* * Do not reorder these. It is OK to add new ones at the end. * * Explicit values are included because some tools like debuggers show * only the value, not the symbol, and it is hard to count up through * 35 lines to figure out the actual value. */ enum t_cose_err_t { /** Operation completed successfully. */ T_COSE_SUCCESS = 0, /** The requested signing algorithm is not supported. */ T_COSE_ERR_UNSUPPORTED_SIGNING_ALG = 1, /** Internal error when encoding protected parameters, usually * because they are too big. It is internal because the caller * can't really affect the size of the protected parameters. */ T_COSE_ERR_MAKING_PROTECTED = 2, /** The hash algorithm needed is not supported. Note that the * signing algorithm identifier identifies the hash algorithm. */ T_COSE_ERR_UNSUPPORTED_HASH = 3, /** Some system failure when running the hash algorithm. */ T_COSE_ERR_HASH_GENERAL_FAIL = 4, /** The buffer to receive a hash result is too small. */ T_COSE_ERR_HASH_BUFFER_SIZE = 5, /** The buffer to receive result of a signing operation is too * small. */ T_COSE_ERR_SIG_BUFFER_SIZE = 6, /** When verifying a \c COSE_Sign1, the CBOR is "well-formed", but * something is wrong with the format of the CBOR outside of the * header parameters. For example, it is missing something like * the payload or something is of an unexpected type. */ T_COSE_ERR_SIGN1_FORMAT = 8, /** When decoding some CBOR like a \c COSE_Sign1, the CBOR was not * "well-formed". Most likely what was supposed to be CBOR is * either not or is corrupted. The CBOR is can't be decoded. */ T_COSE_ERR_CBOR_NOT_WELL_FORMED = 9, /** The CBOR is "well-formed", but something is wrong with format * in the header parameters. For example, a parameter is labeled * with other than an integer or string or the value is an integer * when a byte string is expected. */ T_COSE_ERR_PARAMETER_CBOR = 10, /** No algorithm ID was found when one is needed. For example, * when verifying a \c COSE_Sign1. */ T_COSE_ERR_NO_ALG_ID = 11, /** No kid (key ID) was found when one is needed. For example, * when verifying a \c COSE_Sign1. */ T_COSE_ERR_NO_KID = 12, /** Signature verification failed. For example, the cryptographic * operations completed successfully but hash wasn't as * expected. */ T_COSE_ERR_SIG_VERIFY = 13, /** Verification of a short-circuit signature failed. */ T_COSE_ERR_BAD_SHORT_CIRCUIT_KID = 14, /** Some (unspecified) argument was not valid. */ T_COSE_ERR_INVALID_ARGUMENT = 15, /** Out of heap memory. This originates in crypto library as * t_cose does not use malloc. */ T_COSE_ERR_INSUFFICIENT_MEMORY = 16, /** General unspecific failure. */ T_COSE_ERR_FAIL = 17, /** Equivalent to \c PSA_ERROR_TAMPERING_DETECTED. */ T_COSE_ERR_TAMPERING_DETECTED = 18, /** The key identified by a \ref t_cose_key or a key ID was not * found. */ T_COSE_ERR_UNKNOWN_KEY = 19, /** The key was found, but it was the wrong type for the * operation. */ T_COSE_ERR_WRONG_TYPE_OF_KEY = 20, /** Error constructing the COSE \c Sig_structure when signing or * verify. */ T_COSE_ERR_SIG_STRUCT = 21, /** Signature was short-circuit. The option \ref * T_COSE_OPT_ALLOW_SHORT_CIRCUIT to allow verification of * short-circuit signatures was not set. */ T_COSE_ERR_SHORT_CIRCUIT_SIG = 22, /** Something generally went wrong in the crypto adaptor when * signing or verifying. */ T_COSE_ERR_SIG_FAIL = 23, /** Something went wrong formatting the CBOR. Possibly the * payload has maps or arrays that are not closed when using * t_cose_sign1_encode_parameters() and * t_cose_sign1_encode_signature() to sign a \c COSE_Sign1. */ T_COSE_ERR_CBOR_FORMATTING = 24, /** The buffer passed in to receive the output is too small. */ T_COSE_ERR_TOO_SMALL = 25, /** More parameters (more than \ref T_COSE_PARAMETER_LIST_MAX) * than this implementation can handle. Note that all parameters * need to be checked for criticality so all parameters need to be * examined. */ T_COSE_ERR_TOO_MANY_PARAMETERS = 26, /** A parameter was encountered that was unknown and also listed in * the crit labels parameter. */ T_COSE_ERR_UNKNOWN_CRITICAL_PARAMETER = 27, /** A request was made to signed with a short-circuit sig, \ref * T_COSE_OPT_SHORT_CIRCUIT_SIG, but short circuit signature are * disabled (compiled out) for this implementation. */ T_COSE_ERR_SHORT_CIRCUIT_SIG_DISABLED = 28, /** The key type in a \ref t_cose_key is wrong for the * cryptographic library used by this integration of t_cose. */ T_COSE_ERR_INCORRECT_KEY_FOR_LIB = 29, /** This implementation only handles integer COSE algorithm IDs with * values less than \c INT32_MAX. */ T_COSE_ERR_NON_INTEGER_ALG_ID = 30, /** The content type parameter contains a content type that is * neither integer or text string or it is an integer not in the * range of 0 to \c UINT16_MAX. */ T_COSE_ERR_BAD_CONTENT_TYPE = 31, /** If the option \ref T_COSE_OPT_TAG_REQUIRED is set for * t_cose_sign1_verify() and the tag is absent, this error is * returned. */ T_COSE_ERR_INCORRECTLY_TAGGED = 32, /** The signing or verification key given is empty. */ T_COSE_ERR_EMPTY_KEY = 33, /** A header parameter occurs twice, perhaps once in protected and * once in unprotected. Duplicate header parameters are not * allowed in COSE. */ T_COSE_ERR_DUPLICATE_PARAMETER = 34, /** A header parameter that should be protected (alg id or crit) * is not. This occurs when verifying a \c COSE_Sign1 that is * improperly constructed. */ T_COSE_ERR_PARAMETER_NOT_PROTECTED = 35, /** Something is wrong with the crit parameter. */ T_COSE_ERR_CRIT_PARAMETER = 36, /** * When verifying a \c COSE_Mac0, something is wrong with the * format of the CBOR. For example, it is missing something like * the payload. */ T_COSE_ERR_MAC0_FORMAT = 37, }; /** * The maximum number of header parameters that can be handled during * verification of a \c COSE_Sign1 message. \ref * T_COSE_ERR_TOO_MANY_PARAMETERS will be returned by * t_cose_sign1_verify() if the input message has more. * * There can be both \ref T_COSE_PARAMETER_LIST_MAX integer-labeled * parameters and \ref T_COSE_PARAMETER_LIST_MAX string-labeled * parameters. * * This is a hard maximum so the implementation doesn't need * malloc. This constant can be increased if needed. Doing so will * increase stack usage. */ #define T_COSE_PARAMETER_LIST_MAX 10 /** * The value of an unsigned integer content type indicating no content * type. See \ref t_cose_parameters. */ #define T_COSE_EMPTY_UINT_CONTENT_TYPE UINT16_MAX+1 /** * The result of parsing a set of COSE header parameters. The pointers * are all back into the COSE structure blob passed in. * * Approximate size on a 64-bit machine is 80 bytes and on a 32-bit * machine is 40. */ struct t_cose_parameters { /** The algorithm ID. \ref T_COSE_UNSET_ALGORITHM_ID if the algorithm ID * parameter is not present. String type algorithm IDs are not * supported. See the * [IANA COSE Registry](https://www.iana.org/assignments/cose/cose.xhtml) * for the algorithms corresponding to the integer values. */ int32_t cose_algorithm_id; /** The COSE key ID. \c NULL_Q_USEFUL_BUF_C if parameter is not * present */ struct q_useful_buf_c kid; /** The initialization vector. \c NULL_Q_USEFUL_BUF_C if parameter * is not present */ struct q_useful_buf_c iv; /** The partial initialization vector. \c NULL_Q_USEFUL_BUF_C if * parameter is not present */ struct q_useful_buf_c partial_iv; /** The content type as a MIME type like * "text/plain". \c NULL_Q_USEFUL_BUF_C if parameter is not present */ #ifndef T_COSE_DISABLE_CONTENT_TYPE struct q_useful_buf_c content_type_tstr; /** The content type as a CoAP Content-Format * integer. \ref T_COSE_EMPTY_UINT_CONTENT_TYPE if parameter is not * present. Allowed range is 0 to UINT16_MAX per RFC 7252. */ uint32_t content_type_uint; #endif /* T_COSE_DISABLE_CONTENT_TYPE */ }; /** * An \c option_flag to not add the CBOR type 6 tag for a COSE message. * Some uses of COSE may require this tag be absent because its COSE * message type is known from surrounding context. * * Or said another way, per the COSE RFC, this code produces a \c * COSE_Sign1_Tagged/ \c COSE_Mac0_Tagged by default and * a \c COSE_Sign1/ \c COSE_Mac0 when this flag is set. * The only difference between these two is the CBOR tag. */ #define T_COSE_OPT_OMIT_CBOR_TAG 0x00000002 /** * The error \ref T_COSE_ERR_NO_KID is returned if the kid parameter * is missing. Note that the kid parameter is primarily passed on to * the crypto layer so the crypto layer can look up the key. If the * verification key is determined by other than the kid, then it is * fine if there is no kid. */ #define T_COSE_OPT_REQUIRE_KID 0x00000002 /** * Normally this will decode the CBOR presented as a \c COSE_Sign1 * or a \c COSE_Mac0 message whether it is tagged using QCBOR tagging * as such or not. * If this option is set, then \ref T_COSE_ERR_INCORRECTLY_TAGGED is * returned if it is not tagged. */ #define T_COSE_OPT_TAG_REQUIRED 0x00000004 /** * This option disables cryptographic signature verification. With * this option the \c verification_key is not needed. This is useful * to decode the a COSE message to get the kid (key ID). The * verification key can be looked up or otherwise obtained by the * caller. Once the key in in hand, the verification function can be * called again to perform the full verification. * * The payload will always be returned whether this is option is given * or not, but it should not be considered secure when this option is * given. * */ #define T_COSE_OPT_DECODE_ONLY 0x00000008 #ifdef __cplusplus } #endif #endif /* __T_COSE_COMMON_H__ */