Don't require a call to add_entropy when 0 bytes are needed

If an RNG peripheral includes an entropy source, it would presumably
declare "initial_entropy_size" and "reseed_entropy_size" to be 0. In
this case, don't require the core to call "add_entropy".

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
This commit is contained in:
Gilles Peskine 2020-11-13 14:20:03 +01:00
parent 5263e1ecdd
commit 0e3b7ced4c

View file

@ -486,8 +486,8 @@ This operation family requires the following type, entry points and parameters (
* `"init_random"` (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): the core calls this function to [inject entropy](#entropy-injection).
* `"get_random"` (entry point): the core calls this function whenever it needs to [obtain random data](#the-get_random-entry-point).
* `"initial_entropy_size"` (integer): the minimum number of bytes of entropy that the core must supply before the driver can output random data.
* `"reseed_entropy_size"` (integer): the minimum number of bytes of entropy that the core must supply when the driver runs out of entropy.
* `"initial_entropy_size"` (integer): 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.
* `"reseed_entropy_size"` (integer): the minimum number of bytes of entropy that the core must supply when the driver runs out of entropy. This can be `0` if the driver includes an entropy source of its own.
Random generation is not parametrized by an algorithm. The choice of algorithm is up to the driver.
@ -501,7 +501,7 @@ 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"` will be 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
@ -526,7 +526,7 @@ The core may call this function at any time. For example, to enforce prediction
* Before any 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 `"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.
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"`.
#### The `"get_random"` entry point
@ -541,7 +541,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. 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"`.
* `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.
* `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.