API Description

Random number generation.

Enumerations
enum	odp_random_kind_t { ODP_RANDOM_BASIC , ODP_RANDOM_CRYPTO , ODP_RANDOM_TRUE }
	Random kind selector. More...

Functions
odp_random_kind_t	odp_random_max_kind (void)
	Query random max kind. More...

int32_t	odp_random_data (uint8_t *buf, uint32_t len, odp_random_kind_t kind)
	Generate random byte data. More...

int32_t	odp_random_test_data (uint8_t buf, uint32_t len, uint64_t seed)
	Generate repeatable random data for testing purposes. More...

Enumeration Type Documentation

◆ odp_random_kind_t

enum odp_random_kind_t

Random kind selector.

The kind of random denotes the statistical quality of the random data returned. Basic random simply appears uniformly distributed, Cryptographic random is statistically random and suitable for use by cryptographic functions. True random is generated from a hardware entropy source rather than an algorithm and is thus completely unpredictable. These form a hierarchy where higher quality data is presumably more costly to generate than lower quality data.

Enumerator

ODP_RANDOM_BASIC

Basic random, presumably pseudo-random generated by SW.

This is the lowest kind of random

ODP_RANDOM_CRYPTO

Cryptographic quality random.

ODP_RANDOM_TRUE

True random, generated from a HW entropy source.

This is the highest kind of random

Definition at line 37 of file spec/random_types.h.

Function Documentation

◆ odp_random_max_kind()

odp_random_kind_t odp_random_max_kind ( void )

Query random max kind.

Implementations support the returned max kind and all kinds weaker than it.

Returns: kind The maximum odp_random_kind_t supported by this implementation

Examples: odp_random.c.

◆ odp_random_data()

int32_t odp_random_data	(	uint8_t *	buf,
		uint32_t	len,
		odp_random_kind_t	kind
	)

Generate random byte data.

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.

Parameters

[out]	buf	Output buffer
	len	Length of output buffer in bytes
	kind	Specifies the type of random data required. Request is expected to fail if the implementation is unable to provide the requested type.

Returns: Number of bytes written (0...len).

Return values

<0	on failure

Examples: ipsec_crypto/odp_ipsec.c, odp_packet_gen.c, odp_random.c, and odp_traffic_mgmt.c.

◆ odp_random_test_data()

int32_t odp_random_test_data	(	uint8_t *	buf,
		uint32_t	len,
		uint64_t *	seed
	)

Generate repeatable random data for testing purposes.

For testing purposes it is often useful to generate "random" sequences that are repeatable. This is accomplished by supplying a seed value that is used for pseudo-random data generation. The caller-provided seed value is updated for each call to continue the sequence. Restarting the same series of calls with the same initial seed value will generate the same sequence of random test data.

This function returns data of ODP_RANDOM_BASIC quality and should be used only for testing purposes. Use odp_random_data() for production.