Integrate p256-m as an example driver alongside Mbed TLS and write documentation for the example.
(Reapplying changes as one commit on top of development post codestyle change instead of rewriting old branch)
Signed-off-by: Aditya Deshpande <aditya.deshpande@arm.com>
diff --git a/3rdparty/p256-m/p256-m_driver_entrypoints.h b/3rdparty/p256-m/p256-m_driver_entrypoints.h
new file mode 100644
index 0000000..bf6b18d
--- /dev/null
+++ b/3rdparty/p256-m/p256-m_driver_entrypoints.h
@@ -0,0 +1,155 @@
+#ifndef P256M_DRIVER_ENTRYPOINTS_H
+#define P256M_DRIVER_ENTRYPOINTS_H
+
+#if defined(MBEDTLS_P256M_EXAMPLE_DRIVER_ENABLED)
+#ifndef PSA_CRYPTO_ACCELERATOR_DRIVER_PRESENT
+#define PSA_CRYPTO_ACCELERATOR_DRIVER_PRESENT
+#endif /* PSA_CRYPTO_ACCELERATOR_DRIVER_PRESENT */
+#endif /* MBEDTLS_P256M_EXAMPLE_DRIVER_ENABLED */
+
+#include "psa/crypto_types.h"
+
+/** Convert an internal p256-m error code to a PSA error code
+ *
+ * \param ret An error code thrown by p256-m
+ *
+ * \return The corresponding PSA error code
+ */
+ //no-check-names
+psa_status_t p256m_to_psa_error( int ret );
+
+
+/** Generate SECP256R1 ECC Key Pair.
+ * Interface function which calls the p256-m key generation function and
+ * places it in the key buffer provided by the caller (mbed TLS) in the
+ * correct format. For a SECP256R1 curve this is the 32 bit private key.
+ *
+ * \param[in] attributes The attributes of the key to use for the
+ * operation.
+ * \param[out] key_buffer The buffer to contain the key data in
+ * output format upon successful return.
+ * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes.
+ * \param[out] key_buffer_length The length of the data written in \p
+ * key_buffer in bytes.
+ *
+ * \retval #PSA_SUCCESS
+ * Success. Keypair generated and stored in buffer.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ * \retval #PSA_ERROR_GENERIC_ERROR
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ */
+ //no-check-names
+psa_status_t p256m_transparent_generate_key(
+ const psa_key_attributes_t *attributes,
+ uint8_t *key_buffer,
+ size_t key_buffer_size,
+ size_t *key_buffer_length );
+
+/** Perform raw key agreement using p256-m's ECDH implementation
+ * \param[in] attributes The attributes of the key to use for the
+ * operation.
+ * \param[in] key_buffer The buffer containing the private key
+ * in the format specified by PSA.
+ * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes.
+ * \param[in] alg A key agreement algorithm that is
+ * compatible with the type of the key.
+ * \param[in] peer_key The buffer containing the peer's public
+ * key in format specified by PSA.
+ * \param[in] peer_key_length Size of the \p peer_key buffer in
+ * bytes.
+ * \param[out] shared_secret The buffer to which the shared secret
+ * is to be written.
+ * \param[in] shared_secret_size Size of the \p shared_secret buffer in
+ * bytes.
+ * \param[out] shared_secret_length On success, the number of bytes that
+ * make up the returned shared secret.
+ * \retval #PSA_SUCCESS
+ * Success. Shared secret successfully calculated.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ */
+ //no-check-names
+psa_status_t p256m_transparent_key_agreement(
+ const psa_key_attributes_t *attributes,
+ const uint8_t *key_buffer,
+ size_t key_buffer_size,
+ psa_algorithm_t alg,
+ const uint8_t *peer_key,
+ size_t peer_key_length,
+ uint8_t *shared_secret,
+ size_t shared_secret_size,
+ size_t *shared_secret_length );
+
+/** Sign an already-calculated hash with a private key using p256-m's ECDSA
+ * implementation
+ * \param[in] attributes The attributes of the key to use for the
+ * operation.
+ * \param[in] key_buffer The buffer containing the private key
+ * in the format specified by PSA.
+ * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes.
+ * \param[in] alg A signature algorithm that is compatible
+ * with the type of the key.
+ * \param[in] hash The hash to sign.
+ * \param[in] hash_length Size of the \p hash buffer in bytes.
+ * \param[out] signature Buffer where signature is to be written.
+ * \param[in] signature_size Size of the \p signature buffer in bytes.
+ * \param[out] signature_length On success, the number of bytes
+ * that make up the returned signature value.
+ *
+ * \retval #PSA_SUCCESS
+ * Success. Hash was signed successfully.
+ * respectively of the key.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ */
+//no-check-names
+psa_status_t p256m_transparent_sign_hash(
+ const psa_key_attributes_t *attributes,
+ const uint8_t *key_buffer,
+ size_t key_buffer_size,
+ psa_algorithm_t alg,
+ const uint8_t *hash,
+ size_t hash_length,
+ uint8_t *signature,
+ size_t signature_size,
+ size_t *signature_length );
+
+/** Verify the signature of a hash using a SECP256R1 public key using p256-m's
+ * ECDSA implementation.
+ *
+ * \note p256-m expects a 64 byte public key, but the contents of the key
+ buffer may be the 32 byte keypair representation or the 65 byte
+ public key representation. As a result, this function calls
+ psa_driver_wrapper_export_public_key() to ensure the public key
+ can be passed to p256-m.
+ *
+ * \param[in] attributes The attributes of the key to use for the
+ * operation.
+ *
+ * \param[in] key_buffer The buffer containing the key
+ * in the format specified by PSA.
+ * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes.
+ * \param[in] alg A signature algorithm that is compatible with
+ * the type of the key.
+ * \param[in] hash The hash whose signature is to be
+ * verified.
+ * \param[in] hash_length Size of the \p hash buffer in bytes.
+ * \param[in] signature Buffer containing the signature to verify.
+ * \param[in] signature_length Size of the \p signature buffer in bytes.
+ *
+ * \retval #PSA_SUCCESS
+ * The signature is valid.
+ * \retval #PSA_ERROR_INVALID_SIGNATURE
+ * The calculation was performed successfully, but the passed
+ * signature is not a valid signature.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ */
+psa_status_t p256m_transparent_verify_hash(
+ const psa_key_attributes_t *attributes,
+ const uint8_t *key_buffer,
+ size_t key_buffer_size,
+ psa_algorithm_t alg,
+ const uint8_t *hash,
+ size_t hash_length,
+ const uint8_t *signature,
+ size_t signature_length );
+
+#endif /* P256M_DRIVER_ENTRYPOINTS_H */