yuzu-emu/mbedtls
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Make add_entropy optional

Browse source 
A random generation driver does not need to support entropy injection.
This will limit it to platforms where the RNG peripheral is the sole
entropy source and without an RNG seed saved into persistent storage.

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
This commit is contained in:
Gilles Peskine 2020-11-13 14:40:57 +01:00
parent 390c5a2c6f
commit a14326f054
1 changed files with 12 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
docs/proposed/psa-driver-interface.md
View file

@ -484,9 +484,9 @@ This operation family requires the following type, entry points and parameters (
* 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, mandatory): the core calls this function to [inject entropy](#entropy-injection).
* `"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.
* `"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, optional): 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 includes an entropy source of its own. If omitted, the value is `0`.
* `"initial_entropy_size"` (integer, optional): 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. If omitted, the value is `0`.
* `"reseed_entropy_size"` (integer, optional): the minimum number of bytes of entropy that the core must supply 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 chooses a value which is at least the expected security strength of the device.
Random generation is not parametrized by an algorithm. The choice of algorithm is up to the driver.
@ -528,6 +528,15 @@ The core may call this function at any time. For example, to enforce prediction
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"`.
#### 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"`:
@ -541,7 +550,7 @@ psa_status_t acme_get_random(acme_random_context_t *context,
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"`, the core must have called `"init_random"` if present, and otherwise the context is all-bits zero.
* `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 or partial success, the first `*output_length` bytes of this buffer contain cryptographic-quality random data.
* `output_size`: the size of the `output` buffer in bytes.
* `*output_length`: on exit, 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.