This is the adaptation layer for cryptographic functions used by t_cose. More...

#include "t_cose_common.h"
#include "useful_buf.h"
#include <stdint.h>
#include "t_cose_defines.h"

Data Structures
struct	t_cose_crypto_hash
	The context for use with the hash adaptation layer here. More...

Macros
#define	T_COSE_EC_P256_SIG_SIZE 64
	Size of the signature output for the NIST P-256 Curve. More...

#define	T_COSE_MAX_EC_SIG_SIZE T_COSE_EC_P256_SIG_SIZE
	Size of the largest signature of any of the algorithm types supported. More...

#define	T_COSE_CRYPTO_EC_P256_COORD_SIZE 32
	The size of X and Y coordinate in 2 parameter style EC public key. More...

#define	T_COSE_CRYPTO_SHA256_SIZE 32
	The size of the output of SHA-256 in bytes. More...

Functions
enum t_cose_err_t	t_cose_crypto_pub_key_sign (int32_t cose_alg_id, int32_t key_select, struct useful_buf_c hash_to_sign, struct useful_buf signature_buffer, struct useful_buf_c *signature)
	Perform public key signing. More...

enum t_cose_err_t	t_cose_crypto_pub_key_verify (int32_t cose_alg_id, int32_t key_select, struct useful_buf_c key_id, struct useful_buf_c hash_to_verify, struct useful_buf_c signature)
	perform public key signature verification. More...

enum t_cose_err_t	t_cose_crypto_get_ec_pub_key (int32_t key_select, struct useful_buf_c kid, int32_t cose_curve_id, struct useful_buf buf_to_hold_x_coord, struct useful_buf buf_to_hold_y_coord, struct useful_buf_c x_coord, struct useful_buf_c *y_coord)
	Get an elliptic curve public key. More...

enum t_cose_err_t	t_cose_crypto_hash_start (struct t_cose_crypto_hash *hash_ctx, int32_t cose_hash_alg_id)
	Start cryptographic hash. More...

void	t_cose_crypto_hash_update (struct t_cose_crypto_hash *hash_ctx, struct useful_buf_c data_to_hash)
	Feed data into a cryptographic hash. More...

enum t_cose_err_t	t_cose_crypto_hash_finish (struct t_cose_crypto_hash hash_ctx, struct useful_buf buffer_to_hold_result, struct useful_buf_c hash_result)
	Finish a cryptographic hash. More...

Detailed Description

This is the adaptation layer for cryptographic functions used by t_cose.

This is small wrapper around the cryptographic functions to:

Map COSE algorithm IDs to TF-M algorithm IDs
Map crypto errors to t_cose_err_t errors
Have inputs and outputs be struct useful_buf_c and struct useful_buf
Handle key selection

The idea is that implementations can be made of these functions that adapt to various cryptographic libraries that are used on various platforms and OSs.

