Create a COSE_Sign1 message, such as for EAT or CWT Token. More...

#include <stdint.h>
#include <stdbool.h>
#include "qcbor/qcbor.h"
#include "t_cose/q_useful_buf.h"
#include "t_cose/t_cose_common.h"

Data Structures
struct	t_cose_sign1_sign_ctx

Macros
#define	T_COSE_OPT_SHORT_CIRCUIT_SIG 0x00000001

#define	T_COSE_OPT_OMIT_CBOR_TAG 0x00000002

Functions
static void	t_cose_sign1_sign_init (struct t_cose_sign1_sign_ctx *context, uint32_t option_flags, int32_t cose_algorithm_id)
	Initialize to start creating a `COSE_Sign1`.

static void	t_cose_sign1_set_signing_key (struct t_cose_sign1_sign_ctx *context, struct t_cose_key signing_key, struct q_useful_buf_c kid)
	Set the key and kid (key ID) for signing.

static void	t_cose_sign1_sign_set_auxiliary_buffer (struct t_cose_sign1_sign_ctx *context, struct q_useful_buf auxiliary_buffer)
	Configure an auxiliary buffer used to serialize the Sig_Structure.

static size_t	t_cose_sign1_sign_auxiliary_buffer_size (struct t_cose_sign1_sign_ctx *context)
	Get the required auxiliary buffer size for the most recent signing operation.

static void	t_cose_sign1_set_content_type_uint (struct t_cose_sign1_sign_ctx *context, uint16_t content_type)
	Set the payload content type using CoAP content types.

static void	t_cose_sign1_set_content_type_tstr (struct t_cose_sign1_sign_ctx context, const char content_type)
	Set the payload content type using MIME content types.

static enum t_cose_err_t	t_cose_sign1_sign (struct t_cose_sign1_sign_ctx context, struct q_useful_buf_c payload, struct q_useful_buf out_buf, struct q_useful_buf_c result)
	Create and sign a `COSE_Sign1` message with a payload in one call.

static enum t_cose_err_t	t_cose_sign1_sign_aad (struct t_cose_sign1_sign_ctx context, struct q_useful_buf_c aad, struct q_useful_buf_c payload, struct q_useful_buf out_buf, struct q_useful_buf_c result)
	Create and sign a `COSE_Sign1` message with a payload in one call.

static enum t_cose_err_t	t_cose_sign1_sign_detached (struct t_cose_sign1_sign_ctx context, struct q_useful_buf_c aad, struct q_useful_buf_c detached_payload, struct q_useful_buf out_buf, struct q_useful_buf_c result)
	Create and sign a `COSE_Sign1` message with detached payload in one call.

static enum t_cose_err_t	t_cose_sign1_encode_parameters (struct t_cose_sign1_sign_ctx context, QCBOREncodeContext cbor_encode_ctx)
	Output first part and parameters for a `COSE_Sign1` message.

static enum t_cose_err_t	t_cose_sign1_encode_signature (struct t_cose_sign1_sign_ctx context, QCBOREncodeContext cbor_encode_ctx)
	Finish a `COSE_Sign1` message by outputting the signature.

static enum t_cose_err_t	t_cose_sign1_encode_signature_aad (struct t_cose_sign1_sign_ctx context, struct q_useful_buf_c aad, QCBOREncodeContext cbor_encode_ctx)
	Finish a `COSE_Sign1` message with AAD by outputting the signature.

enum t_cose_err_t	t_cose_sign1_encode_parameters_internal (struct t_cose_sign1_sign_ctx context, bool payload_is_detached, QCBOREncodeContext cbor_encode_ctx)
	Semi-private function that ouputs the COSE parameters, startng a `COSE_Sign1` message.

enum t_cose_err_t	t_cose_sign1_encode_signature_aad_internal (struct t_cose_sign1_sign_ctx context, struct q_useful_buf_c aad, struct q_useful_buf_c detached_payload, QCBOREncodeContext cbor_encode_ctx)
	Semi-private function that ouputs the signature, finishing a `COSE_Sign1` message.

