text: /*
   * 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 "q_useful_buf.h"
  #include <stdint.h>
  #include "t_cose_defines.h"
  
  #ifdef __cplusplus
  extern "C" {
  #endif
  
  /**
   * \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 q_useful_buf_c and
   *   \c struct \c q_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
   * q_useful_buf to pass the buffer to receive the data and its length in
   * and a \c q_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
   * q_useful_buf_c returned is const.
   *
   * The pointer in the \c q_useful_buf_c will always point to the buffer
   * passed in via the \c q_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 q_useful_buf and \c q_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 q_useful_buf_c hash_to_sign,
                             struct q_useful_buf signature_buffer,
                             struct q_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_Q_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_Q_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 q_useful_buf_c key_id,
                               struct q_useful_buf_c hash_to_verify,
                               struct q_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_Q_USEFUL_BUF_C.
   * \param[in] kid            A key ID to look up against. May be
   *                           \c NULL_Q_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 q_useful_buf and \c q_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 q_useful_buf_c kid,
                               int32_t *cose_curve_id,
                               struct q_useful_buf buf_to_hold_x_coord,
                               struct q_useful_buf buf_to_hold_y_coord,
                               struct q_useful_buf_c  *x_coord,
                               struct q_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().
   */
  
  
  
  
  #ifdef T_COSE_USE_B_CON_SHA256
  /* This is code for use with Brad Conte's crypto.  See
   * https://github.com/B-Con/crypto-algorithms and see the description
   * of t_cose_crypto_hash
   */
  #include "sha256.h"
  #endif
  
  
  /**
   * The context for use with the hash adaptation layer here.
   *
   * Hash implementations for this porting layer are put into two
   * different categories.
   *
   * The first can be supported generically without any dependency on
   * the actual hash implementation in this header. These only need a
   * pointer or handle for the hash context.  Usually these are
   * implemented by a service, system API or crypto HW that runs in a
   * separate context or process. They probably allocate memory
   * internally. These can use context.ptr or context.handle to hold the
   * pointer or handle to the hash context.
   *
   * The second sort of hash implementations need more than just a
   * pointer or handle. Typically these are libraries that are linked
   * with this code and run in the same process / context / thread as
   * this code. These can be efficient requiring no context switches or
   * memory allocations. These type require this header be modified for
   * the #include which defines the hash context and so this struct
   * includes that context as a member. This context is allocated on the
   * stack, so any members added here should be small enough to go on
   * the stack. USE_B_CON_SHA256 is an example of this type.
   *
   * The actual implementation of the hash is in a separate .c file
   * that will be specific to the particular platform, library,
   * service or such used.
   */
  struct t_cose_crypto_hash {
  
  #ifdef T_COSE_USE_B_CON_SHA256
      /* Specific context for Brad Conte's sha256.c */
      SHA256_CTX context;
  #else
      /*
       *  Generic pointer / handle that can work for many
       *  hash implementations.
       */
      union {
          void    *ptr;
          uint64_t handle;
      } context;
      int64_t status;
  #endif
  
  };
  
  
  /**
   * 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.
   *
   * This function can be called with \c data_to_hash.ptr NULL and it
   * will pretend to hash. This allows the same code that is used to
   * produce the real hash to be used to return a length of the would be
   * hash for encoded data structure size calculations.
   */
  void t_cose_crypto_hash_update(struct t_cose_crypto_hash *hash_ctx,
                                 struct q_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 q_useful_buf and \c q_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 q_useful_buf buffer_to_hold_result,
                            struct q_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;
      }
  }
  
  
  #ifdef __cplusplus
  }
  #endif
  
  #endif /* __T_COSE_CRYPTO_H__ */
  