Mistake on this page?
Report an issue in GitHub or email us
Data Structures | Macros | Functions
t_cose_crypto.h File Reference

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"

Go to the source code of this file.

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

static size_t t_cose_signature_size (int32_t cose_sig_alg_id)
 Get the size in bytes of a particular signature type. More...
 
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:

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). New ones can be registered in the IANA COSE Registry. 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

#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) 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.

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

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

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

Function Documentation

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_selectUsed to look up the public key to return when kid is NULL_USEFUL_BUF_C.
[in]kidA 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_idThe curve ID of the key returned as defined by COSE (RFC 8152) or the IANA COSE registry.
[in]buf_to_hold_x_coordPointer and length into which the X coordinate is put.
[in]buf_to_hold_y_coordPointer and length into which the Y coordinate is put.
[out]x_coordPointer and length of the returned X coordinate.
[out]y_coordPointer and length of the returned Y coordinate.
Return values
T_COSE_SUCCESSThe key was found and is returned.
T_COSE_ERR_UNKNOWN_KEYThe key identified by key_select or a kid was not found.
T_COSE_ERR_WRONG_TYPE_OF_KEYThe key was found, but it was the wrong type for the operation.
T_COSE_ERR_FAILGeneral unspecific failure.
T_COSE_ERR_KEY_BUFFER_SIZEBuffer 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.

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_ctxPointer to the hash context.
[in]buffer_to_hold_resultPointer and length into which the resulting hash is put.
[out]hash_resultPointer and length of the resulting hash.
Return values
T_COSE_ERR_HASH_GENERAL_FAILSome general failure of the hash function.
T_COSE_ERR_HASH_BUFFER_SIZEThe 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.

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_ctxPointer to the hash context that will be initialized.
[in]cose_hash_alg_idAlgorithm ID that identifies the hash to use. This is from the IANA COSE Registry. 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_HASHThe requested algorithm is unknown or unsupported.
T_COSE_ERR_HASH_GENERAL_FAILSome 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.

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_ctxPointer to the hash context in which accumulate the hash.
[in]data_to_hashPointer 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.

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_idThe algorithm to sign with. The IDs are defined in COSE (RFC 8152) or in the IANA COSE Registry. A proprietary ID can also be defined locally (#define) if the needed one hasn't been registered.
[in]key_selectIndicates which key to use to sign.
[in]hash_to_signThe bytes to sign. Typically, a hash of a payload.
[in]signature_bufferPointer and length of buffer into which the resulting signature is put.
[in]signaturePointer and length of the signature returned.
Return values
T_COSE_SUCCESSSuccessfully created the signature.
T_COSE_ERR_SIG_BUFFER_SIZEThe signature_buffer too small.
T_COSE_ERR_UNSUPPORTED_SIGNING_ALGThe requested signing algorithm, cose_alg_id, is not supported.
T_COSE_ERR_UNKNOWN_KEYThe key identified by key_select was not found.
T_COSE_ERR_WRONG_TYPE_OF_KEYThe key was found, but it was the wrong type.
T_COSE_ERR_INVALID_ARGUMENTSome (unspecified) argument was not valid.
T_COSE_ERR_INSUFFICIENT_MEMORYInsufficient heap memory.
T_COSE_ERR_FAILGeneral unspecific failure.
T_COSE_ERR_TAMPERING_DETECTEDEquivalent 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.

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_idThe algorithm to use for verification. The IDs are defined in COSE (RFC 8152) or in the IANA COSE Registry. A proprietary ID can also be defined locally (#define) if the needed one hasn't been registered.
[in]key_selectVerification key selection.
[in]key_idA key id or NULL_USEFUL_BUF_C.
[in]hash_to_verifyThe data or hash that is to be verified.
[in]signatureThe 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_SUCCESSThe signature is valid
T_COSE_ERR_SIG_VERIFYSignature verification failed. For example, the cryptographic operations completed successfully but hash wasn't as expected.
T_COSE_ERR_UNKNOWN_KEYThe key identified by key_select or a kid was not found.
T_COSE_ERR_WRONG_TYPE_OF_KEYThe key was found, but it was the wrong type for the operation.
T_COSE_ERR_UNSUPPORTED_SIGNING_ALGThe requested signing algorithm is not supported.
T_COSE_ERR_INVALID_ARGUMENTSome (unspecified) argument was not valid.
T_COSE_ERR_INSUFFICIENT_MEMORYOut of heap memory.
T_COSE_ERR_FAILGeneral unspecific failure.
T_COSE_ERR_TAMPERING_DETECTEDEquivalent to PSA_ERROR_TAMPERING_DETECTED.
static size_t t_cose_signature_size ( int32_t  cose_sig_alg_id)
static

Get the size in bytes of a particular signature type.

Parameters
[in]cose_sig_alg_idThe COSE algorithm ID.
Returns
The size in bytes of the signature for a public-key signing algorithm.

Definition at line 402 of file t_cose_crypto.h.

Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.