SysSrandom(), SysSrandom_r()
Supply entropy to the kernel's PNRG, retrieve entropy collected by the kernel, or both
Synopsis:
#include <sys/neutrino.h>
int SysSrandom( const uint64_t *seedp, uint64_t *entropy,
size_t elements );
int SysSrandom_r( const uint64_t *seedp, uint64_t *entropy,
size_t elements );
Arguments:
- seedp
- A pointer to a 64-bit seed to provide as entropy for the kernel's pseudorandom number generator (PRNG). If NULL, no seed is provided.
- entropy
- An array the kernel populates with entropy it obtains from internal sources such as interrupt timings. Can be NULL only if elements is 0.
- elements
- The number of elements in the array pointed to by entropy. If 0, entropy is not retrieved and can be NULL.
Library:
libc
Use the -l c option to qcc to link against this library. This library is usually included automatically.
Description:
The SysSrandom() and SysSrandom_r() kernel calls supply 64-bits of entropy to the kernel's pseudorandom number generator (PRNG), query the kernel for accumulated entropy, or both.
The PRNG is used with address space layout randomization (ASLR) and AArch64 Pointer Authentication per-process keys.
For more information about ASLR, refer to
Address space layout randomization (ASLR)
in the System Security Guide,
and for more information about pointer authentication keys, refer to
DCMD_PROC_GETREGSET
in the Programmer's Guide.
These calls make it possible to use an external source, such as a random number generator implemented in hardware,
to augment the other sources of entropy.
These functions are identical except in the way they indicate errors. See the Returns section for details.
- To use these calls to query the kernel for entropy, your process must have the PROCMGR_AID_SRANDOM ability enabled.
For more information, see
Abilities
in the System Security Guide. - Trace event logs intentionally don't include the new value of the source of entropy, for security reasons.
Blocking states
These calls don't block.
Returns:
EOK on success. If an error occurs:
- SysSrandom() returns -1 and sets errno.
- SysSrandom_r() returns any value from the Errors section and doesn't set errno.
Errors:
- EFAULT
- The destination buffer for gathering entropy is not valid.
- EPERM
- The calling process doesn't have the required permission; see
Abilities
in the System Security Guide.
Classification:
| Safety: | |
|---|---|
| Cancellation point | No |
| Signal handler | Yes |
| Thread | Yes |