enum t_cose_err_t	t_cose_sign1_sign_aad_internal (struct t_cose_sign1_sign_ctx context, bool payload_is_detached, struct q_useful_buf_c aad, struct q_useful_buf_c payload, struct q_useful_buf out_buf, struct q_useful_buf_c result)
	Semi-private function that does a complete signing in one call.

Detailed Description

Create a COSE_Sign1 message, such as for EAT or CWT Token.

This creates a COSE_Sign1 message in compliance with COSE (RFC 8152). A COSE_Sign1 message is a CBOR encoded binary blob that contains header parameters, a payload and a signature. Usually the signature is made with an EC signing algorithm like ECDSA.

This implementation is intended to be small and portable to different OS's and platforms. Its dependencies are:

QCBOR
<stdint.h>, <string.h>, <stddef.h>
Hash functions like SHA-256
Signing functions like ECDSA

There is a cryptographic adaptation layer defined in t_cose_crypto.h. An implementation can be made of the functions in it for different cryptographic libraries. This means that different integrations with different cryptographic libraries may support only signing with a particular set of algorithms. Integration with OpenSSL is supported. Key ID look up also varies by different cryptographic library integrations.

This implementation has a mode where a CBOR-format payload can be output directly into the output buffer. This saves having two copies of the payload in memory. For this mode use t_cose_sign1_encode_parameters() and t_cose_sign1_encode_signature(). For a simpler API that just takes the payload as an input buffer use t_cose_sign1_sign().

See t_cose_common.h for preprocessor defines to reduce object code and stack use by disabling features.

Macro Definition Documentation

◆ T_COSE_OPT_OMIT_CBOR_TAG

#define T_COSE_OPT_OMIT_CBOR_TAG 0x00000002

An option_flag for t_cose_sign1_sign_init() to not add the CBOR type 6 tag for COSE_Sign1 whose value is 18. Some uses of COSE may require this tag be absent because it is known that it is a COSE_Sign1 from surrounding context.

Or said another way, per the COSE RFC, this code produces a COSE_Sign1_Tagged by default and a COSE_Sign1 when this flag is set. The only difference between these two is the CBOR tag.

◆ T_COSE_OPT_SHORT_CIRCUIT_SIG

#define T_COSE_OPT_SHORT_CIRCUIT_SIG 0x00000001

This selects a signing test mode called short circuit signing. This mode is useful when there is no signing key available, perhaps because it has not been provisioned or configured for the particular device. It may also be because the public key cryptographic functions have not been connected up in the cryptographic adaptation layer.

It has no value for security at all. Data signed this way MUST NOT be trusted as anyone can sign like this.

In this mode, the signature is the hash of that which would normally be signed by the public key algorithm. To make the signature the correct size for the particular algorithm, instances of the hash are concatenated to pad it out.

This mode is very useful for testing because all the code except the actual signing algorithm is run exactly as it would if a proper signing algorithm was run. This can be used for end-end system testing all the way to a server or relying party, not just for testing device code as t_cose_sign1_verify() supports it too.

Function Documentation

◆ t_cose_sign1_encode_parameters()

static enum t_cose_err_t t_cose_sign1_encode_parameters	(	struct t_cose_sign1_sign_ctx *	context,
		QCBOREncodeContext *	cbor_encode_ctx )

inlinestatic

Output first part and parameters for a COSE_Sign1 message.

Parameters

[in]	context	The t_cose signing context.
[in]	cbor_encode_ctx	Encoding context to output to.

This is the more complex and more memory efficient alternative to t_cose_sign1_sign(). Like t_cose_sign1_sign(), t_cose_sign1_sign_init() and t_cose_sign1_set_signing_key() must be called before calling this.

When this is called, the opening parts of the COSE_Sign1 message are output to the cbor_encode_ctx.

After this is called, the CBOR-formatted payload must be written to the cbor_encode_ctx by calling all the various QCBOREncode_AddXxx calls. It can be as simple or complex as needed.

