GETENTROPY(3)

GETENTROPY(3) | Library Functions Manual | GETENTROPY(3)

# NAME

`getentropy` —
generate uniform random seeds from system entropy for cryptography

# LIBRARY

Standard C Library (libc, -lc)

# SYNOPSIS

`#include <unistd.h>`

int
`getentropy`(void *buf, size_t buflen);

`#include <limits.h>`

`#define GETENTROPY_MAX 256`

# DESCRIPTION

The `getentropy` function fills buf with exactly buflen independent uniform random bytes derived from the system's entropy pool.

The output of `getentropy` is meant to be unpredictable to an adversary and fit for use in cryptography. See CAVEATS below.

`getentropy` is meant for seeding random number generators, not for direct use by applications; most applications should use arc4random(3).

buflen must be at most 256.

# RETURN VALUES

The `getentropy`() function returns the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error.

# ERRORS

`getentropy`() will succeed unless:

[`EFAULT`]
  The buf argument points to an invalid memory address.
[`EINVAL`]
  More than 256 bytes were requested.

# CAVEATS

Security can only be guaranteed relative to whatever unpredictable physical processes or secret seed material are available to the system; see entropy(7).

On systems which have no hardware random number generator and which have not had secret seed material loaded, NetBSD makes a reasonable effort to incorporate samples from various physical processes available to it that might be unpredictable from random jitter in timing.

However, the `getentropy` interface alone can make no security guarantees without a physical system configuration that includes random number generation hardware or secret seed material from such hardware on another machine.

# SEE ALSO

arc4random(3), rnd(4), entropy(7)

# STANDARDS

The `getentropy`() function is nonstandard. However, it is likely to be included in the next revision of POSIX.

# HISTORY

The `getentropy`() function first appeared in OpenBSD 5.6, then in FreeBSD 12.0, and in NetBSD 10.0.

February 28, 2023 | NetBSD 10.0