Mbed OS Reference | t_cose_crypto.h Source File

Go to the documentation of this file.
 /*
  * t_cose_crypto.h
  *
  * Copyright 2019, Laurence Lundblade
  *
  * SPDX-License-Identifier: BSD-3-Clause
  *
  * See BSD-3-Clause license in README.mdE.
  */
 
 
 #ifndef __T_COSE_CRYPTO_H__
 #define __T_COSE_CRYPTO_H__
 
 #include "t_cose_common.h"
 #include "useful_buf.h"
 #include <stdint.h>
 #include "t_cose_defines.h"
 
 
 /**
  * \file t_cose_crypto.h
  *
  * \brief 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 \ref t_cose_err_t errors
  * - Have inputs and outputs be \c struct \c useful_buf_c and
  *   \c struct \c 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 (\c \#define) if what is needed is not in
  * the IANA registry.
  *
  * Binary data is returned to the caller using a \c struct \c
  * useful_buf to pass the buffer to receive the data and its length in
  * and a \c 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 \c
  * useful_buf_c returned is const.
  *
  * The pointer in the \c useful_buf_c will always point to the buffer
  * passed in via the \c 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.
  */
 
 
 /**
  * Size of the signature output for the NIST P-256 Curve.
  */
 #define T_COSE_EC_P256_SIG_SIZE 64
 
 /**
  * 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.
  */
 #define T_COSE_MAX_EC_SIG_SIZE T_COSE_EC_P256_SIG_SIZE
 
 
 /**
  * \brief Get the size in bytes of a particular signature type.
  *
  * \param[in] cose_sig_alg_id  The COSE algorithm ID.
  *
  * \return The size in bytes of the signature for a public-key signing
  * algorithm.
  */
 static inline size_t t_cose_signature_size(int32_t cose_sig_alg_id);
 
 
 /**
  * \brief Perform public key signing. Part of the t_cose crypto
  * adaptation layer.
  *
  * \param[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 (\c \#define) if the needed
  *                              one hasn't been registered.
  * \param[in] key_select        Indicates which key to use to sign.
  * \param[in] hash_to_sign      The bytes to sign. Typically, a hash of
  *                              a payload.
  * \param[in] signature_buffer  Pointer and length of buffer into which
  *                              the resulting signature is put.
  * \param[in] signature         Pointer and length of the signature
  *                              returned.
  *
  * \retval T_COSE_SUCCESS
  *         Successfully created the signature.
  * \retval T_COSE_ERR_SIG_BUFFER_SIZE
  *         The \c signature_buffer too small.
  * \retval T_COSE_ERR_UNSUPPORTED_SIGNING_ALG
  *         The requested signing algorithm, \c cose_alg_id, is not
  *         supported.
  * \retval T_COSE_ERR_UNKNOWN_KEY
  *         The key identified by \c key_select was not found.
  * \retval T_COSE_ERR_WRONG_TYPE_OF_KEY
  *         The key was found, but it was the wrong type.
  * \retval T_COSE_ERR_INVALID_ARGUMENT
  *         Some (unspecified) argument was not valid.
  * \retval T_COSE_ERR_INSUFFICIENT_MEMORY
  *         Insufficient heap memory.
  * \retval T_COSE_ERR_FAIL
  *         General unspecific failure.
  * \retval T_COSE_ERR_TAMPERING_DETECTED
  *         Equivalent to \c 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 \c useful_buf and \c useful_buf_c are used to
  * return the signature.
  *
  * To find out the size of the signature buffer needed, call this with
  * \c signature_buffer->ptr \c NULL and \c signature_buffer->len a
  * very large number like \c UINT32_MAX. The size will be returned in
  * \c signature->len.
  */
 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);
 
 
 /**
  * \brief perform public key signature verification. Part of the
  * t_cose crypto adaptation layer.
  *
  * \param[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 (\c \#define) if the needed one
  *                           hasn't been registered.
  * \param[in] key_select     Verification key selection.
  * \param[in] key_id         A key id or \c NULL_USEFUL_BUF_C.
  * \param[in] hash_to_verify The data or hash that is to be verified.
  * \param[in] signature      The signature.
  *
  * This verifies that the \c signature passed in was over the \c
  * hash_to_verify passed in.
  *
  * The public key used to verify the signature is selected by the \c
  * key_id if it is not \c NULL_USEFUL_BUF_C or the \c key_select if it
  * is.
  *
  * The key selected must be, or include, a public key of the correct
  * type for \c cose_alg_id.
  *
  * \retval T_COSE_SUCCESS
  *         The signature is valid
  * \retval T_COSE_ERR_SIG_VERIFY
  *         Signature verification failed. For example, the
  *         cryptographic operations completed successfully but hash
  *         wasn't as expected.
  * \retval T_COSE_ERR_UNKNOWN_KEY
  *         The key identified by \c key_select or a \c kid was
  *         not found.
  * \retval T_COSE_ERR_WRONG_TYPE_OF_KEY
  *         The key was found, but it was the wrong type
  *         for the operation.
  * \retval T_COSE_ERR_UNSUPPORTED_SIGNING_ALG
  *         The requested signing algorithm is not supported.
  * \retval T_COSE_ERR_INVALID_ARGUMENT
  *         Some (unspecified) argument was not valid.
  * \retval T_COSE_ERR_INSUFFICIENT_MEMORY
  *         Out of heap memory.
  * \retval T_COSE_ERR_FAIL
  *         General unspecific failure.
  * \retval T_COSE_ERR_TAMPERING_DETECTED
  *         Equivalent to \c PSA_ERROR_TAMPERING_DETECTED.
  */
 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);
 
 
 /**
  * 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](http://www.secg.org/sec1-v2.pdf).
  *
  * This size is well-known and documented in public standards.
  */
 #define T_COSE_CRYPTO_EC_P256_COORD_SIZE 32
 
 
 /**
  * \brief Get an elliptic curve public key. Part of the t_cose crypto
  * adaptation layer.
  *
  * \param[in] key_select     Used to look up the public
  *                           key to return when \c kid is
  *                           \c NULL_USEFUL_BUF_C.
  * \param[in] kid            A key ID to look up against. May be
  *                           \c NULL_USEFUL_BUF_C. This is typically
  *                           the kid from the COSE unprotected header.
  * \param[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.
  * \param[in] buf_to_hold_x_coord Pointer and length into which the
  *                                X coordinate is put.
  * \param[in] buf_to_hold_y_coord Pointer and length into which the
  *                                Y coordinate is put.
  * \param[out] x_coord       Pointer and length of the returned X
  *                           coordinate.
  * \param[out] y_coord       Pointer and length of the returned Y
  *                           coordinate.
  *
  * \retval T_COSE_SUCCESS
  *         The key was found and is returned.
  * \retval T_COSE_ERR_UNKNOWN_KEY
  *         The key identified by \c key_select or a \c kid was not
  *         found.
  * \retval T_COSE_ERR_WRONG_TYPE_OF_KEY
  *         The key was found, but it was the wrong type for the
  *         operation.
  * \retval T_COSE_ERR_FAIL
  *         General unspecific failure.
  * \retval 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.
  *
  * \ref 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 \c useful_buf and \c useful_buf_c are used to
  * return the X and Y coordinates.
  */
 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);
 
 
 /*
  * No function to get private key because there is no need for it.
  * The private signing key only needs to exist behind
  * t_cose_crypto_pub_key_sign().
  */
 
 
 
 
 /**
  * The context for use with the hash adaptation layer here.
  */
 struct t_cose_crypto_hash {
     /* Can't put the actual size here without creating dependecy on
      * actual hash implementation, so this is a fairly large and
      * accommodating size.
      */
     uint8_t bytes[280];
 };
 
 
 /**
  * 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.)
  */
 #define T_COSE_CRYPTO_SHA256_SIZE 32
 
 
 /**
  * \brief Start cryptographic hash. Part of the t_cose crypto
  * adaptation layer.
  *
  * \param[in,out] hash_ctx      Pointer to the hash context that
  *                              will be initialized.
  * \param[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.
  *
  * \retval T_COSE_ERR_UNSUPPORTED_HASH
  *         The requested algorithm is unknown or unsupported.
  *
  * \retval 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 \c hash_ctx can be reused if it is
  * reinitialized.
  */
 enum t_cose_err_t
 t_cose_crypto_hash_start(struct t_cose_crypto_hash *hash_ctx,
                          int32_t cose_hash_alg_id);
 
 
 /**
  * \brief Feed data into a cryptographic hash. Part of the t_cose
  * crypto adaptation layer.
  *
  * \param[in,out] hash_ctx  Pointer to the hash context in which
  *                          accumulate the hash.
  * \param[in]  data_to_hash Pointer and length of data to feed into
  *                          hash. The pointer may by \c NULL in which
  *                          case no hashing is performed.
  *
  * There is no return value. If an error occurs it is remembered in \c
  * 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.
  */
 void t_cose_crypto_hash_update(struct t_cose_crypto_hash *hash_ctx,
                                struct useful_buf_c data_to_hash);
 
 
 /**
  * \brief Finish a cryptographic hash. Part of the t_cose crypto
  * adaptation layer.
  *
  * \param[in,out] hash_ctx           Pointer to the hash context.
  * \param[in] buffer_to_hold_result  Pointer and length into which
  *                                   the resulting hash is put.
  * \param[out] hash_result           Pointer and length of the
  *                                   resulting hash.
  *
  * \retval T_COSE_ERR_HASH_GENERAL_FAIL
  *         Some general failure of the hash function.
  * \retval 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 \c useful_buf and \c useful_buf_c are used to
  * return the hash.
  */
 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);
 
 
 
 /*
  * Public inline function. See documentation above.
  */
 static inline size_t t_cose_signature_size(int32_t cose_sig_alg_id)
 {
     switch(cose_sig_alg_id) {
         case COSE_ALGORITHM_ES256:
             return T_COSE_EC_P256_SIG_SIZE;
         default:
             return T_COSE_EC_P256_SIG_SIZE;
     }
 }
 
 
 #endif /* __T_COSE_CRYPTO_H__ */
Important Information for this Arm website
