Merge pull request #789 from ARMmbed/mbedtls-2.25.0r0
Merge release candidate back to development
diff --git a/docs/architecture/testing/driver-interface-test-strategy.md b/docs/architecture/testing/driver-interface-test-strategy.md
index d6769da..086fc1a 100644
--- a/docs/architecture/testing/driver-interface-test-strategy.md
+++ b/docs/architecture/testing/driver-interface-test-strategy.md
@@ -4,9 +4,19 @@
The driver interfaces are standardized through PSA Cryptography functional specifications.
-## Secure element driver interface
+## Secure element driver interface testing
-The secure element driver interface (SE interface for short) is defined by [`psa/crypto_se_driver.h`](../../../include/psa/crypto_se_driver.h). This is an interface between Mbed Crypto and one or more third-party drivers.
+### Secure element driver interfaces
+
+#### Opaque driver interface
+
+The [unified driver interface](../../proposed/psa-driver-interface.md) supports both transparent drivers (for accelerators) and opaque drivers (for secure elements).
+
+Drivers exposing this interface need to be registered at compile time by declaring their JSON description file.
+
+#### Dynamic secure element driver interface
+
+The dynamic secure element driver interface (SE interface for short) is defined by [`psa/crypto_se_driver.h`](../../../include/psa/crypto_se_driver.h). This is an interface between Mbed Crypto and one or more third-party drivers.
The SE interface consists of one function provided by Mbed Crypto (`psa_register_se_driver`) and many functions that drivers must implement. To make a driver usable by Mbed Crypto, the initialization code must call `psa_register_se_driver` with a structure that describes the driver. The structure mostly contains function pointers, pointing to the driver's methods. All calls to a driver function are triggered by a call to a PSA crypto API function.
@@ -18,6 +28,8 @@
#### SE driver registration
+This applies to dynamic drivers only.
+
* Test `psa_register_se_driver` with valid and with invalid arguments.
* Make at least one failing call to `psa_register_se_driver` followed by a successful call.
* Make at least one test that successfully registers the maximum number of drivers and fails to register one more.
@@ -102,14 +114,20 @@
A PKCS#11 driver would be a good candidate. It would be useful as part of our product offering.
-## Accelerator driver interface
+## Transparent driver interface testing
-The accelerator driver interface is defined by [`psa/crypto_accel_driver.h`](../../../include/psa/crypto_accel_driver.h).
+The [unified driver interface](../../proposed/psa-driver-interface.md) defines interfaces for accelerators.
-TODO
+### Test requirements
-## Entropy driver interface
+#### Requirements for transparent driver testing
-The entropy driver interface is defined by [`psa/crypto_entropy_driver.h`](../../../include/psa/crypto_entropy_driver.h).
+Every cryptographic mechanism for which a transparent driver interface exists (key creation, cryptographic operations, …) must be exercised in at least one build. The test must verify that the driver code is called.
+
+#### Requirements for fallback
+
+The driver interface includes a fallback mechanism so that a driver can reject a request at runtime and let another driver handle the request. For each entry point, there must be at least three test runs with two or more drivers available with driver A configured to fall back to driver B, with one run where A returns `PSA_SUCCESS`, one where A returns `PSA_ERROR_NOT_SUPPORTED` and B is invoked, and one where A returns a different error and B is not invoked.
+
+## Entropy and randomness interface testing
TODO
diff --git a/docs/proposed/psa-driver-interface.md b/docs/proposed/psa-driver-interface.md
index d825794..67ded56 100644
--- a/docs/proposed/psa-driver-interface.md
+++ b/docs/proposed/psa-driver-interface.md
@@ -5,8 +5,6 @@
This specification is work in progress and should be considered to be in a beta stage. There is ongoing work to implement this interface in Mbed TLS, which is the reference implementation of the PSA Cryptography API. At this stage, Arm does not expect major changes, but minor changes are expected based on experience from the first implementation and on external feedback.
-Time-stamp: "2020/11/24 11:03:32 GMT"
-
## Introduction
### Purpose of the driver interface
@@ -196,6 +194,8 @@
Some entry points are grouped in families that must be implemented as a whole. If a driver supports an entry point family, it must provide all the entry points in the family.
+Drivers can also have entry points related to random generation. A transparent driver can provide a [random generation interface](#random-generation-entry-points). Separately, transparent and opaque drivers can have [entropy collection entry points](#entropy-collection-entry-point).
+
#### General considerations on driver entry point parameters
Buffer parameters for driver entry points obey the following conventions:
@@ -375,6 +375,49 @@
* For elliptic curve private keys (`PSA_KEY_TYPE_ECC_KEY_PAIR`), check the size and range. TODO: what else?
* For elliptic curve public keys (`PSA_KEY_TYPE_ECC_PUBLIC_KEY`), check the size and range, and that the point is on the curve. TODO: what else?
+### Entropy collection entry point
+
+A driver can declare an entropy source by providing a `"get_entropy"` entry point. This entry point has the following prototype for a driver with the prefix `"acme"`:
+
+```
+psa_status_t acme_get_entropy(uint32_t flags,
+ size_t *estimate_bits,
+ uint8_t *output,
+ size_t output_size);
+```
+
+The semantics of the parameters is as follows:
+
+* `flags`: a bit-mask of [entropy collection flags](#entropy-collection-flags).
+* `estimate_bits`: on success, an estimate of the amount of entropy that is present in the `output` buffer, in bits. This must be at least `1` on success. The value is ignored on failure. Drivers should return a conservative estimate, even in circumstances where the quality of the entropy source is degraded due to environmental conditions (e.g. undervolting, low temperature, etc.).
+* `output`: on success, this buffer contains non-deterministic data with an estimated entropy of at least `*estimate_bits` bits. When the entropy is coming from a hardware peripheral, this should preferably be raw or lightly conditioned measurements from a physical process, such that statistical tests run over a sufficiently large amount of output can confirm the entropy estimates. But this specification also permits entropy sources that are fully conditioned, for example when the PSA Cryptography system is running as an application in an operating system and `"get_entropy"` returns data from the random generator in the operating system's kernel.
+* `output_size`: the size of the `output` buffer in bytes. This size should be large enough to allow a driver to pass unconditioned data with a low density of entropy; for example a peripheral that returns eight bytes of data with an estimated one bit of entropy cannot provide meaningful output in less than 8 bytes.
+
+Note that there is no output parameter indicating how many bytes the driver wrote to the buffer. Such an output length indication is not necessary because the entropy may be located anywhere in the buffer, so the driver may write less than `output_size` bytes but the core does not need to know this. The output parameter `estimate_bits` contains the amount of entropy, expressed in bits, which may be significantly less than `output_size * 8`.
+
+The entry point may return the following statuses:
+
+* `PSA_SUCCESS`: success. The output buffer contains some entropy.
+* `PSA_ERROR_INSUFFICIENT_ENTROPY`: no entropy is available without blocking. This is only permitted if the `PSA_DRIVER_GET_ENTROPY_BLOCK` flag is clear. The core may call `get_entropy` again later, giving time for entropy to be gathered or for adverse environmental conditions to be rectified.
+* Other error codes indicate a transient or permanent failure of the entropy source.
+
+Unlike most other entry points, if multiple transparent drivers include a `"get_entropy"` point, the core will call all of them (as well as the entry points from opaque drivers). Fallback is not applicable to `"get_entropy"`.
+
+#### Entropy collection flags
+
+* `PSA_DRIVER_GET_ENTROPY_BLOCK`: If this flag is set, the driver should block until it has at least one bit of entropy. If this flag is clear, the driver should avoid blocking if no entropy is readily available.
+* `PSA_DRIVER_GET_ENTROPY_KEEPALIVE`: This flag is intended to help with energy management for entropy-generating peripherals. If this flag is set, the driver should expect another call to `acme_get_entropy` after a short time. If this flag is clear, the core is not expecting to call the `"get_entropy"` entry point again within a short amount of time (but it may do so nonetheless).
+
+#### Entropy collection and blocking
+
+The intent of the `BLOCK` and `KEEPALIVE` [flags](#entropy-collection-flags) is to support drivers for TRNG (True Random Number Generator, i.e. an entropy source peripheral) that have a long ramp-up time, especially on platforms with multiple entropy sources.
+
+Here is a suggested call sequence for entropy collection that leverages these flags:
+
+1. The core makes a first round of calls to `"get_entropy"` on every source with the `BLOCK` flag clear and the `KEEPALIVE` flag set, so that drivers can prepare the TRNG peripheral.
+2. The core makes a second round of calls with the `BLOCK` flag set and the `KEEPALIVE` flag clear to gather needed entropy.
+3. If the second round does not collect enough entropy, the core makes more similar rounds, until the total amount of collected entropy is sufficient.
+
### Miscellaneous driver entry points
#### Driver initialization
@@ -428,6 +471,109 @@
3. [Determine the key size](#key-size-determination-on-import) and output it through `*bits`.
4. Copy the validated key data from `data` to `key_buffer`. The output must be in the canonical format documented for [`psa_export_key()`](https://armmbed.github.io/mbed-crypto/html/api/keys/management.html#c.psa_export_key) or [`psa_export_public_key()`](https://armmbed.github.io/mbed-crypto/html/api/keys/management.html#c.psa_export_public_key), so if the input is not in this format, the entry point must convert it.
+### Random generation entry points
+
+A transparent driver may provide an operation family that can be used as a cryptographic random number generator. The random generation mechanism must obey the following requirements:
+
+* The random output must be of cryptographic quality, with a uniform distribution. Therefore, if the random generator includes an entropy source, this entropy source must be fed through a CSPRNG (cryptographically secure pseudo-random number generator).
+* Random generation is expected to be fast. (If a device can provide entropy but is slow at generating random data, declare it as an [entropy driver](#entropy-collection-entry-point) instead.)
+* The random generator should be able to incorporate entropy provided by an outside source. If it isn't, the random generator can only be used if it's the only entropy source on the platform. (A random generator peripheral can be declared as an [entropy source](#entropy-collection-entry-point) instead of a random generator; this way the core will combine it with other entropy sources.)
+* The random generator may either be deterministic (in the sense that it always returns the same data when given the same entropy inputs) or non-deterministic (including its own entropy source). In other words, this interface is suitable both for PRNG (pseudo-random number generator, also known as DRBG (deterministic random bit generator)) and for NRBG (non-deterministic random bit generator).
+
+If no driver implements the random generation entry point family, the core provides an unspecified random generation mechanism.
+
+This operation family requires the following type, entry points and parameters (TODO: where exactly are the parameters in the JSON structure?):
+
+* Type `"random_context_t"`: the type of a random generation context.
+* `"init_random"` (entry point, optional): if this function is present, [the core calls it once](#random-generator-initialization) after allocating a `"random_context_t"` object.
+* `"add_entropy"` (entry point, optional): the core calls this function to [inject entropy](#entropy-injection). This entry point is optional if the driver is for a peripheral that includes an entropy source of its own, however [random generator drivers without entropy injection](#random-generator-drivers-without-entropy-injection) have limited portability since they can only be used on platforms with no other entropy source. This entry point is mandatory if `"initial_entropy_size"` is nonzero.
+* `"get_random"` (entry point, mandatory): the core calls this function whenever it needs to [obtain random data](#the-get_random-entry-point).
+* `"initial_entropy_size"` (integer, mandatory): the minimum number of bytes of entropy that the core must supply before the driver can output random data. This can be `0` if the driver is for a peripheral that includes an entropy source of its own.
+* `"reseed_entropy_size"` (integer, optional): the minimum number of bytes of entropy that the core should supply via [`"add_entropy"`](#entropy-injection) when the driver runs out of entropy. This value is also a hint for the size to supply if the core makes additional calls to `"add_entropy"`, for example to enforce prediction resistance. If omitted, the core should pass an amount of entropy corresponding to the expected security strength of the device (for example, pass 32 bytes of entropy when reseeding to achieve a security strength of 256 bits). If specified, the core should pass the larger of `"reseed_entropy_size"` and the amount corresponding to the security strength.
+
+Random generation is not parametrized by an algorithm. The choice of algorithm is up to the driver.
+
+#### Random generator initialization
+
+The `"init_random"` entry point has the following prototype for a driver with the prefix `"acme"`:
+
+```
+psa_status_t acme_init_random(acme_random_context_t *context);
+```
+
+The core calls this entry point once after allocating a random generation context. Initially, the context object is all-bits-zero.
+
+If a driver does not have an `"init_random"` entry point, the context object passed to the first call to `"add_entropy"` or `"get_random"` will be all-bits-zero.
+
+#### Entropy injection
+
+The `"add_entropy"` entry point has the following prototype for a driver with the prefix `"acme"`:
+
+```
+psa_status_t acme_add_entropy(acme_random_context_t *context,
+ const uint8_t *entropy,
+ size_t entropy_size);
+```
+
+The semantics of the parameters is as follows:
+
+* `context`: a random generation context. On the first call to `"add_entropy"`, this object has been initialized by a call to the driver's `"init_random"` entry point if one is present, and to all-bits-zero otherwise.
+* `entropy`: a buffer containing full-entropy data to seed the random generator. “Full-entropy” means that the data is uniformly distributed and independent of any other observable quantity.
+* `entropy_size`: the size of the `entropy` buffer in bytes. It is guaranteed to be at least `1`, but it may be smaller than the amount of entropy that the driver needs to deliver random data, in which case the core will call the `"add_entropy"` entry point again to supply more entropy.
+
+The core calls this function to supply entropy to the driver. The driver must mix this entropy into its internal state. The driver must mix the whole supplied entropy, even if there is more than what the driver requires, to ensure that all entropy sources are mixed into the random generator state. The driver may mix additional entropy of its own.
+
+The core may call this function at any time. For example, to enforce prediction resistance, the core can call `"add_entropy"` immediately after each call to `"get_random"`. The core must call this function in two circumstances:
+
+* Before the first call to the `"get_random"` entry point, to supply `"initial_entropy_size"` bytes of entropy.
+* After a call to the `"get_random"` entry point returns less than the required amount of random data, to supply at least `"reseed_entropy_size"` bytes of entropy.
+
+When the driver requires entropy, the core can supply it with one or more successive calls to the `"add_entropy"` entry point. If the required entropy size is zero, the core does not need to call `"add_entropy"`.
+
+#### Combining entropy sources with a random generation driver
+
+This section provides guidance on combining one or more [entropy sources](#entropy-collection-entry-point) (each having a `"get_entropy"` entry point) with a random generation driver (with an `"add_entropy"` entry point).
+
+Note that `"get_entropy"` returns data with an estimated amount of entropy that is in general less than the buffer size. The core must apply a mixing algorithm to the output of `"get_entropy"` to obtain full-entropy data.
+
+For example, the core may use a simple mixing scheme based on a pseudorandom function family $(F_k)$ with an $E$-bit output where $E = 8 \cdot \mathtt{entropy_size}$ and $\mathtt{entropy_size}$ is the desired amount of entropy in bytes (typically the random driver's `"initial_entropy_size"` property for the initial seeding and the `"reseed_entropy_size"` property for subsequent reseeding). The core calls the `"get_entropy"` points of the available entropy drivers, outputting a string $s_i$ and an entropy estimate $e_i$ on the $i$th call. It does so until the total entropy estimate $e_1 + e_2 + \ldots + e_n$ is at least $E$. The core then calculates $F_k(0)$ where $k = s_1 || s_2 || \ldots || s_n$. This value is a string of $\mathtt{entropy_size}$, and since $(F_k)$ is a pseudorandom function family, $F_k(0)$ is uniformly distributed over strings of $\mathtt{entropy_size}$ bytes. Therefore $F_k(0)$ is a suitable value to pass to `"add_entropy"`.
+
+Note that the mechanism above is only given as an example. Implementations may choose a different mechanism, for example involving multiple pools or intermediate compression functions.
+
+#### Random generator drivers without entropy injection
+
+Random generator drivers should have the capability to inject additional entropy through the `"add_entropy"` entry point. This ensures that the random generator depends on all the entropy sources that are available on the platform. A driver where a call to `"add_entropy"` does not affect the state of the random generator is not compliant with this specification.
+
+However, a driver may omit the `"add_entropy"` entry point. This limits the driver's portability: implementations of the PSA Cryptography specification may reject drivers without an `"add_entropy"` entry point, or only accept such drivers in certain configurations. In particular, the `"add_entropy"` entry point is required if:
+
+* the integration of PSA Cryptography includes an entropy source that is outside the driver; or
+* the core saves random data in persistent storage to be preserved across platform resets.
+
+#### The `"get_random"` entry point
+
+The `"get_random"` entry point has the following prototype for a driver with the prefix `"acme"`:
+
+```
+psa_status_t acme_get_random(acme_random_context_t *context,
+ uint8_t *output,
+ size_t output_size,
+ size_t *output_length);
+```
+
+The semantics of the parameters is as follows:
+
+* `context`: a random generation context. If the driver's `"initial_entropy_size"` property is nonzero, the core must have called `"add_entropy"` at least once with a total of at least `"initial_entropy_size"` bytes of entropy before it calls `"get_random"`. Alternatively, if the driver's `"initial_entropy_size"` property is zero and the core did not call `"add_entropy"`, or if the driver has no `"add_entropy"` entry point, the core must have called `"init_random"` if present, and otherwise the context is all-bits zero.
+* `output`: on success (including partial success), the first `*output_length` bytes of this buffer contain cryptographic-quality random data. The output is not used on error.
+* `output_size`: the size of the `output` buffer in bytes.
+* `*output_length`: on success (including partial success), the number of bytes of random data that the driver has written to the `output` buffer. This is preferably `output_size`, but the driver is allowed to return less data if it runs out of entropy as described below. The core sets this value to 0 on entry. The value is not used on error.
+
+The driver may return the following status codes:
+
+* `PSA_SUCCESS`: the `output` buffer contains `*output_length` bytes of cryptographic-quality random data. Note that this may be less than `output_size`; in this case the core should call the driver's `"add_entropy"` method to supply at least `"reseed_entropy_size"` bytes of entropy before calling `"get_random"` again.
+* `PSA_ERROR_INSUFFICIENT_ENTROPY`: the core must supply additional entropy by calling the `"add_entropy"` entry point with at least `"reseed_entropy_size"` bytes.
+* `PSA_ERROR_NOT_SUPPORTED`: the random generator is not available. This is only permitted if the driver specification for random generation has the [fallback property](#fallback) enabled.
+* Other error codes such as `PSA_ERROR_COMMUNICATION_FAILURE` or `PSA_ERROR_HARDWARE_FAILURE` indicate a transient or permanent error.
+
### Fallback
Sometimes cryptographic accelerators only support certain cryptographic mechanisms partially. The capability description language allows specifying some restrictions, including restrictions on key sizes, but it cannot cover all the possibilities that may arise in practice. Furthermore, it may be desirable to deploy the same binary image on different devices, only some of which have a cryptographic accelerators.
@@ -704,6 +850,19 @@
## Open questions
+### Value representation
+
+#### Integers
+
+It would be better if there was a uniform requirement on integer values. Do they have to be JSON integers? C preprocessor integers (which could be e.g. a macro defined in some header file)? C compile-time constants (allowing `sizeof`)?
+
+This choice is partly driven by the use of the values, so they might not be uniform. Note that if the value can be zero and it's plausible that the core would want to statically allocate an array of the given size, the core needs to know whether the value is 0 so that it could use code like
+```
+#if ACME_FOO_SIZE != 0
+ uint8_t foo[ACME_FOO_SIZE];
+#endif
+```
+
### Driver declarations
#### Declaring driver entry points
@@ -779,6 +938,26 @@
`psa_crypto_driver_get_persistent_state` does not identify the calling driver, so the driver needs to remember which driver it's calling. This may require a thread-local variable in a multithreaded core. Is this ok?
+### Randomness
+
+#### Input to `"add_entropy"`
+
+Should the input to the [`"add_entropy"` entry point](#entropy-injection) be a full-entropy buffer (with data from all entropy sources already mixed), raw entropy direct from the entropy sources, or give the core a choice?
+
+* Raw data: drivers must implement entropy mixing. `"add_entropy"` needs an extra parameter to indicate the amount of entropy in the data. The core must not do any conditioning.
+* Choice: drivers must implement entropy mixing. `"add_entropy"` needs an extra parameter to indicate the amount of entropy in the data. The core may do conditioning if it wants, but doesn't have to.
+* Full entropy: drivers don't need to do entropy mixing.
+
+#### Flags for `"get_entropy"`
+
+Are the [entropy collection flags](#entropy-collection-flags) well-chosen?
+
+#### Random generator instantiations
+
+May the core instantiate a random generation context more than once? In other words, can there be multiple objects of type `acme_random_context_t`?
+
+Functionally, one RNG is as good as any. If the core wants some parts of the system to use a deterministic generator for reproducibility, it can't use this interface anyway, since the RNG is not necessarily deterministic. However, for performance on multiprocessor systems, a multithreaded core could prefer to use one RNG instance per thread.
+
<!--
Local Variables:
time-stamp-line-limit: 40
diff --git a/include/psa/crypto_accel_driver.h b/include/psa/crypto_accel_driver.h
deleted file mode 100644
index 4488ea8..0000000
--- a/include/psa/crypto_accel_driver.h
+++ /dev/null
@@ -1,823 +0,0 @@
-/**
- * \file psa/crypto_accel_driver.h
- * \brief PSA cryptography accelerator driver module
- *
- * This header declares types and function signatures for cryptography
- * drivers that access key material directly. This is meant for
- * on-chip cryptography accelerators.
- *
- * This file is part of the PSA Crypto Driver Model, containing functions for
- * driver developers to implement to enable hardware to be called in a
- * standardized way by a PSA Cryptographic API implementation. The functions
- * comprising the driver model, which driver authors implement, are not
- * intended to be called by application developers.
- */
-
-/*
- * Copyright The Mbed TLS Contributors
- * SPDX-License-Identifier: Apache-2.0
- *
- * Licensed under the Apache License, Version 2.0 (the "License"); you may
- * not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
- * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-#ifndef PSA_CRYPTO_ACCEL_DRIVER_H
-#define PSA_CRYPTO_ACCEL_DRIVER_H
-
-#include "crypto_driver_common.h"
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-/** \defgroup driver_digest Hardware-Accelerated Message Digests
- *
- * Generation and authentication of Message Digests (aka hashes) must be done
- * in parts using the following sequence:
- * - `psa_drv_hash_setup_t`
- * - `psa_drv_hash_update_t`
- * - `psa_drv_hash_update_t`
- * - ...
- * - `psa_drv_hash_finish_t`
- *
- * If a previously started Message Digest operation needs to be terminated
- * before the `psa_drv_hash_finish_t` operation is complete, it should be aborted
- * by the `psa_drv_hash_abort_t`. Failure to do so may result in allocated
- * resources not being freed or in other undefined behavior.
- */
-/**@{*/
-
-/** \brief The hardware-specific hash context structure
- *
- * The contents of this structure are implementation dependent and are
- * therefore not described here
- */
-typedef struct psa_drv_hash_context_s psa_drv_hash_context_t;
-
-/** \brief The function prototype for the start operation of a hash (message
- * digest) operation
- *
- * Functions that implement this prototype should be named in the following
- * convention:
- * ~~~~~~~~~~~~~{.c}
- * psa_drv_hash_<ALGO>_setup
- * ~~~~~~~~~~~~~
- * Where `ALGO` is the name of the underlying hash function
- *
- * \param[in,out] p_context A structure that will contain the
- * hardware-specific hash context
- *
- * \retval #PSA_SUCCESS Success.
- */
-typedef psa_status_t (*psa_drv_hash_setup_t)(psa_drv_hash_context_t *p_context);
-
-/** \brief The function prototype for the update operation of a hash (message
- * digest) operation
- *
- * Functions that implement this prototype should be named in the following
- * convention:
- * ~~~~~~~~~~~~~{.c}
- * psa_drv_hash_<ALGO>_update
- * ~~~~~~~~~~~~~
- * Where `ALGO` is the name of the underlying algorithm
- *
- * \param[in,out] p_context A hardware-specific structure for the
- * previously-established hash operation to be
- * continued
- * \param[in] p_input A buffer containing the message to be appended
- * to the hash operation
- * \param[in] input_length The size in bytes of the input message buffer
- */
-typedef psa_status_t (*psa_drv_hash_update_t)(psa_drv_hash_context_t *p_context,
- const uint8_t *p_input,
- size_t input_length);
-
-/** \brief The function prototype for the finish operation of a hash (message
- * digest) operation
- *
- * Functions that implement this prototype should be named in the following
- * convention:
- * ~~~~~~~~~~~~~{.c}
- * psa_drv_hash_<ALGO>_finish
- * ~~~~~~~~~~~~~
- * Where `ALGO` is the name of the underlying algorithm
- *
- * \param[in,out] p_context A hardware-specific structure for the
- * previously started hash operation to be
- * fiinished
- * \param[out] p_output A buffer where the generated digest will be
- * placed
- * \param[in] output_size The size in bytes of the buffer that has been
- * allocated for the `p_output` buffer
- * \param[out] p_output_length The number of bytes placed in `p_output` after
- * success
- *
- * \retval #PSA_SUCCESS
- * Success.
- */
-typedef psa_status_t (*psa_drv_hash_finish_t)(psa_drv_hash_context_t *p_context,
- uint8_t *p_output,
- size_t output_size,
- size_t *p_output_length);
-
-/** \brief The function prototype for the abort operation of a hash (message
- * digest) operation
- *
- * Functions that implement this prototype should be named in the following
- * convention:
- * ~~~~~~~~~~~~~{.c}
- * psa_drv_hash_<ALGO>_abort
- * ~~~~~~~~~~~~~
- * Where `ALGO` is the name of the underlying algorithm
- *
- * \param[in,out] p_context A hardware-specific structure for the previously
- * started hash operation to be aborted
- */
-typedef void (*psa_drv_hash_abort_t)(psa_drv_hash_context_t *p_context);
-
-/**@}*/
-
-/** \defgroup accel_mac Hardware-Accelerated Message Authentication Code
- * Generation and authentication of Message Authentication Codes (MACs) using
- * cryptographic accelerators can be done either as a single function call (via the
- * `psa_drv_accel_mac_generate_t` or `psa_drv_accel_mac_verify_t`
- * functions), or in parts using the following sequence:
- * - `psa_drv_accel_mac_setup_t`
- * - `psa_drv_accel_mac_update_t`
- * - `psa_drv_accel_mac_update_t`
- * - ...
- * - `psa_drv_accel_mac_finish_t` or `psa_drv_accel_mac_finish_verify_t`
- *
- * If a previously started MAC operation needs to be terminated, it
- * should be done so by the `psa_drv_accel_mac_abort_t`. Failure to do so may
- * result in allocated resources not being freed or in other undefined
- * behavior.
- *
- */
-/**@{*/
-
-/** \brief The hardware-accelerator-specific MAC context structure
- *
- * The contents of this structure are implementation dependent and are
- * therefore not described here.
- */
-typedef struct psa_drv_accel_mac_context_s psa_drv_accel_mac_context_t;
-
-/** \brief The function prototype for the setup operation of a
- * hardware-accelerated MAC operation
- *
- * Functions that implement this prototype should be named in the following
- * convention:
- * ~~~~~~~~~~~~~{.c}
- * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_setup
- * ~~~~~~~~~~~~~
- * Where `ALGO` is the name of the underlying primitive, and `MAC_VARIANT`
- * is the specific variant of a MAC operation (such as HMAC or CMAC)
- *
- * \param[in,out] p_context A structure that will contain the
- * hardware-specific MAC context
- * \param[in] p_key A buffer containing the cleartext key material
- * to be used in the operation
- * \param[in] key_length The size in bytes of the key material
- *
- * \retval #PSA_SUCCESS
- * Success.
- */
-typedef psa_status_t (*psa_drv_accel_mac_setup_t)(psa_drv_accel_mac_context_t *p_context,
- const uint8_t *p_key,
- size_t key_length);
-
-/** \brief The function prototype for the update operation of a
- * hardware-accelerated MAC operation
- *
- * Functions that implement this prototype should be named in the following
- * convention:
- * ~~~~~~~~~~~~~{.c}
- * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_update
- * ~~~~~~~~~~~~~
- * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT`
- * is the specific variant of a MAC operation (such as HMAC or CMAC)
- *
- * \param[in,out] p_context A hardware-specific structure for the
- * previously-established MAC operation to be
- * continued
- * \param[in] p_input A buffer containing the message to be appended
- * to the MAC operation
- * \param[in] input_length The size in bytes of the input message buffer
- */
-typedef psa_status_t (*psa_drv_accel_mac_update_t)(psa_drv_accel_mac_context_t *p_context,
- const uint8_t *p_input,
- size_t input_length);
-
-/** \brief The function prototype for the finish operation of a
- * hardware-accelerated MAC operation
- *
- * Functions that implement this prototype should be named in the following
- * convention:
- * ~~~~~~~~~~~~~{.c}
- * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_finish
- * ~~~~~~~~~~~~~
- * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is
- * the specific variant of a MAC operation (such as HMAC or CMAC)
- *
- * \param[in,out] p_context A hardware-specific structure for the
- * previously started MAC operation to be
- * finished
- * \param[out] p_mac A buffer where the generated MAC will be placed
- * \param[in] mac_length The size in bytes of the buffer that has been
- * allocated for the `p_mac` buffer
- *
- * \retval #PSA_SUCCESS
- * Success.
- */
-typedef psa_status_t (*psa_drv_accel_mac_finish_t)(psa_drv_accel_mac_context_t *p_context,
- uint8_t *p_mac,
- size_t mac_length);
-
-/** \brief The function prototype for the finish and verify operation of a
- * hardware-accelerated MAC operation
- *
- * Functions that implement this prototype should be named in the following
- * convention:
- * ~~~~~~~~~~~~~{.c}
- * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_finish_verify
- * ~~~~~~~~~~~~~
- * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is
- * the specific variant of a MAC operation (such as HMAC or CMAC)
- *
- * \param[in,out] p_context A hardware-specific structure for the
- * previously started MAC operation to be
- * verified and finished
- * \param[in] p_mac A buffer containing the MAC that will be used
- * for verification
- * \param[in] mac_length The size in bytes of the data in the `p_mac`
- * buffer
- *
- * \retval #PSA_SUCCESS
- * The operation completed successfully and the comparison matched
- */
-typedef psa_status_t (*psa_drv_accel_mac_finish_verify_t)(psa_drv_accel_mac_context_t *p_context,
- const uint8_t *p_mac,
- size_t mac_length);
-
-/** \brief The function prototype for the abort operation for a previously
- * started hardware-accelerated MAC operation
- *
- * Functions that implement this prototype should be named in the following
- * convention:
- * ~~~~~~~~~~~~~{.c}
- * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_abort
- * ~~~~~~~~~~~~~
- * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is
- * the specific variant of a MAC operation (such as HMAC or CMAC)
- *
- * \param[in,out] p_context A hardware-specific structure for the
- * previously started MAC operation to be
- * aborted
- *
- */
-typedef psa_status_t (*psa_drv_accel_mac_abort_t)(psa_drv_accel_mac_context_t *p_context);
-
-/** \brief The function prototype for the one-shot operation of a
- * hardware-accelerated MAC operation
- *
- * Functions that implement this prototype should be named in the following
- * convention:
- * ~~~~~~~~~~~~~{.c}
- * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>
- * ~~~~~~~~~~~~~
- * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is
- * the specific variant of a MAC operation (such as HMAC or CMAC)
- *
- * \param[in] p_input A buffer containing the data to be MACed
- * \param[in] input_length The length in bytes of the `p_input` data
- * \param[in] p_key A buffer containing the key material to be used
- * for the MAC operation
- * \param[in] key_length The length in bytes of the `p_key` data
- * \param[in] alg The algorithm to be performed
- * \param[out] p_mac The buffer where the resulting MAC will be placed
- * upon success
- * \param[in] mac_length The length in bytes of the `p_mac` buffer
- */
-typedef psa_status_t (*psa_drv_accel_mac_t)(const uint8_t *p_input,
- size_t input_length,
- const uint8_t *p_key,
- size_t key_length,
- psa_algorithm_t alg,
- uint8_t *p_mac,
- size_t mac_length);
-
-/** \brief The function prototype for the one-shot hardware-accelerated MAC
- * Verify operation
- *
- * Functions that implement this prototype should be named in the following
- * convention:
- * ~~~~~~~~~~~~~{.c}
- * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_verify
- * ~~~~~~~~~~~~~
- * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is
- * the specific variant of a MAC operation (such as HMAC or CMAC)
- *
- * \param[in] p_input A buffer containing the data to be MACed
- * \param[in] input_length The length in bytes of the `p_input` data
- * \param[in] p_key A buffer containing the key material to be used
- * for the MAC operation
- * \param[in] key_length The length in bytes of the `p_key` data
- * \param[in] alg The algorithm to be performed
- * \param[in] p_mac The MAC data to be compared
- * \param[in] mac_length The length in bytes of the `p_mac` buffer
- *
- * \retval #PSA_SUCCESS
- * The operation completed successfully and the comparison matched
- */
-typedef psa_status_t (*psa_drv_accel_mac_verify_t)(const uint8_t *p_input,
- size_t input_length,
- const uint8_t *p_key,
- size_t key_length,
- psa_algorithm_t alg,
- const uint8_t *p_mac,
- size_t mac_length);
-/**@}*/
-
-/** \defgroup accel_cipher Hardware-Accelerated Block Ciphers
- * Encryption and Decryption using hardware-acceleration in block modes other
- * than ECB must be done in multiple parts, using the following flow:
- * - `psa_drv_accel_ciphersetup_t`
- * - `psa_drv_accel_cipher_set_iv_t` (optional depending upon block mode)
- * - `psa_drv_accel_cipher_update_t`
- * - `psa_drv_accel_cipher_update_t`
- * - ...
- * - `psa_drv_accel_cipher_finish_t`
- *
- * If a previously started hardware-accelerated Cipher operation needs to be
- * terminated, it should be done so by the `psa_drv_accel_cipher_abort_t`.
- * Failure to do so may result in allocated resources not being freed or in
- * other undefined behavior.
- */
-/**@{*/
-
-/** \brief The hardware-accelerator-specific cipher context structure
- *
- * The contents of this structure are implementation dependent and are
- * therefore not described here.
- */
-typedef struct psa_drv_accel_cipher_context_s psa_drv_accel_cipher_context_t;
-
-/** \brief The function prototype for the setup operation of
- * hardware-accelerated block cipher operations.
- * Functions that implement this prototype should be named in the following
- * conventions:
- * ~~~~~~~~~~~~~{.c}
- * psa_drv_accel_cipher_setup_<CIPHER_NAME>_<MODE>
- * ~~~~~~~~~~~~~
- * Where
- * - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES)
- * - `MODE` is the block mode of the cipher operation (i.e. CBC or CTR)
- *
- * For stream ciphers:
- * ~~~~~~~~~~~~~{.c}
- * psa_drv_accel_cipher_setup_<CIPHER_NAME>
- * ~~~~~~~~~~~~~
- * Where `CIPHER_NAME` is the name of a stream cipher (i.e. RC4)
- *
- * \param[in,out] p_context A structure that will contain the
- * hardware-specific cipher context
- * \param[in] direction Indicates if the operation is an encrypt or a
- * decrypt
- * \param[in] p_key_data A buffer containing the cleartext key material
- * to be used in the operation
- * \param[in] key_data_size The size in bytes of the key material
- *
- * \retval #PSA_SUCCESS
- */
-typedef psa_status_t (*psa_drv_accel_cipher_setup_t)(psa_drv_accel_cipher_context_t *p_context,
- psa_encrypt_or_decrypt_t direction,
- const uint8_t *p_key_data,
- size_t key_data_size);
-
-/** \brief The function prototype for the set initialization vector operation
- * of hardware-accelerated block cipher operations
- * Functions that implement this prototype should be named in the following
- * convention:
- * ~~~~~~~~~~~~~{.c}
- * psa_drv_accel_cipher_set_iv_<CIPHER_NAME>_<MODE>
- * ~~~~~~~~~~~~~
- * Where
- * - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES)
- * - `MODE` is the block mode of the cipher operation (i.e. CBC or CTR)
- *
- * \param[in,out] p_context A structure that contains the previously setup
- * hardware-specific cipher context
- * \param[in] p_iv A buffer containing the initialization vecotr
- * \param[in] iv_length The size in bytes of the contents of `p_iv`
- *
- * \retval #PSA_SUCCESS
- */
-typedef psa_status_t (*psa_drv_accel_cipher_set_iv_t)(psa_drv_accel_cipher_context_t *p_context,
- const uint8_t *p_iv,
- size_t iv_length);
-
-/** \brief The function prototype for the update operation of
- * hardware-accelerated block cipher operations.
- *
- * Functions that implement this prototype should be named in the following
- * convention:
- * ~~~~~~~~~~~~~{.c}
- * psa_drv_accel_cipher_update_<CIPHER_NAME>_<MODE>
- * ~~~~~~~~~~~~~
- * Where
- * - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES)
- * - `MODE` is the block mode of the cipher operation (i.e. CBC or CTR)
- *
- * \param[in,out] p_context A hardware-specific structure for the
- * previously started cipher operation
- * \param[in] p_input A buffer containing the data to be
- * encrypted or decrypted
- * \param[in] input_size The size in bytes of the `p_input` buffer
- * \param[out] p_output A caller-allocated buffer where the
- * generated output will be placed
- * \param[in] output_size The size in bytes of the `p_output` buffer
- * \param[out] p_output_length After completion, will contain the number
- * of bytes placed in the `p_output` buffer
- *
- * \retval #PSA_SUCCESS
- */
-typedef psa_status_t (*psa_drv_accel_cipher_update_t)(psa_drv_accel_cipher_context_t *p_context,
- const uint8_t *p_input,
- size_t input_size,
- uint8_t *p_output,
- size_t output_size,
- size_t *p_output_length);
-
-/** \brief The function prototype for the finish operation of
- * hardware-accelerated block cipher operations.
- *
- * Functions that implement this prototype should be named in the following
- * convention:
- * ~~~~~~~~~~~~~{.c}
- * psa_drv_accel_cipher_finish_<CIPHER_NAME>_<MODE>
- * ~~~~~~~~~~~~~
- * Where
- * - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES)
- * - `MODE` is the block mode of the cipher operation (i.e. CBC or CTR)
- *
- * \param[in,out] p_context A hardware-specific structure for the
- * previously started cipher operation
- * \param[out] p_output A caller-allocated buffer where the generated
- * output will be placed
- * \param[in] output_size The size in bytes of the `p_output` buffer
- * \param[out] p_output_length After completion, will contain the number of
- * bytes placed in the `p_output` buffer
- *
- * \retval #PSA_SUCCESS
- */
-typedef psa_status_t (*psa_drv_accel_cipher_finish_t)(psa_drv_accel_cipher_context_t *p_context,
- uint8_t *p_output,
- size_t output_size,
- size_t *p_output_length);
-
-/** \brief The function prototype for the abort operation of
- * hardware-accelerated block cipher operations.
- *
- * Functions that implement the following prototype should be named in the
- * following convention:
- * ~~~~~~~~~~~~~{.c}
- * psa_drv_accel_cipher_abort_<CIPHER_NAME>_<MODE>
- * ~~~~~~~~~~~~~
- * Where
- * - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES)
- * - `MODE` is the block mode of the cipher operation (i.e. CBC or CTR)
- *
- * \param[in,out] p_context A hardware-specific structure for the
- * previously started cipher operation
- *
- * \retval #PSA_SUCCESS
- */
-typedef psa_status_t (*psa_drv_accel_cipher_abort_t)(psa_drv_accel_cipher_context_t *p_context);
-
-/**@}*/
-
-/** \defgroup accel_aead Hardware-Accelerated Authenticated Encryption with Additional Data
- *
- * Hardware-accelerated Authenticated Encryption with Additional Data (AEAD)
- * operations must be done in one function call. While this creates a burden
- * for implementers as there must be sufficient space in memory for the entire
- * message, it prevents decrypted data from being made available before the
- * authentication operation is complete and the data is known to be authentic.
- */
-/**@{*/
-
-/** \brief The function prototype for the hardware-accelerated authenticated
- * encryption operation.
- *
- * Functions that implement this prototype should be named in the following
- * convention:
- * ~~~~~~~~~~~~~{.c}
- * psa_drv_accel_aead_<ALGO>_encrypt
- * ~~~~~~~~~~~~~
- * Where `ALGO` is the name of the AEAD algorithm
- *
- * \param[in] p_key A pointer to the key material
- * \param[in] key_length The size in bytes of the key material
- * \param[in] alg The AEAD algorithm to compute
- * (\c PSA_ALG_XXX value such that
- * #PSA_ALG_IS_AEAD(`alg`) is true)
- * \param[in] nonce Nonce or IV to use
- * \param[in] nonce_length Size of the `nonce` buffer in bytes
- * \param[in] additional_data Additional data that will be MACed
- * but not encrypted.
- * \param[in] additional_data_length Size of `additional_data` in bytes
- * \param[in] plaintext Data that will be MACed and
- * encrypted.
- * \param[in] plaintext_length Size of `plaintext` in bytes
- * \param[out] ciphertext Output buffer for the authenticated and
- * encrypted data. The additional data is
- * not part of this output. For algorithms
- * where the encrypted data and the
- * authentication tag are defined as
- * separate outputs, the authentication
- * tag is appended to the encrypted data.
- * \param[in] ciphertext_size Size of the `ciphertext` buffer in
- * bytes
- * This must be at least
- * #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(`alg`,
- * `plaintext_length`).
- * \param[out] ciphertext_length On success, the size of the output in
- * the `ciphertext` buffer
- *
- * \retval #PSA_SUCCESS
- *
- */
-typedef psa_status_t (*psa_drv_accel_aead_encrypt_t)(const uint8_t *p_key,
- size_t key_length,
- psa_algorithm_t alg,
- const uint8_t *nonce,
- size_t nonce_length,
- const uint8_t *additional_data,
- size_t additional_data_length,
- const uint8_t *plaintext,
- size_t plaintext_length,
- uint8_t *ciphertext,
- size_t ciphertext_size,
- size_t *ciphertext_length);
-
-/** \brief The function prototype for the hardware-accelerated authenticated
- * decryption operation.
- *
- * Functions that implement this prototype should be named in the following
- * convention:
- * ~~~~~~~~~~~~~{.c}
- * psa_drv_accel_aead_<ALGO>_decrypt
- * ~~~~~~~~~~~~~
- * Where `ALGO` is the name of the AEAD algorithm
- * \param[in] p_key A pointer to the key material
- * \param[in] key_length The size in bytes of the key material
- * \param[in] alg The AEAD algorithm to compute
- * (\c PSA_ALG_XXX value such that
- * #PSA_ALG_IS_AEAD(`alg`) is true)
- * \param[in] nonce Nonce or IV to use
- * \param[in] nonce_length Size of the `nonce` buffer in bytes
- * \param[in] additional_data Additional data that has been MACed
- * but not encrypted
- * \param[in] additional_data_length Size of `additional_data` in bytes
- * \param[in] ciphertext Data that has been MACed and
- * encrypted
- * For algorithms where the encrypted data
- * and the authentication tag are defined
- * as separate inputs, the buffer must
- * contain the encrypted data followed by
- * the authentication tag.
- * \param[in] ciphertext_length Size of `ciphertext` in bytes
- * \param[out] plaintext Output buffer for the decrypted data
- * \param[in] plaintext_size Size of the `plaintext` buffer in
- * bytes
- * This must be at least
- * #PSA_AEAD_DECRYPT_OUTPUT_SIZE(`alg`,
- * `ciphertext_length`).
- * \param[out] plaintext_length On success, the size of the output
- * in the \b plaintext buffer
- *
- * \retval #PSA_SUCCESS
- * Success.
- */
-typedef psa_status_t (*psa_drv_accel_aead_decrypt_t)(const uint8_t *p_key,
- size_t key_length,
- psa_algorithm_t alg,
- const uint8_t *nonce,
- size_t nonce_length,
- const uint8_t *additional_data,
- size_t additional_data_length,
- const uint8_t *ciphertext,
- size_t ciphertext_length,
- uint8_t *plaintext,
- size_t plaintext_size,
- size_t *plaintext_length);
-
-/**@}*/
-
-/** \defgroup accel_asymmetric Hardware-Accelerated Asymmetric Cryptography
- *
- * Since the amount of data that can (or should) be encrypted or signed using
- * asymmetric keys is limited by the key size, hardware-accelerated asymmetric
- * key operations must be done in single function calls.
- */
-/**@{*/
-
-
-/**
- * \brief The function prototype for the hardware-accelerated asymmetric sign
- * operation.
- *
- * Functions that implement this prototype should be named in the following
- * convention:
- * ~~~~~~~~~~~~~{.c}
- * psa_drv_accel_asymmetric_<ALGO>_sign
- * ~~~~~~~~~~~~~
- * Where `ALGO` is the name of the signing algorithm
- *
- * This function supports any asymmetric-key output from psa_export_key() as
- * the buffer in \p p_key. Refer to the documentation of \ref
- * psa_export_key() for the formats.
- *
- * \param[in] p_key A buffer containing the private key
- * material
- * \param[in] key_size The size in bytes of the `p_key` data
- * \param[in] alg A signature algorithm that is compatible
- * with the type of `p_key`
- * \param[in] p_hash The hash or message to sign
- * \param[in] hash_length Size of the `p_hash` buffer in bytes
- * \param[out] p_signature Buffer where the signature is to be written
- * \param[in] signature_size Size of the `p_signature` buffer in bytes
- * \param[out] p_signature_length On success, the number of bytes
- * that make up the returned signature value
- *
- * \retval #PSA_SUCCESS
- */
-typedef psa_status_t (*psa_drv_accel_asymmetric_sign_t)(const uint8_t *p_key,
- size_t key_size,
- psa_algorithm_t alg,
- psa_key_type_t key_type,
- const uint8_t *p_hash,
- size_t hash_length,
- uint8_t *p_signature,
- size_t signature_size,
- size_t *p_signature_length);
-
-/**
- * \brief The function prototype for the hardware-accelerated signature verify
- * operation
- *
- * Functions that implement this prototype should be named in the following
- * convention:
- * ~~~~~~~~~~~~~{.c}
- * psa_drv_accel_asymmetric_<ALGO>_verify
- * ~~~~~~~~~~~~~
- * Where `ALGO` is the name of the signing algorithm
- *
- * This function supports any output from \ref psa_export_public_key() as the
- * buffer in \p p_key. Refer to the documentation of \ref
- * psa_export_public_key() for the format of public keys and to the
- * documentation of \ref psa_export_key() for the format for other key types.
- *
- * \param[in] p_key A buffer containing the public key material
- * \param[in] key_size The size in bytes of the `p_key` data
- * \param[in] alg A signature algorithm that is compatible with
- * the type of `key`
- * \param[in] p_hash The hash or message whose signature is to be
- * verified
- * \param[in] hash_length Size of the `p_hash` buffer in bytes
- * \param[in] p_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.
- */
-typedef psa_status_t (*psa_drv_accel_asymmetric_verify_t)(const uint8_t *p_key,
- size_t key_size,
- psa_algorithm_t alg,
- psa_key_type_t key_type,
- const uint8_t *p_hash,
- size_t hash_length,
- const uint8_t *p_signature,
- size_t signature_length);
-
-/**
- * \brief The function prototype for the hardware-accelerated asymmetric
- * encrypt operation
- *
- * Functions that implement this prototype should be named in the following
- * convention:
- * ~~~~~~~~~~~~~{.c}
- * psa_drv_accel_asymmetric_<ALGO>_encrypt
- * ~~~~~~~~~~~~~
- * Where `ALGO` is the name of the encryption algorithm
- *
- * This function supports any output from \ref psa_export_public_key() as the
- * buffer in \p p_key. Refer to the documentation of \ref
- * psa_export_public_key() for the format of public keys and to the
- * documentation of \ref psa_export_key() for the format for other key types.
- *
- * \param[in] p_key A buffer containing the public key material
- * \param[in] key_size The size in bytes of the `p_key` data
- * \param[in] alg An asymmetric encryption algorithm that is
- * compatible with the type of `key`
- * \param[in] p_input The message to encrypt
- * \param[in] input_length Size of the `p_input` buffer in bytes
- * \param[in] p_salt A salt or label, if supported by the
- * encryption algorithm
- * If the algorithm does not support a
- * salt, pass `NULL`
- * If the algorithm supports an optional
- * salt and you do not want to pass a salt,
- * pass `NULL`.
- * For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
- * supported.
- * \param[in] salt_length Size of the `p_salt` buffer in bytes
- * If `p_salt` is `NULL`, pass 0.
- * \param[out] p_output Buffer where the encrypted message is to
- * be written
- * \param[in] output_size Size of the `p_output` buffer in bytes
- * \param[out] p_output_length On success, the number of bytes
- * that make up the returned output
- *
- * \retval #PSA_SUCCESS
- */
-typedef psa_status_t (*psa_drv_accel_asymmetric_encrypt_t)(const uint8_t *p_key,
- size_t key_size,
- psa_algorithm_t alg,
- psa_key_type_t key_type,
- const uint8_t *p_input,
- size_t input_length,
- const uint8_t *p_salt,
- size_t salt_length,
- uint8_t *p_output,
- size_t output_size,
- size_t *p_output_length);
-
-/**
- * \brief The function prototype for the hardware=acce;erated asymmetric
- * decrypt operation
- *
- * Functions that implement this prototype should be named in the following
- * convention:
- * ~~~~~~~~~~~~~{.c}
- * psa_drv_accel_asymmetric_<ALGO>_decrypt
- * ~~~~~~~~~~~~~
- * Where `ALGO` is the name of the encryption algorithm
- *
- * This function supports any asymmetric-key output from psa_export_key() as
- * the buffer in \p p_key. Refer to the documentation of \ref
- * psa_export_key() for the formats.
- *
- * \param[in] p_key A buffer containing the private key material
- * \param[in] key_size The size in bytes of the `p_key` data
- * \param[in] alg An asymmetric encryption algorithm that is
- * compatible with the type of `key`
- * \param[in] p_input The message to decrypt
- * \param[in] input_length Size of the `p_input` buffer in bytes
- * \param[in] p_salt A salt or label, if supported by the
- * encryption algorithm
- * If the algorithm does not support a
- * salt, pass `NULL`.
- * If the algorithm supports an optional
- * salt and you do not want to pass a salt,
- * pass `NULL`.
- * For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
- * supported
- * \param[in] salt_length Size of the `p_salt` buffer in bytes
- * If `p_salt` is `NULL`, pass 0
- * \param[out] p_output Buffer where the decrypted message is to
- * be written
- * \param[in] output_size Size of the `p_output` buffer in bytes
- * \param[out] p_output_length On success, the number of bytes
- * that make up the returned output
- *
- * \retval #PSA_SUCCESS
- */
-typedef psa_status_t (*psa_drv_accel_asymmetric_decrypt_t)(const uint8_t *p_key,
- size_t key_size,
- psa_algorithm_t alg,
- psa_key_type_t key_type,
- const uint8_t *p_input,
- size_t input_length,
- const uint8_t *p_salt,
- size_t salt_length,
- uint8_t *p_output,
- size_t output_size,
- size_t *p_output_length);
-
-/**@}*/
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* PSA_CRYPTO_ACCEL_DRIVER_H */
diff --git a/include/psa/crypto_driver_common.h b/include/psa/crypto_driver_common.h
index 2ce75d2..1b6f322 100644
--- a/include/psa/crypto_driver_common.h
+++ b/include/psa/crypto_driver_common.h
@@ -5,9 +5,8 @@
* This file contains common definitions shared by all PSA crypto drivers.
* Do not include it directly: instead, include the header file(s) for
* the type(s) of driver that you are implementing. For example, if
- * you are writing a driver for a chip that provides both a hardware
- * random generator and an accelerator for some cryptographic algorithms,
- * include `psa/crypto_entropy_driver.h` and `psa/crypto_accel_driver.h`.
+ * you are writing a dynamically registered driver for a secure element,
+ * include `psa/crypto_se_driver.h`.
*
* This file is part of the PSA Crypto Driver Model, containing functions for
* driver developers to implement to enable hardware to be called in a
diff --git a/include/psa/crypto_entropy_driver.h b/include/psa/crypto_entropy_driver.h
deleted file mode 100644
index 9b6546e..0000000
--- a/include/psa/crypto_entropy_driver.h
+++ /dev/null
@@ -1,108 +0,0 @@
-/**
- * \file psa/crypto_entropy_driver.h
- * \brief PSA entropy source driver module
- *
- * This header declares types and function signatures for entropy sources.
- *
- * This file is part of the PSA Crypto Driver Model, containing functions for
- * driver developers to implement to enable hardware to be called in a
- * standardized way by a PSA Cryptographic API implementation. The functions
- * comprising the driver model, which driver authors implement, are not
- * intended to be called by application developers.
- */
-
-/*
- * Copyright The Mbed TLS Contributors
- * SPDX-License-Identifier: Apache-2.0
- *
- * Licensed under the Apache License, Version 2.0 (the "License"); you may
- * not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
- * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-#ifndef PSA_CRYPTO_ENTROPY_DRIVER_H
-#define PSA_CRYPTO_ENTROPY_DRIVER_H
-
-#include "crypto_driver_common.h"
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-/** \defgroup driver_rng Entropy Generation
- */
-/**@{*/
-
-/** \brief Initialize an entropy driver
- *
- *
- * \param[in,out] p_context A hardware-specific structure
- * containing any context information for
- * the implementation
- *
- * \retval #PSA_SUCCESS
- */
-typedef psa_status_t (*psa_drv_entropy_init_t)(void *p_context);
-
-/** \brief Get a specified number of bits from the entropy source
- *
- * It retrives `buffer_size` bytes of data from the entropy source. The entropy
- * source will always fill the provided buffer to its full size, however, most
- * entropy sources have biases, and the actual amount of entropy contained in
- * the buffer will be less than the number of bytes.
- * The driver will return the actual number of bytes of entropy placed in the
- * buffer in `p_received_entropy_bytes`.
- * A PSA Crypto API implementation will likely feed the output of this function
- * into a Digital Random Bit Generator (DRBG), and typically has a minimum
- * amount of entropy that it needs.
- * To accomplish this, the PSA Crypto implementation should be designed to call
- * this function multiple times until it has received the required amount of
- * entropy from the entropy source.
- *
- * \param[in,out] p_context A hardware-specific structure
- * containing any context information
- * for the implementation
- * \param[out] p_buffer A caller-allocated buffer for the
- * retrieved entropy to be placed in
- * \param[in] buffer_size The allocated size of `p_buffer`
- * \param[out] p_received_entropy_bits The amount of entropy (in bits)
- * actually provided in `p_buffer`
- *
- * \retval #PSA_SUCCESS
- */
-typedef psa_status_t (*psa_drv_entropy_get_bits_t)(void *p_context,
- uint8_t *p_buffer,
- uint32_t buffer_size,
- uint32_t *p_received_entropy_bits);
-
-/**
- * \brief A struct containing all of the function pointers needed to interface
- * to an entropy source
- *
- * PSA Crypto API implementations should populate instances of the table as
- * appropriate upon startup.
- *
- * If one of the functions is not implemented, it should be set to NULL.
- */
-typedef struct {
- /** The driver-specific size of the entropy context */
- const size_t context_size;
- /** Function that performs initialization for the entropy source */
- psa_drv_entropy_init_t p_init;
- /** Function that performs the get_bits operation for the entropy source */
- psa_drv_entropy_get_bits_t p_get_bits;
-} psa_drv_entropy_t;
-/**@}*/
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* PSA_CRYPTO_ENTROPY_DRIVER_H */
diff --git a/programs/test/cpp_dummy_build.cpp b/programs/test/cpp_dummy_build.cpp
index c69cd2b..5abb46a 100644
--- a/programs/test/cpp_dummy_build.cpp
+++ b/programs/test/cpp_dummy_build.cpp
@@ -111,8 +111,6 @@
#include "psa/crypto.h"
#include "psa/crypto_se_driver.h"
-#include "psa/crypto_entropy_driver.h"
-#include "psa/crypto_accel_driver.h"
#include "../library/psa_crypto_its.h"
int main()
diff --git a/tests/scripts/test_psa_constant_names.py b/tests/scripts/test_psa_constant_names.py
index c7011a7..bead60c 100755
--- a/tests/scripts/test_psa_constant_names.py
+++ b/tests/scripts/test_psa_constant_names.py
@@ -94,8 +94,12 @@
self.dh_groups = set(['0xff'])
self.key_types = set(['0xffff'])
self.key_usage_flags = set(['0x80000000'])
- # Hard-coded value for unknown algorithms
- self.hash_algorithms = set(['0x020000fe'])
+ # Hard-coded values for unknown algorithms
+ #
+ # These have to have values that are correct for their respective
+ # PSA_ALG_IS_xxx macros, but are also not currently assigned and are
+ # not likely to be assigned in the near future.
+ self.hash_algorithms = set(['0x020000fe']) # 0x020000ff is PSA_ALG_ANY_HASH
self.mac_algorithms = set(['0x0300ffff'])
self.ka_algorithms = set(['0x09fc0000'])
self.kdf_algorithms = set(['0x080000ff'])
diff --git a/visualc/VS2010/mbedTLS.vcxproj b/visualc/VS2010/mbedTLS.vcxproj
index 0af4145..440cc11 100644
--- a/visualc/VS2010/mbedTLS.vcxproj
+++ b/visualc/VS2010/mbedTLS.vcxproj
@@ -222,11 +222,9 @@
<ClInclude Include="..\..\include\mbedtls\x509_csr.h" />
<ClInclude Include="..\..\include\mbedtls\xtea.h" />
<ClInclude Include="..\..\include\psa\crypto.h" />
- <ClInclude Include="..\..\include\psa\crypto_accel_driver.h" />
<ClInclude Include="..\..\include\psa\crypto_compat.h" />
<ClInclude Include="..\..\include\psa\crypto_config.h" />
<ClInclude Include="..\..\include\psa\crypto_driver_common.h" />
- <ClInclude Include="..\..\include\psa\crypto_entropy_driver.h" />
<ClInclude Include="..\..\include\psa\crypto_extra.h" />
<ClInclude Include="..\..\include\psa\crypto_platform.h" />
<ClInclude Include="..\..\include\psa\crypto_se_driver.h" />