To complete the COSE_Sign1 call t_cose_sign1_encode_signature().

The cbor_encode_ctx must have been initialized with an output buffer to hold the COSE_Sign1 header parameters, the payload and the signature.

This and t_cose_sign1_encode_signature() can be used to calculate the size of the COSE_Sign1 in the way QCBOREncode is usually used to calculate sizes. In this case the t_cose_sign1_ctx must be initialized with the options, algorithm, key and kid just as normal as these are needed to calculate the size. Then set up the output buffer for cbor_encode_ctx with a NULL pointer and large length like UINT32_MAX. Call t_cose_sign1_encode_parameters(), then format the payload into the encoder context, then call t_cose_sign1_encode_signature(). Finally call QCBOREncode_FinishGetSize() to get the length.

◆ t_cose_sign1_encode_parameters_internal()

enum t_cose_err_t t_cose_sign1_encode_parameters_internal	(	struct t_cose_sign1_sign_ctx *	context,
		bool	payload_is_detached,
		QCBOREncodeContext *	cbor_encode_ctx )

Semi-private function that ouputs the COSE parameters, startng a COSE_Sign1 message.

Parameters

[in]	context	The t_cose signing context.
[in]	payload_is_detached	If the payload is to be detached, this is `true`.
[in]	cbor_encode_ctx	Encoding context to output to.

Returns: This returns one of the error codes defined by t_cose_err_t.

This does the actual work for encoding the COSE parameters, but is a private function inside the implementation. Call t_cose_sign1_encode_parameters() instead of this.

◆ t_cose_sign1_encode_signature()

static enum t_cose_err_t t_cose_sign1_encode_signature	(	struct t_cose_sign1_sign_ctx *	context,
		QCBOREncodeContext *	cbor_encode_ctx )

inlinestatic

Finish a COSE_Sign1 message by outputting the signature.

Parameters

[in]	context	The t_cose signing context.
[in]	cbor_encode_ctx	Encoding context to output to.

Returns: This returns one of the error codes defined by t_cose_err_t.

Call this to complete creation of a signed COSE_Sign1 started with t_cose_sign1_encode_parameters().

This is when the cryptographic signature algorithm is run.

The completed COSE_Sign1 message is retrieved from the cbor_encode_ctx by calling QCBOREncode_Finish().

◆ t_cose_sign1_encode_signature_aad()

static enum t_cose_err_t t_cose_sign1_encode_signature_aad	(	struct t_cose_sign1_sign_ctx *	context,
		struct q_useful_buf_c	aad,
		QCBOREncodeContext *	cbor_encode_ctx )

inlinestatic

Finish a COSE_Sign1 message with AAD by outputting the signature.

Parameters

[in]	context	The t_cose signing context.
[in]	aad	The Additional Authenticated Data.
[in]	cbor_encode_ctx	Encoding context to output to.

Returns: This returns one of the error codes defined by t_cose_err_t.

This is the same as t_cose_sign1_encode_signature() and it allows passing in AAD (Additional Authenticated Data) to be covered by the signature.

AAD is simply any data that should also be covered by the signature. The verifier of the COSE_Sign1 must also have exactly this data to be able to successfully verify the signature. Often this data is some parameters or fields in the protocol carrying the COSE message.

◆ t_cose_sign1_encode_signature_aad_internal()

enum t_cose_err_t t_cose_sign1_encode_signature_aad_internal	(	struct t_cose_sign1_sign_ctx *	context,
		struct q_useful_buf_c	aad,
		struct q_useful_buf_c	detached_payload,
		QCBOREncodeContext *	cbor_encode_ctx )

Semi-private function that ouputs the signature, finishing a COSE_Sign1 message.

Parameters

[in]	context	The t_cose signing context.
[in]	aad	The Additional Authenticated Data or `NULL_Q_USEFUL_BUF_C`.
[in]	detached_payload	The detached payload or `NULL_Q_USEFUL_BUF_C`.
[in]	cbor_encode_ctx	Encoding context to output to.

