Last updated
Last updated
Sodium is a shared library with a machine-independent set of headers, so it can easily be used by 3rd party projects.
The library is built using Autotools, making it easy to package.
Installation is trivial, and both compilation and testing can take advantage of multiple CPU cores.
Download a , preferably the latest stable version, then follow the ritual:
On aarch64, with some compilers, you may currently have to define -march=armv8-a+crypto+aes:
Since different files are compiled for different CPU classes, and to prevent unwanted optimizations, link-time optimization (LTO) should not be used.
Also, do not enable sanitizers (such as -fsanitize=signed-integer-overflow). These can introduce side channels.
On Linux, if the process hangs at the make check step, your system PRG may not have been properly seeded. Please refer to the notes in the “Usage” section for ways to address this.
Also, on Linux, like any manually installed library, running the ldconfig command is required to make the dynamic linker aware of the new library.
Compilation on Windows is usually not required, as pre-built libraries for MinGW and Visual Studio are available (see below).
Visual Studio solutions can be then found in the builds/msvc directory.
In order to compile with MinGW, run either ./dist-build/msys2-win32.sh or ./dist-build/msys2-win64.sh for Win32 or x64 targets.
They include header files as well as static (.LIB) and shared (.DLL) libraries for all the supported compiler versions.
Projects willing to statically link Sodium must define a macro named SODIUM_STATIC. This will prevent symbol definitions from being referenced with __dllexport.
After unpacking the source distribution (stable is recommended), set ANDROID_NDK_HOME to the path to the Android SDK. Note that compilation is only tested on CI with the LTS version of the SDK.
Then, run the android-aar.sh script:
This will compile libsodium (full builds and minimal builds) for every Android architectures. The resulting libraries are in libsodium-android-<architecture> folders.
In addition, this creates AAR files, that can be directly included in projects using gradle or cmake. After compilation, the script outputs the instructions to do so.
The apple-xcframework.sh scripts crates an xcframework package containing libsodium for iOS, macOS, Catalyst, watchOS, tvOS, visionOS and their respective emulators:
Here is an example of cross-compiling to ARM using the GNU tools for ARM embedded processors:
make check can also build the test apps, but these have to be run on the native platform.
Note: --specs=nosys.specs is only required for the ARM compilation toolchain.
Please note that using libsodium on ARM Cortex M0, M3, and M4 CPUs is untested and not recommended if side-channels are a concern.
Releases can be compiled using the CompCert compiler.
A typical command to compile Sodium on a little-endian system with CompCert is:
Compilation for the current target:
Size-optimized builds:
Cross-compilation:
Code in the stable branch also includes generated files, and does not require the autotools (Libtool, Autoconf, and Automake) to be present.
To check out the stable branch, use:
Tarballs of the stable code are also available for download and recommended if you are compiling libsodium from source.
RWQf6LRCGA9i53mlYecO4IzT51TGPpvWucNSCh1CBM0QTaLn73Y7GFO3
The .minisig file should be present in the same directory as the main file. The typical command to verify a file is:
Or with GnuPG and the following RSA key:
We encourage users and researchers to use PGP encrypted emails to transmit confidential details regarding possible vulnerabilities in the Sodium library.
Details should be sent to j [at] pureftpd [dot] org using the PGP key above.
However, if you want to compile it yourself, start by cloning the from the Git repository.
Alternatively, you can build and install libsodium using dependency manager:
The libsodium port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please on the vcpkg repository.
with stable additions (see below) are available, as well as pre-built libraries for MinGW32 and MinGW64. Note that pre-built libraries are built with the run-time Multi-threaded (/MT) and not with Multi-threaded DLL (/MD).
can be used to compile or cross-compile to any supported target:
We recommend using distribution tarballs over cloning the , especially since tarballs do not require dependencies, such as Libtool and Autotools.
However, if cloning a Git repository happens to be more convenient, the branch always contains the latest stable release of libsodium, plus minor patches that will be part of the next version and critical security fixes while new packages including them are being prepared.
See the and sections to get started!
Distribution files can be verified with using the following Ed25519 key: