Prosody IM Website


file doc/developers/util/crand.md in changeset 5edcaf4e11a9

View latest ↓ Download file

line wrap: on
line source

---
abstract: Binding to native platform RNG
title: util.crand
---

Prosody normally opens and reads from the special device file
`/dev/urandom` to acquire pseudorandom data. On some constrained
platforms such as containers or jails this might not be available. This
is where the optional `util.crand` module comes in. It is a compiled
binary module that can provide access to a different pseudorandom data
generator.

# Usage

`util.crand` should not be used directly, instead use
[`util.random`](/doc/developers/util/random).

# API

The API provided is the same as
[`util.random`](/doc/developers/util/random), which simply redirects to
the `util.crand` module if available.

# Available backends

To use `util.crand` you need to select a suitable backend using the
`./configure` script at build time.

## Linux getrandom

The `getrandom()` system call in Linux is a different interface to the
same random generator as `/dev/urandom`.

``` {.sh}
./configure --with-random=getrandom
```

## BSD arc4random

Used in `/dev/urandom` on some \*BSD operating systems. Can also be used
on Linux via a *libbsd* package on some distributions.

``` {.sh}
./configure --with-random=arc4random
```

## OpenSSL

Prosody already uses OpenSSL for [cryptographic hash
functions](/doc/developers/util/hashes) and SSL/TLS. OpenSSL also
includes an API for getting random data.

``` {.sh}
./configure --with-random=openssl
```