This runs entirely off of COSE-style algorithm identifiers. They are simple integers and thus work nice as function parameters. An initial set is defined by [COSE (RFC 8152)] (https://tools.ietf.org/html/rfc8152). New ones can be registered in the [IANA COSE Registry] (https://www.iana.org/assignments/cose/cose.xhtml). Local use new ones can also be defined (#define) if what is needed is not in the IANA registry.

Binary data is returned to the caller using a struct useful_buf to pass the buffer to receive the data and its length in and a useful_buf_c to return the pointer and length of the returned data. The point of this is coding hygiene. The buffer passed in is not const as it is to be modified. The useful_buf_c returned is const.

The pointer in the useful_buf_c will always point to the buffer passed in via the useful_buf so the lifetime of the data is under control of the caller.

This is not intended as any sort of general cryptographic API. It is just the functions needed by t_cose in the form that is most useful for t_cose.

Definition in file t_cose_crypto.h.

Macro Definition Documentation

◆ T_COSE_EC_P256_SIG_SIZE

#define T_COSE_EC_P256_SIG_SIZE 64

Size of the signature output for the NIST P-256 Curve.

Definition at line 67 of file t_cose_crypto.h.

◆ T_COSE_MAX_EC_SIG_SIZE

#define T_COSE_MAX_EC_SIG_SIZE T_COSE_EC_P256_SIG_SIZE

Size of the largest signature of any of the algorithm types supported.

This will have to be adjusted if support for other algorithms larger is added.

This is a compile time constant so it can be used to define stack variable sizes.

Definition at line 79 of file t_cose_crypto.h.

◆ T_COSE_CRYPTO_EC_P256_COORD_SIZE

#define T_COSE_CRYPTO_EC_P256_COORD_SIZE 32

The size of X and Y coordinate in 2 parameter style EC public key.

Format is as defined in [COSE (RFC 8152)] (https://tools.ietf.org/html/rfc8152) and SEC 1: Elliptic Curve Cryptography.

This size is well-known and documented in public standards.

Definition at line 222 of file t_cose_crypto.h.

◆ T_COSE_CRYPTO_SHA256_SIZE

#define T_COSE_CRYPTO_SHA256_SIZE 32

The size of the output of SHA-256 in bytes.

(It is safe to define this independently here as its size is well-known and fixed. There is no need to reference platform-specific headers and incur messy dependence.)

Definition at line 309 of file t_cose_crypto.h.

Function Documentation

◆ t_cose_crypto_pub_key_sign()

enum t_cose_err_t t_cose_crypto_pub_key_sign	(	int32_t	cose_alg_id,
		int32_t	key_select,
		struct useful_buf_c	hash_to_sign,
		struct useful_buf	signature_buffer,
		struct useful_buf_c *	signature
	)

Perform public key signing.

Part of the t_cose crypto adaptation layer.

Parameters

[in]	cose_alg_id	The algorithm to sign with. The IDs are defined in [COSE (RFC 8152)] (https://tools.ietf.org/html/rfc8152) or in the [IANA COSE Registry] (https://www.iana.org/assignments/cose/cose.xhtml). A proprietary ID can also be defined locally (`#define`) if the needed one hasn't been registered.
[in]	key_select	Indicates which key to use to sign.
[in]	hash_to_sign	The bytes to sign. Typically, a hash of a payload.
[in]	signature_buffer	Pointer and length of buffer into which the resulting signature is put.
[in]	signature	Pointer and length of the signature returned.

Return values

T_COSE_SUCCESS	Successfully created the signature.
T_COSE_ERR_SIG_BUFFER_SIZE	The `signature_buffer` too small.
T_COSE_ERR_UNSUPPORTED_SIGNING_ALG	The requested signing algorithm, `cose_alg_id`, is not supported.
T_COSE_ERR_UNKNOWN_KEY	The key identified by `key_select` was not found.
T_COSE_ERR_WRONG_TYPE_OF_KEY	The key was found, but it was the wrong type.
T_COSE_ERR_INVALID_ARGUMENT	Some (unspecified) argument was not valid.
T_COSE_ERR_INSUFFICIENT_MEMORY	Insufficient heap memory.
T_COSE_ERR_FAIL	General unspecific failure.
T_COSE_ERR_TAMPERING_DETECTED	Equivalent to `PSA_ERROR_TAMPERING_DETECTED`.

This is called to do public key signing. The implementation will vary from one platform / OS to another but should conform to the description here.

The key selection depends on the platform / OS.

See the note in the Detailed Description (the \file comment block) for details on how useful_buf and useful_buf_c are used to return the signature.

To find out the size of the signature buffer needed, call this with signature_buffer->ptr NULL and signature_buffer->len a very large number like UINT32_MAX. The size will be returned in signature->len.

◆ t_cose_crypto_pub_key_verify()

enum t_cose_err_t t_cose_crypto_pub_key_verify	(	int32_t	cose_alg_id,
		int32_t	key_select,
		struct useful_buf_c	key_id,
		struct useful_buf_c	hash_to_verify,
		struct useful_buf_c	signature
	)

perform public key signature verification.

Part of the t_cose crypto adaptation layer.

Parameters

[in]	cose_alg_id	The algorithm to use for verification. The IDs are defined in [COSE (RFC 8152)] (https://tools.ietf.org/html/rfc8152) or in the [IANA COSE Registry] (https://www.iana.org/assignments/cose/cose.xhtml). A proprietary ID can also be defined locally (`#define`) if the needed one hasn't been registered.
[in]	key_select	Verification key selection.
[in]	key_id	A key id or `NULL_USEFUL_BUF_C`.
[in]	hash_to_verify	The data or hash that is to be verified.
[in]	signature	The signature.

This verifies that the signature passed in was over the hash_to_verify passed in.

The public key used to verify the signature is selected by the key_id if it is not NULL_USEFUL_BUF_C or the key_select if it is.

The key selected must be, or include, a public key of the correct type for cose_alg_id.

Return values

T_COSE_SUCCESS	The signature is valid
T_COSE_ERR_SIG_VERIFY	Signature verification failed. For example, the cryptographic operations completed successfully but hash wasn't as expected.
T_COSE_ERR_UNKNOWN_KEY	The key identified by `key_select` or a `kid` 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_UNSUPPORTED_SIGNING_ALG	The requested signing algorithm is not supported.
T_COSE_ERR_INVALID_ARGUMENT	Some (unspecified) argument was not valid.
T_COSE_ERR_INSUFFICIENT_MEMORY	Out of heap memory.
T_COSE_ERR_FAIL	General unspecific failure.
T_COSE_ERR_TAMPERING_DETECTED	Equivalent to `PSA_ERROR_TAMPERING_DETECTED`.

◆ t_cose_crypto_get_ec_pub_key()

enum t_cose_err_t t_cose_crypto_get_ec_pub_key	(	int32_t	key_select,
		struct useful_buf_c	kid,
		int32_t *	cose_curve_id,
		struct useful_buf	buf_to_hold_x_coord,
		struct useful_buf	buf_to_hold_y_coord,
		struct useful_buf_c *	x_coord,
		struct useful_buf_c *	y_coord
	)

Get an elliptic curve public key.

Part of the t_cose crypto adaptation layer.

Parameters

[in]	key_select	Used to look up the public key to return when `kid` is `NULL_USEFUL_BUF_C`.
[in]	kid	A key ID to look up against. May be `NULL_USEFUL_BUF_C`. This is typically the kid from the COSE unprotected header.
[out]	cose_curve_id	The curve ID of the key returned as defined by [COSE (RFC 8152)] (https://tools.ietf.org/html/rfc8152) or the IANA COSE registry.
[in]	buf_to_hold_x_coord	Pointer and length into which the X coordinate is put.
[in]	buf_to_hold_y_coord	Pointer and length into which the Y coordinate is put.
[out]	x_coord	Pointer and length of the returned X coordinate.
[out]	y_coord	Pointer and length of the returned Y coordinate.

Return values

T_COSE_SUCCESS	The key was found and is returned.
T_COSE_ERR_UNKNOWN_KEY	The key identified by `key_select` or a `kid` 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_FAIL	General unspecific failure.
T_COSE_ERR_KEY_BUFFER_SIZE	Buffer to hold the output was too small.

This finds and returns a public key. Where it looks for the key is dependent on the OS / platform.

T_COSE_CRYPTO_EC_P256_COORD_SIZE is the size of the X or Y coordinate for the NIST P-256 curve.

See the note in the Detailed Description (the \file comment block) for details on how useful_buf and useful_buf_c are used to return the X and Y coordinates.

◆ t_cose_crypto_hash_start()

enum t_cose_err_t t_cose_crypto_hash_start	(	struct t_cose_crypto_hash *	hash_ctx,
		int32_t	cose_hash_alg_id
	)

Start cryptographic hash.

Part of the t_cose crypto adaptation layer.

Parameters

[in,out]	hash_ctx	Pointer to the hash context that will be initialized.
[in]	cose_hash_alg_id	Algorithm ID that identifies the hash to use. This is from the [IANA COSE Registry] (https://www.iana.org/assignments/cose/cose.xhtml). As of the creation of this interface no identifiers of only a hash functions have been registered. Signature algorithms that include specification of the hash have been registered, but they are not to be used here. Until hash functions only have been officially registered, some IDs are defined in the proprietary space in t_cose_common.h.

Return values

T_COSE_ERR_UNSUPPORTED_HASH	The requested algorithm is unknown or unsupported.
T_COSE_ERR_HASH_GENERAL_FAIL	Some general failure of the hash function

This initializes the hash context for the particular algorithm. It must be called first. A hash_ctx can be reused if it is reinitialized.

◆ t_cose_crypto_hash_update()

void t_cose_crypto_hash_update	(	struct t_cose_crypto_hash *	hash_ctx,
		struct useful_buf_c	data_to_hash
	)

Feed data into a cryptographic hash.

Part of the t_cose crypto adaptation layer.

Parameters

[in,out]	hash_ctx	Pointer to the hash context in which accumulate the hash.
[in]	data_to_hash	Pointer and length of data to feed into hash. The pointer may by `NULL` in which case no hashing is performed.

There is no return value. If an error occurs it is remembered in hash_ctx and returned when t_cose_crypto_hash_finish() is called. Once in the error state, this function may be called, but it will not do anything.

◆ t_cose_crypto_hash_finish()

enum t_cose_err_t t_cose_crypto_hash_finish	(	struct t_cose_crypto_hash *	hash_ctx,
		struct useful_buf	buffer_to_hold_result,
		struct useful_buf_c *	hash_result
	)

Finish a cryptographic hash.

Part of the t_cose crypto adaptation layer.

Parameters

[in,out]	hash_ctx	Pointer to the hash context.
[in]	buffer_to_hold_result	Pointer and length into which the resulting hash is put.
[out]	hash_result	Pointer and length of the resulting hash.

Return values

T_COSE_ERR_HASH_GENERAL_FAIL	Some general failure of the hash function.
T_COSE_ERR_HASH_BUFFER_SIZE	The size of the buffer to hold the hash result was too small.

Call this to complete the hashing operation. If the everything completed correctly, the resulting hash is returned. Note that any errors that occurred during t_cose_crypto_hash_update() are returned here.

See the note in the Detailed Description (the \file comment block) for details on how useful_buf and useful_buf_c are used to return the hash.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ T_COSE_EC_P256_SIG_SIZE

◆ T_COSE_MAX_EC_SIG_SIZE

◆ T_COSE_CRYPTO_EC_P256_COORD_SIZE

◆ T_COSE_CRYPTO_SHA256_SIZE

Function Documentation

◆ t_cose_crypto_pub_key_sign()

◆ t_cose_crypto_pub_key_verify()

◆ t_cose_crypto_get_ec_pub_key()

◆ t_cose_crypto_hash_start()

◆ t_cose_crypto_hash_update()

◆ t_cose_crypto_hash_finish()