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>
diff --git a/docs/proposed/psa-driver-interface.md b/docs/proposed/psa-driver-interface.md
index b036ccb..c80b406 100644
--- a/docs/proposed/psa-driver-interface.md
+++ b/docs/proposed/psa-driver-interface.md
@@ -486,8 +486,8 @@
* `"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 @@
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 @@
* 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 @@
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.
