os_random.h File Reference

Module. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
ORDO_PUBLIC int	os_random (void *out, size_t len)
ORDO_PUBLIC int	os_secure_random (void *out, size_t len)

Detailed Description

Module.

Exposes the OS CSPRNG (Cryptographically Secure PseudoRandom Number Generator) interface, which is basically a cross-platform wrapper to the OS-provided entropy pool. To learn more about how it is implemented, go to the source code or find out what facilities your operating system provides for entropy gathering.

Function Documentation

ORDO_PUBLIC int os_random	(	void *	out,
		size_t	len
	)

Generates cryptographically secure pseudorandom numbers.

Parameters

[out]	out	The destination buffer.
[in]	len	The number of bytes to generate.

Returns

ORDO_SUCCESS on success, else an error code.

Remarks

This function uses the CSPRNG provided by your operating system.

If the platform does not provide this feature, this function will always fail with the ORDO_FAIL error message, and any data in the buffer should be discarded as indeterminate.

ORDO_PUBLIC int os_secure_random	(	void *	out,
		size_t	len
	)

Generates cryptographically secure pseudorandom numbers, the function will make a best effort attempt to access the operating system entropy pool and so, ideally, should return exactly len bytes of entropy, whereas the os_random() function need only return enough entropy for the output stream to be computationally indistinguishable from a non-random stream. However, keep in mind that this function is not required to behave as such.

Parameters

[out]	out	The destination buffer.
[in]	len	The number of bytes to generate.

Returns

ORDO_SUCCESS on success, else an error code.

Warning

If your platform doesn't provide this feature, this function will fall back to os_random() (there is no way to know whether this feature is available, this is by design).

You should not need to know whether this feature is available, as this function will make a "best effort" attempt to obtain entropy from the operating system - you should use this function for high security uses such as generating private keys (it has a high cost so don't use it for e.g. nonces and initialization vectors).