t_cose_common.h File Reference

This file contains definitions common to all public t_cose interfaces. More...

#include <stdint.h>
#include <stdbool.h>

Go to the source code of this file.

Data Structures
struct	t_cose_key

Macros
#define	T_COSE_VERSION_MAJOR   1
#define	T_COSE_VERSION_MINOR   1
#define	T_COSE_VERSION_PATCH   2
#define	T_COSE_ALGORITHM_ES256   -7
	Indicates ECDSA with SHA-256.
#define	T_COSE_ALGORITHM_EDDSA   -8
	Indicates EDDSA, as described by RFC8032.
#define	T_COSE_ALGORITHM_ES384   -35
	Indicates ECDSA with SHA-384.
#define	T_COSE_ALGORITHM_ES512   -36
	Indicates ECDSA with SHA-512.
#define	T_COSE_ALGORITHM_PS256   -37
	Indicates RSASSA-PSS with SHA-256.
#define	T_COSE_ALGORITHM_PS384   -38
	Indicates RSASSA-PSS with SHA-384.
#define	T_COSE_ALGORITHM_PS512   -39
	Indicates RSASSA-PSS with SHA-512.
#define	T_COSE_NULL_KEY    ((struct t_cose_key){T_COSE_CRYPTO_LIB_UNIDENTIFIED, {0}})
#define	T_COSE_SIGN1_MAX_SIZE_PROTECTED_PARAMETERS   (1+1+5+17)
#define	T_COSE_PARAMETER_LIST_MAX   10
#define	T_COSE_EMPTY_UINT_CONTENT_TYPE   UINT16_MAX+1

Enumerations
enum	t_cose_crypto_lib_t { T_COSE_CRYPTO_LIB_UNIDENTIFIED = 0 , T_COSE_CRYPTO_LIB_OPENSSL = 1 , T_COSE_CRYPTO_LIB_PSA = 2 }
enum	t_cose_err_t {   T_COSE_SUCCESS = 0 , T_COSE_ERR_UNSUPPORTED_SIGNING_ALG = 1 , T_COSE_ERR_MAKING_PROTECTED = 2 , T_COSE_ERR_UNSUPPORTED_HASH = 3 ,   T_COSE_ERR_HASH_GENERAL_FAIL = 4 , T_COSE_ERR_HASH_BUFFER_SIZE = 5 , T_COSE_ERR_SIG_BUFFER_SIZE = 6 , T_COSE_ERR_SIGN1_FORMAT = 8 ,   T_COSE_ERR_CBOR_NOT_WELL_FORMED = 9 , T_COSE_ERR_PARAMETER_CBOR = 10 , T_COSE_ERR_NO_ALG_ID = 11 , T_COSE_ERR_NO_KID = 12 ,   T_COSE_ERR_SIG_VERIFY = 13 , T_COSE_ERR_BAD_SHORT_CIRCUIT_KID = 14 , T_COSE_ERR_INVALID_ARGUMENT = 15 , T_COSE_ERR_INSUFFICIENT_MEMORY = 16 ,   T_COSE_ERR_FAIL = 17 , T_COSE_ERR_TAMPERING_DETECTED = 18 , T_COSE_ERR_UNKNOWN_KEY = 19 , T_COSE_ERR_WRONG_TYPE_OF_KEY = 20 ,   T_COSE_ERR_SIG_STRUCT = 21 , T_COSE_ERR_SHORT_CIRCUIT_SIG = 22 , T_COSE_ERR_SIG_FAIL = 23 , T_COSE_ERR_CBOR_FORMATTING = 24 ,   T_COSE_ERR_TOO_SMALL = 25 , T_COSE_ERR_TOO_MANY_PARAMETERS = 26 , T_COSE_ERR_UNKNOWN_CRITICAL_PARAMETER = 27 , T_COSE_ERR_SHORT_CIRCUIT_SIG_DISABLED = 28 ,   T_COSE_ERR_INCORRECT_KEY_FOR_LIB = 29 , T_COSE_ERR_NON_INTEGER_ALG_ID = 30 , T_COSE_ERR_BAD_CONTENT_TYPE = 31 , T_COSE_ERR_INCORRECTLY_TAGGED = 32 ,   T_COSE_ERR_EMPTY_KEY = 33 , T_COSE_ERR_DUPLICATE_PARAMETER = 34 , T_COSE_ERR_PARAMETER_NOT_PROTECTED = 35 , T_COSE_ERR_CRIT_PARAMETER = 36 ,   T_COSE_ERR_TOO_MANY_TAGS = 37 , T_COSE_ERR_NEED_AUXILIARY_BUFFER = 38 , T_COSE_ERR_AUXILIARY_BUFFER_SIZE = 39 }

Functions
bool	t_cose_is_algorithm_supported (int32_t cose_algorithm_id)
	Check whether an algorithm is supported.

Detailed Description

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