Returns: This returns one of the error codes defined by t_cose_err_t.

This does the actual work for several public methods that output a signature. It is internal to the implmentation and t_cose_sign1_encode_signature_aad() should be called instead.

If detached_payload is NULL_Q_USEFUL_BUF_C then the payload is to be inline and must have been added by calls to QCBOREncode after the call to t_cose_sign1_encode_parameters().

◆ t_cose_sign1_set_content_type_tstr()

static void t_cose_sign1_set_content_type_tstr	(	struct t_cose_sign1_sign_ctx *	context,
		const char *	content_type )

inlinestatic

Set the payload content type using MIME content types.

Parameters

[in]	context	The t_cose signing context.
[in]	content_type	The content type of the payload as defined in the IANA Media Types registry.

It is not allowed to have both a CoAP and MIME content type. This error will show up when t_cose_sign1_sign() or t_cose_sign1_encode_parameters() is called.

The IANA Media Types registry can be found here. These have been known as MIME types in the past.

◆ t_cose_sign1_set_content_type_uint()

static void t_cose_sign1_set_content_type_uint	(	struct t_cose_sign1_sign_ctx *	context,
		uint16_t	content_type )

inlinestatic

Set the payload content type using CoAP content types.

Parameters

[in]	context	The t_cose signing context.
[in]	content_type	The content type of the payload as defined in the IANA CoAP Content-Formats registry.

It is not allowed to have both a CoAP and MIME content type. This error will show up when t_cose_sign1_sign() or t_cose_sign1_encode_parameters() is called as no error is returned by this function.

The IANA CoAP Content-Formats registry is found here.

◆ t_cose_sign1_set_signing_key()

static void t_cose_sign1_set_signing_key	(	struct t_cose_sign1_sign_ctx *	context,
		struct t_cose_key	signing_key,
		struct q_useful_buf_c	kid )

inlinestatic

Set the key and kid (key ID) for signing.

Parameters

[in]	context	The t_cose signing context.
[in]	signing_key	The signing key to use or T_COSE_NULL_KEY.
[in]	kid	COSE kid (key ID) parameter or `NULL_Q_USEFUL_BUF_C`.

This needs to be called to set the signing key to use. The kid may be omitted by giving NULL_Q_USEFUL_BUF_C.

If short-circuit signing is used, T_COSE_OPT_SHORT_CIRCUIT_SIG, then this does not need to be called. If it is called the kid given will be used, but the signing_key is never used. When the kid is given with a short-circuit signature, the internally fixed kid for short circuit will not be used and this COSE_Sign1 message can not be verified by t_cose_sign1_verify().

◆ t_cose_sign1_sign()

static enum t_cose_err_t t_cose_sign1_sign	(	struct t_cose_sign1_sign_ctx *	context,
		struct q_useful_buf_c	payload,
		struct q_useful_buf	out_buf,
		struct q_useful_buf_c *	result )

inlinestatic

Create and sign a COSE_Sign1 message with a payload in one call.

Parameters

[in]	context	The t_cose signing context.
[in]	payload	Pointer and length of payload to sign.
[in]	out_buf	Pointer and length of buffer to output to.
[out]	result	Pointer and length of the resulting `COSE_Sign1`.

The context must have been initialized with t_cose_sign1_sign_init() and the key set with t_cose_sign1_set_signing_key() before this is called.

This creates the COSE header parameter, hashes and signs the payload and creates the signature all in one go. out_buf gives the pointer and length of the memory into which the output is written. The pointer and length of the completed COSE_Sign1 is returned in result. (out_buf and result are used instead of the usual in/out parameter for length because it is the convention for q_useful_buf and is more const correct.)

The size of out_buf must be the size of the payload plus overhead for formating, the signature and the key id (if used). The formatting overhead is minimal at about 30 bytes.The total overhead is about 150 bytes for ECDSA 256 with a 32-byte key ID.

