Usage

Search…
Usage
1
#include <sodium.h>
2
​
3
int main(void)
4
{
5
    if (sodium_init() == -1) {
6
        return 1;
7
    }
8
    ...
9
}
Copied!
sodium.h is the only header that has to be included.
The library is called sodium (use -lsodium to link it), and proper compilation/linker flags can be obtained using pkg-config on systems where it is available:
1
CFLAGS=$(pkg-config --cflags libsodium)
2
LDFLAGS=$(pkg-config --libs libsodium)
Copied!
For static linking, Visual Studio users should define SODIUM_STATIC=1 and SODIUM_EXPORT=. This is not required on other platforms.
Projects using CMake can include the Findsodium.cmake file from the Facebook Fizz project to detect and link the library.
sodium_init() initializes the library and should be called before any other function provided by Sodium. It is safe to call this function more than once and from different threads -- subsequent calls won't have any effects.
After this function returns, all of the other functions provided by Sodium will be thread-safe.
sodium_init() doesn't perform any memory allocations. However, on Unix systems, it may open /dev/urandom and keep the descriptor open so that the device remains accessible after a chroot() call.
Multiple calls to sodium_init() do not cause additional descriptors to be opened.
sodium_init() returns 0 on success, -1 on failure, and 1 if the library had already been initialized.
Before returning, the function ensures that the system's random number generator has been properly seeded.
sodium_init() stalling on Linux
On some Linux systems, this may take some time, especially when called right after a reboot of the system. This issue has been reported on Digital Ocean virtual machines, Scaleway ARM instances, and AWS Nitro Enclaves.
This can be confirmed with the following command:
1
cat /proc/sys/kernel/random/entropy_avail
Copied!
If the command returns 0 or a very low number (< 160), and you are not running an obsolete kernel, this is very likely to be the case.
In a virtualized environment, make sure that the virtio-rng interface is available. If this is a cloud service and the hypervisor settings are out of your reach, consider switching to a different service.
On a bare-metal host such as Scaleway instances, a possible workaround is to install the rng-tools package:
1
apt-get install rng-tools
Copied!
And check the value of /proc/sys/kernel/random/entropy_avail again. If the value didn't go any higher, install haveged:
1
apt-get install haveged
Copied!
Haveged should only be used as a very last resort. It hasn't received any updates for 10+ years and shouldn't be trusted as a single entropy source, especially on virtualized environments.
​Jitterentropy is a better alternative, but most Linux distributions don't offer it as an installable package yet.
On AWS Nitro Enclaves, workarounds include:
Calling the aws_nitro_enclaves_library_seed_entropy() function before sodium_init(), and occasionally afterwards.
Using the RDSEED CPU instruction to seed the kernel RNG (not recommended as a unique entropy source).
Setting random.trust_cpu=on in the kernel command line (requires Linux kernel > 4.19).
Applications can warn users about the Linux RNG not being seeded before calling sodium_init() using code similar to the following:
1
#if defined(__linux__)
2
# include <fcntl.h>
3
# include <unistd.h>
4
# include <sys/ioctl.h>
5
# include <linux/random.h>
6
#endif
7
// ...
8
#if defined(__linux__) && defined(RNDGETENTCNT)
9
int fd;
10
int c;
11
​
12
if ((fd = open("/dev/random", O_RDONLY)) != -1) {
13
    if (ioctl(fd, RNDGETENTCNT, &c) == 0 && c < 160) {
14
        fputs("This system doesn't provide enough entropy to quickly generate high-quality random numbers.\n"
15
              "Installing the rng-utils/rng-tools, jitterentropy or haveged packages may help.\n"
16
              "On virtualized Linux environments, also consider using virtio-rng.\n"
17
              "The service will not start until enough entropy has been collected.\n", stderr);
18
    }
19
    (void) close(fd);
20
}
21
#endif
Copied!
Congrats, you're all set up!
A good documentation page to read next might be Quickstart and FAQ.
Bindings for other languages
Helpers
Last modified 2mo ago
Copy link
Contents
sodium_init() stalling on Linux