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

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

Commit Message

Bill Fischofer Dec. 5, 2016, 1:15 a.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>

---
Changes in v5:
- Change return type from int to int32_t for random APIs

Changes in v4:
- Normalize random API signatures with other ODP APIs
- Add new odp_random_seeded_data() API for repeatable random data generation
- Add additional tests for new odp_random_seeded_data() API
- Break out crypto section of User Guide to its own sub-document
- Add User Guide docuemntation for ODP random data API.

Changes in v3:
- Address commments by Petri
- Rename ODP_RAND_NORMAL to ODP_RANDOM_BASIC to avoid confusion with the
mathematical term "normal"

 include/odp/api/spec/random.h | 31 ++++++++++++++++++++++++++-----
 1 file changed, 26 insertions(+), 5 deletions(-)

-- 
2.7.4

Comments

Savolainen, Petri (Nokia - FI/Espoo) Dec. 5, 2016, 2:34 p.m. | #1
> -int32_t odp_random_data(uint8_t *buf, int32_t size, odp_bool_t

> use_entropy);

> +int32_t odp_random_data(uint8_t *buf, uint32_t len, odp_random_kind_t

> kind);


I think this an acceptable compromise, although int32_t on both (len and return) would help user to pick the type which can be compared directly with return value. I'm OK if this compiles:

uint8_t buf[32];
int32_t len = sizeof(buf);

if (odp_random_data(buf, len, ODP_RANDOM_TRUE) < len)
    printf("not enough data");


-Petri
Bill Fischofer Dec. 5, 2016, 2:41 p.m. | #2
On Mon, Dec 5, 2016 at 8:34 AM, Savolainen, Petri (Nokia - FI/Espoo)
<petri.savolainen@nokia-bell-labs.com> wrote:
>

>> -int32_t odp_random_data(uint8_t *buf, int32_t size, odp_bool_t

>> use_entropy);

>> +int32_t odp_random_data(uint8_t *buf, uint32_t len, odp_random_kind_t

>> kind);

>

> I think this an acceptable compromise, although int32_t on both (len and return) would help user to pick the type which can be compared directly with return value. I'm OK if this compiles:

>

> uint8_t buf[32];

> int32_t len = sizeof(buf);

>

> if (odp_random_data(buf, len, ODP_RANDOM_TRUE) < len)

>     printf("not enough data");


This is what the random.c validation test is doing, so this should be
OK. Are you still looking to split out the capability into a separate
odp_random_capability() API?

>

>

> -Petri

Patch

diff --git a/include/odp/api/spec/random.h b/include/odp/api/spec/random.h
index 00fa15b..e732c3a 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 {
+	/** Basic random, presumably pseudo-random generated by SW */
+	ODP_RANDOM_BASIC,
+	/** Cryptographic quality random */
+	ODP_RANDOM_CRYPTO,
+	/** True random, generated from a HW entropy source */
+	ODP_RANDOM_TRUE,
+} odp_random_kind_t;
+
+/**
  * Generate random byte data
  *
- * @param[out]    buf   Output buffer
- * @param         size  Size of output buffer
- * @param use_entropy   Use entropy
+ * The intent in supporting different kinds of random data is to allow
+ * tradeoffs between performance and the quality of random data needed. The
+ * assumption is that basic 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.
  *
- * @todo Define the implication of the use_entropy parameter
+ * @param[out]    buf   Output buffer
+ * @param         len   Length of output buffer in bytes
+ * @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
  */
-int32_t odp_random_data(uint8_t *buf, int32_t size, odp_bool_t use_entropy);
+int32_t odp_random_data(uint8_t *buf, uint32_t len, odp_random_kind_t kind);
 
 /**
  * @}