To compute the size of the buffer needed before it is allocated call this with out_buf containing a NULL pointer and large length like UINT32_MAX. The algorithm and key, kid and such must be set up just as if the real COSE_Sign1 were to be created as these values are needed to compute the size correctly. The contents of result will be a NULL pointer and the length of the COSE_Sign1. When this is run like this, the cryptographic functions will not actually run, but the size of their output will be taken into account to give an exact size.

This function requires the payload be complete and formatted in a contiguous buffer. The resulting COSE_Sign1 message also contains the payload preceded by the header parameters and followed by the signature, all CBOR formatted. This function thus requires two copies of the payload to be in memory. Alternatively t_cose_sign1_encode_parameters() and t_cose_sign1_encode_signature() can be used. They are more complex to use, but avoid the two copies of the payload and can reduce memory requirements by close to half.

◆ t_cose_sign1_sign_aad()

static enum t_cose_err_t t_cose_sign1_sign_aad	(	struct t_cose_sign1_sign_ctx *	context,
		struct q_useful_buf_c	aad,
		struct q_useful_buf_c	payload,
		struct q_useful_buf	out_buf,
		struct q_useful_buf_c *	result )

inlinestatic

Create and sign a COSE_Sign1 message with a payload in one call.

Parameters

[in]	context	The t_cose signing context.
[in]	aad	The Additional Authenticated Data or `NULL_Q_USEFUL_BUF_C`.
[in]	payload	Pointer and length of payload to sign.
[in]	out_buf	Pointer and length of buffer to output to.
[out]	result	Pointer and length of the resulting `COSE_Sign1`.

This is the same as t_cose_sign1_sign() additionally allowing AAD. AAD (Additional Authenticated Data) is extra bytes to be covered by the signature. See t_cose_sign1_encode_signature_aad() for more details about AAD.

Calling this with aad as NULL_Q_USEFUL_BUF_C is equivalent to t_cose_sign1_sign().

◆ t_cose_sign1_sign_aad_internal()

enum t_cose_err_t t_cose_sign1_sign_aad_internal	(	struct t_cose_sign1_sign_ctx *	context,
		bool	payload_is_detached,
		struct q_useful_buf_c	aad,
		struct q_useful_buf_c	payload,
		struct q_useful_buf	out_buf,
		struct q_useful_buf_c *	result )

Semi-private function that does a complete signing in one call.

Parameters

[in]	context	The t_cose signing context.
[in]	payload_is_detached	If `true`, then `payload` is detached.
[in]	payload	The payload, inline or detached.
[in]	aad	The Additional Authenticated Data or `NULL_Q_USEFUL_BUF_C`.
[in]	out_buf	Pointer and length of buffer to output to.
[out]	result	Pointer and length of the resulting `COSE_Sign1`.

Returns: This returns one of the error codes defined by t_cose_err_t.

This is where the work actually gets done for signing that is done all in one call with or without AAD and for included or detached payloads.

This is a private function internal to the implementation. Call t_cose_sign1_sign_aad() instead of this.

◆ t_cose_sign1_sign_auxiliary_buffer_size()

static size_t t_cose_sign1_sign_auxiliary_buffer_size ( struct t_cose_sign1_sign_ctx * context )

inlinestatic

Get the required auxiliary buffer size for the most recent signing operation.

Parameters

[in] context The t_cose signing context.

Returns: The number of bytes of auxiliary buffer used by the most recent signing operation.

This function can be called after t_cose_sign1_sign (or equivalent) was called. If a NULL output buffer was passed to the signing function (to operate in size calculation mode), this returns the number of bytes that would have been used by the signing operation. This allows the caller to allocate an appropriately sized buffer before performing the actual verification.

This function returns if the signature algorithm used does not need an auxiliary buffer.

◆ t_cose_sign1_sign_detached()

static enum t_cose_err_t t_cose_sign1_sign_detached	(	struct t_cose_sign1_sign_ctx *	context,
		struct q_useful_buf_c	aad,
		struct q_useful_buf_c	detached_payload,
		struct q_useful_buf	out_buf,
		struct q_useful_buf_c *	result )

inlinestatic

Create and sign a COSE_Sign1 message with detached payload in one call.