T_COSE_DISABLE_SHORT_CIRCUIT_SIGN – This disables short-circuit signing test mode. This saves a small amount of object code

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 T_COSE_DISABLE_ES384.

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 T_COSE_DISABLE_ES512 is not also defined.

T_COSE_DISABLE_PS256 – Disables the COSE algorithm PS256 algorithm.

T_COSE_DISABLE_PS384 – Disables the COSE algorithm PS384 algorithm.

T_COSE_DISABLE_PS512 – Disables the COSE algorithm PS512 algorithm.

T_COSE_DISABLE_CONTENT_TYPE – Disables the content type parameters for both signing and verifying.

Macro Definition Documentation

T_COSE_ALGORITHM_EDDSA

#define T_COSE_ALGORITHM_EDDSA   -8

Indicates EDDSA, as described by RFC8032.

This value comes from the IANA COSE Registry.

Keys using either the edwards25519 or edwards448 curves can be used with this algorithm.

T_COSE_ALGORITHM_ES256

#define T_COSE_ALGORITHM_ES256   -7

Indicates ECDSA with SHA-256.

This value comes from the IANA COSE Registry.

The COSE standard recommends a key using the secp256r1 curve with this algorithm. This curve is also known as prime256v1 and P-256.

T_COSE_ALGORITHM_ES384

#define T_COSE_ALGORITHM_ES384   -35

Indicates ECDSA with SHA-384.

This value comes from the IANA COSE Registry.

The COSE standard recommends a key using the secp384r1 curve with this algorithm. This curve is also known as P-384.

T_COSE_ALGORITHM_ES512

#define T_COSE_ALGORITHM_ES512   -36

Indicates ECDSA with SHA-512.

This value comes from the IANA COSE Registry.

The COSE standard recommends a key using the secp521r1 curve with this algorithm. This curve is also known as P-521.

T_COSE_ALGORITHM_PS256

#define T_COSE_ALGORITHM_PS256   -37

Indicates RSASSA-PSS with SHA-256.

This value comes from the IANA COSE Registry.

T_COSE_ALGORITHM_PS384

#define T_COSE_ALGORITHM_PS384   -38

Indicates RSASSA-PSS with SHA-384.

This value comes from the IANA COSE Registry.

T_COSE_ALGORITHM_PS512

#define T_COSE_ALGORITHM_PS512   -39

Indicates RSASSA-PSS with SHA-512.

This value comes from the IANA COSE Registry.

T_COSE_EMPTY_UINT_CONTENT_TYPE

#define T_COSE_EMPTY_UINT_CONTENT_TYPE   UINT16_MAX+1

The value of an unsigned integer content type indicating no content type. See t_cose_parameters.

T_COSE_NULL_KEY

#define T_COSE_NULL_KEY    ((struct t_cose_key){T_COSE_CRYPTO_LIB_UNIDENTIFIED, {0}})

An empty or NULL t_cose_key

T_COSE_PARAMETER_LIST_MAX

#define T_COSE_PARAMETER_LIST_MAX   10

The maximum number of header parameters that can be handled during verification of a COSE_Sign1 message. T_COSE_ERR_TOO_MANY_PARAMETERS will be returned by t_cose_sign1_verify() if the input message has more.

There can be both T_COSE_PARAMETER_LIST_MAX integer-labeled parameters and 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.

T_COSE_VERSION_MAJOR

#define T_COSE_VERSION_MAJOR   1

Semantic versioning for t_cose x.y.z. Note that these were not defined for some releases of t_cose 1.x so !defined(T_COSE_VERSION_MAJOR) indicates t_cose 1.x.

Enumeration Type Documentation

t_cose_crypto_lib_t

enum t_cose_crypto_lib_t

Indicates the cryptographic library the t_cose_key is intended for. Usually only one cryptographic library is integrated so this serves as a cross-check.

Enumerator
T_COSE_CRYPTO_LIB_UNIDENTIFIED	can be used for integrations that don't have or don't want to have any cross-check.
T_COSE_CRYPTO_LIB_OPENSSL	key_ptr points to a malloced OpenSSL EC_KEY. The caller needs to free it after the operation is done.
T_COSE_CRYPTO_LIB_PSA	key_handle is a psa_key_handle_t in Arm's Platform Security Architecture

t_cose_err_t

enum t_cose_err_t

Error codes return by t_cose.

