[API-NEXT,PATCHv2,1/4] api: random: replace use_entropy with odp_rand_kind parameter

Message ID 1477432992-21770-1-git-send-email-bill.fischofer@linaro.org
State New
Headers show

Commit Message

Bill Fischofer Oct. 25, 2016, 10:03 p.m.
Address bug https://bugs.linaro.org/show_bug.cgi?id=2557 by replacing the
use_entropy parameter with a more comprehensive enum that specifies the
kind of random data requested.

Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org>

---
 include/odp/api/spec/random.h | 29 +++++++++++++++++++++++++----
 1 file changed, 25 insertions(+), 4 deletions(-)

-- 
2.7.4

Patch

diff --git a/include/odp/api/spec/random.h b/include/odp/api/spec/random.h
index 00fa15b..97df4bc 100644
--- a/include/odp/api/spec/random.h
+++ b/include/odp/api/spec/random.h
@@ -24,18 +24,39 @@  extern "C" {
  */
 
 /**
+ * Random kind selector
+ */
+typedef enum {
+	/** Normal random, presumably pseudo-random generated by SW */
+	ODP_RAND_NORMAL,
+	/** Cryptographic quality random */
+	ODP_RAND_CRYPTO,
+	/** True random, generated from a HW entropy source */
+	ODP_RAND_TRUE,
+} odp_rand_kind_t;
+
+/**
  * Generate random byte data
  *
  * @param[out]    buf   Output buffer
  * @param         size  Size of output buffer
- * @param use_entropy   Use entropy
- *
- * @todo Define the implication of the use_entropy parameter
+ * @param         kind  Specifies the type of random data required. Request
+ *                      is expected to fail if the implementation is unable to
+ *                      provide the requested type.
  *
  * @return Number of bytes written
  * @retval <0 on failure
+ *
+ * @note The indent in supporting different kinds of random data is to allow
+ * tradeoffs between performance and the quality of random data needed. The
+ * assumption is that normal random is cheap while true random is relatively
+ * expensive in terms of time to generate, with cryptographic random being
+ * something in between. Implementations that support highly efficient true
+ * random are free to use this for all requested kinds. So it is always
+ * permissible to "upgrade" a random data request, but never to "downgrade"
+ * such requests.
  */
-int32_t odp_random_data(uint8_t *buf, int32_t size, odp_bool_t use_entropy);
+int32_t odp_random_data(uint8_t *buf, int32_t size, odp_rand_kind_t kind);
 
 /**
  * @}