Parameters

[in]	context	The t_cose signing context.
[in]	aad	The Additional Authenticated Data or `NULL_Q_USEFUL_BUF_C`.
[in]	detached_payload	Pointer and length of the detached payload to sign.
[in]	out_buf	Pointer and length of buffer to output to.
[out]	result	Pointer and length of the resulting `COSE_Sign1`.

This is similar to, but not the same as t_cose_sign1_sign_aad(). Here the payload is detached, not inside the COSE_Sign1 and conveyed separately. The signature is still over the payload as with t_cose_sign1_sign_aad(). They payload must conveyed to recipient by some other means than by being inside the COSE_Sign1. The recipient will be unable to verify the COSE_Sign1 without it.

This may be called with aad as NULL_Q_USEFUL_BUF_C if there is no AAD.

◆ t_cose_sign1_sign_init()

static void t_cose_sign1_sign_init	(	struct t_cose_sign1_sign_ctx *	context,
		uint32_t	option_flags,
		int32_t	cose_algorithm_id )

inlinestatic

Initialize to start creating a COSE_Sign1.

Parameters

[in]	context	The t_cose signing context.
[in]	option_flags	One of `T_COSE_OPT_XXXX`.
[in]	cose_algorithm_id	The algorithm to sign with, for example T_COSE_ALGORITHM_ES256.

Initialize the t_cose_sign1_sign_ctx context. Typically, no option_flags are needed and 0 can be passed. A cose_algorithm_id must always be given. See T_COSE_OPT_SHORT_CIRCUIT_SIG and related for possible option flags.

The algorithm ID space is from COSE (RFC8152) and the IANA COSE Registry. T_COSE_ALGORITHM_ES256 and a few others are defined here for convenience. The signing algorithms supported depends on the cryptographic library that t_cose is integrated with.

Errors such as the passing of an unsupported cose_algorithm_id are reported when t_cose_sign1_sign() or t_cose_sign1_encode_parameters() is called.

◆ t_cose_sign1_sign_set_auxiliary_buffer()

static void t_cose_sign1_sign_set_auxiliary_buffer	(	struct t_cose_sign1_sign_ctx *	context,
		struct q_useful_buf	auxiliary_buffer )

inlinestatic

Configure an auxiliary buffer used to serialize the Sig_Structure.

Parameters

[in]	context	The t_cose signing context.
[in]	auxiliary_buffer	The buffer used to serialize the Sig_Structure.

Some signature algorithms (namely EdDSA), require two passes over their input. In order to achieve this, the library needs to serialize a temporary to-be-signed structure into an auxiliary buffer. This function allows the user to configure such a buffer.

The buffer must be big enough to accomodate the Sig_Structure type, which is roughly the sum of sizes of the encoded protected parameters, aad and payload, along with a few dozen bytes of overhead.

To compute the exact size needed, an auxiliary buffer with a NULL pointer and a large size, such as UINT32_MAX, can be used. No actual signing will take place, but the auxiliary buffer will be shrunk to the to expected size.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ T_COSE_OPT_OMIT_CBOR_TAG

◆ T_COSE_OPT_SHORT_CIRCUIT_SIG

Function Documentation

◆ t_cose_sign1_encode_parameters()

◆ t_cose_sign1_encode_parameters_internal()

◆ t_cose_sign1_encode_signature()

◆ t_cose_sign1_encode_signature_aad()

◆ t_cose_sign1_encode_signature_aad_internal()

◆ t_cose_sign1_set_content_type_tstr()

◆ t_cose_sign1_set_content_type_uint()

◆ t_cose_sign1_set_signing_key()

◆ t_cose_sign1_sign()

◆ t_cose_sign1_sign_aad()

◆ t_cose_sign1_sign_aad_internal()

◆ t_cose_sign1_sign_auxiliary_buffer_size()

◆ t_cose_sign1_sign_detached()

◆ t_cose_sign1_sign_init()

◆ t_cose_sign1_sign_set_auxiliary_buffer()