aboutsummaryrefslogtreecommitdiff
path: root/lib/t_cose/src/t_cose_crypto.h
diff options
context:
space:
mode:
Diffstat (limited to 'lib/t_cose/src/t_cose_crypto.h')
-rw-r--r--lib/t_cose/src/t_cose_crypto.h470
1 files changed, 0 insertions, 470 deletions
diff --git a/lib/t_cose/src/t_cose_crypto.h b/lib/t_cose/src/t_cose_crypto.h
deleted file mode 100644
index 83d9f33d30..0000000000
--- a/lib/t_cose/src/t_cose_crypto.h
+++ /dev/null
@@ -1,470 +0,0 @@
-/*
- * t_cose_crypto.h
- *
- * Copyright 2019, Laurence Lundblade
- *
- * SPDX-License-Identifier: BSD-3-Clause
- *
- * See BSD-3-Clause license in README.md.
- */
-
-
-#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__ */