Enumerator
T_COSE_SUCCESS	Operation completed successfully.
T_COSE_ERR_UNSUPPORTED_SIGNING_ALG	The requested signing algorithm is not supported.
T_COSE_ERR_MAKING_PROTECTED	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_UNSUPPORTED_HASH	The hash algorithm needed is not supported. Note that the signing algorithm identifier identifies the hash algorithm.
T_COSE_ERR_HASH_GENERAL_FAIL	Some system failure when running the hash algorithm.
T_COSE_ERR_HASH_BUFFER_SIZE	The buffer to receive a hash result is too small.
T_COSE_ERR_SIG_BUFFER_SIZE	The buffer to receive result of a signing operation is too small.
T_COSE_ERR_SIGN1_FORMAT	When verifying a 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_CBOR_NOT_WELL_FORMED	When decoding some CBOR like a 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_PARAMETER_CBOR	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_NO_ALG_ID	No algorithm ID was found when one is needed. For example, when verifying a COSE_Sign1.
T_COSE_ERR_NO_KID	No kid (key ID) was found when one is needed. For example, when verifying a COSE_Sign1.
T_COSE_ERR_SIG_VERIFY	Signature verification failed. For example, the cryptographic operations completed successfully but hash wasn't as expected.
T_COSE_ERR_BAD_SHORT_CIRCUIT_KID	Verification of a short-circuit signature failed.
T_COSE_ERR_INVALID_ARGUMENT	Some (unspecified) argument was not valid.
T_COSE_ERR_INSUFFICIENT_MEMORY	Out of heap memory. This originates in crypto library as t_cose does not use malloc.
T_COSE_ERR_FAIL	General unspecific failure.
T_COSE_ERR_TAMPERING_DETECTED	Equivalent to PSA_ERROR_CORRUPTION_DETECTED.
T_COSE_ERR_UNKNOWN_KEY	The key identified by a t_cose_key or a key ID was not found.
T_COSE_ERR_WRONG_TYPE_OF_KEY	The key was found, but it was the wrong type for the operation.
T_COSE_ERR_SIG_STRUCT	Error constructing the COSE Sig_structure when signing or verify.
T_COSE_ERR_SHORT_CIRCUIT_SIG	Signature was short-circuit. The option T_COSE_OPT_ALLOW_SHORT_CIRCUIT to allow verification of short-circuit signatures was not set.
T_COSE_ERR_SIG_FAIL	Something generally went wrong in the crypto adaptor when signing or verifying.
T_COSE_ERR_CBOR_FORMATTING	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 COSE_Sign1.
T_COSE_ERR_TOO_SMALL	The buffer passed in to receive the output is too small.
T_COSE_ERR_TOO_MANY_PARAMETERS	More parameters (more than 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_UNKNOWN_CRITICAL_PARAMETER	A parameter was encountered that was unknown and also listed in the crit labels parameter.
T_COSE_ERR_SHORT_CIRCUIT_SIG_DISABLED	A request was made to signed with a short-circuit sig, T_COSE_OPT_SHORT_CIRCUIT_SIG, but short circuit signature are disabled (compiled out) for this implementation.
T_COSE_ERR_INCORRECT_KEY_FOR_LIB	The key type in a t_cose_key is wrong for the cryptographic library used by this integration of t_cose.
T_COSE_ERR_NON_INTEGER_ALG_ID	This implementation only handles integer COSE algorithm IDs with values less than INT32_MAX.
T_COSE_ERR_BAD_CONTENT_TYPE	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 UINT16_MAX.
T_COSE_ERR_INCORRECTLY_TAGGED	If the option T_COSE_OPT_TAG_REQUIRED is set for t_cose_sign1_verify() and the tag is absent, this error is returned.
T_COSE_ERR_EMPTY_KEY	The signing or verification key given is empty.
T_COSE_ERR_DUPLICATE_PARAMETER	A header parameter occurs twice, perhaps once in protected and once in unprotected. Duplicate header parameters are not allowed in COSE.
T_COSE_ERR_PARAMETER_NOT_PROTECTED	A header parameter that should be protected (alg id or crit) is not. This occurs when verifying a COSE_Sign1 that is improperly constructed.
T_COSE_ERR_CRIT_PARAMETER	Something is wrong with the crit parameter.
T_COSE_ERR_TOO_MANY_TAGS	More than T_COSE_MAX_TAGS_TO_RETURN unprocessed tags when verifying a signature.
T_COSE_ERR_NEED_AUXILIARY_BUFFER	The signature algorithm needs an extra buffer, but none was provided. See t_cose_sign1_verify_set_auxiliary_buffer for more details.
T_COSE_ERR_AUXILIARY_BUFFER_SIZE	The auxiliary buffer is too small

Function Documentation

t_cose_is_algorithm_supported()

bool t_cose_is_algorithm_supported

(

int32_t

cose_algorithm_id

)

Check whether an algorithm is supported.

Parameters

[in]

cose_algorithm_id

COSE Integer algorithm ID.

Returns

true if algorithm is supported, false if not.

Algorithms identifiers are from COSE algorithm registry: https://www.iana.org/assignments/cose/cose.xhtml#algorithms

A primary use for this is to determine whether or not to run a test case. It is often unneccessary for regular use, because all the APIs will return T_COSE_ERR_UNSUPPORTED_XXXX if the algorithm is not supported.