libsodium: a NaCl fork for encryption, signatures and password hashing

What libsodium is for, and who it is aimed at

The README describes Sodium as "an easy-to-use software library that provides a wide range of cryptographic operations including encryption, decryption, digital signatures, and secure password hashing." That sentence is the whole pitch. The project is a fork of NaCl, and the README says it maintains API compatibility while extending functionality "to improve usability and simplify the development of secure applications."

The intended audience is application developers who need to encrypt a payload, sign a message, or hash a password, and who do not want to assemble those operations from lower-level primitives themselves. The supported surface is broad: the README lists Windows through MinGW and Visual Studio on x86, x64 and arm64, plus iOS, Android, JavaScript and WebAssembly. A C library that reaches JavaScript and WebAssembly through the same conceptual API is unusual, and it is the main reason libsodium appears in so many language bindings. The related searches around libsodium for PHP, Python, Rust, C++ and npm reflect that: most people meet the library through a binding, not through the C headers.

What it is not: a protocol implementation. There is no TLS server in the README, no certificate handling, no command-line tool. If you need those, this is the wrong layer.

How libsodium works: a NaCl-compatible core with a two-tier release process

The repository is a C project built around autotools. The top level contains configure.ac, Makefile.am, autogen.sh and m4/, which is the standard GNU build system layout. Alongside that there is build.zig and a zig-package topic, so a Zig build path exists as well. The src/ directory holds the implementation and test/ holds the test suite. Packaging metadata lives in libsodium.pc.in and libsodium-uninstalled.pc.in, which means downstream projects can discover the library through pkg-config, including an uninstalled variant for building against a source tree.

The versioning scheme matters more than the directory listing. The README describes a two-tier system. Point releases such as 1.0.19, 1.0.20 and 1.0.21 are tagged "when new features are added or significant changes are made." Stable releases are "frequent maintainance updates between point releases" that fix minor issues and stay fully compatible with their parent point release. The README states plainly: "No new features, no breaking changes." For anyone pinning a dependency, that is the useful part. If your application depends on a specific point release, the README says stable updates are safe to apply. Security fixes go to the stable branch immediately, with a new point release tagged shortly after.

That is an explicit compatibility contract, and it is rarer than it should be in C libraries.

Installing libsodium and making a first call

The README does not carry install instructions inline. It links to an installation page at doc.libsodium.org/installation, a quickstart at doc.libsodium.org/quickstart, and a releases directory at download.libsodium.org/libsodium/releases/. The README also links to an integrity-checking section on the installation page, which is worth reading before you trust a downloaded archive. Because the README gives no package-manager commands, none are reproduced here; check the installation page for the platform you target.

Once the library is present, the repository ships pkg-config metadata in libsodium.pc.in and libsodium-uninstalled.pc.in, so the library is meant to be discovered through pkg-config. The installation page is the place to confirm the exact invocation for your platform, including the uninstalled case, since the README does not spell it out.

After linking, the quickstart page is where the first real call belongs, because the README does not reproduce function signatures. The pattern to expect from a NaCl-compatible library is a small set of named operations rather than a generic cipher interface, and the quickstart is the authoritative source for which one to call first.

For a first real use, pick the operation you actually need rather than the most general one. If you are storing passwords, that is password hashing. If you are moving a payload between two parties who already share a key, that is symmetric encryption. The quickstart maps those intentions onto functions.

Where libsodium is the wrong tool

The clearest boundary is protocol work. If you need to terminate TLS, manage certificates, or speak an existing wire protocol, libsodium gives you primitives and constructions, not those protocols. You would be building the protocol layer yourself, and that is exactly the kind of work a crypto library is supposed to remove.

A second boundary is key management and storage. Nothing in the README describes where keys live, how they are rotated, or how they are protected at rest. The library performs operations on keys you supply. If your threat model includes an attacker with filesystem access, libsodium does not answer that question, and no amount of correct primitive selection will.

The third boundary is the release process itself. Stable releases are described as maintenance updates that add no features. That is good for stability and bad if you are waiting for a capability that only lands in a point release. You cannot get a new feature by tracking stable; you have to move to the next point release and accept whatever else it contains. The README also notes that security fixes reach the stable branch immediately but a new point release is tagged "shortly after," so there is a window where the fix is on a branch rather than in a tagged release. If your process only consumes tags, know that window exists.

Finally, the licence field on the repository is reported as NOASSERTION, while the README states the project is distributed under the ISC license. Those two signals disagree, and that is a thing to resolve with your own legal review rather than assume.

libsodium compared with OpenSSL and Crypto++

The most common comparison people search for is libsodium versus OpenSSL, and the difference is one of scope rather than quality. OpenSSL is a protocol and toolkit project: TLS, X.509 certificates, a command-line interface, and a very large surface of algorithm implementations. libsodium is a library of cryptographic operations with a deliberately small API. The README's own framing, an "easy-to-use software library" that is a fork of NaCl with API compatibility, describes a project that chose to expose fewer knobs.

That choice has consequences in both directions. A smaller API means fewer ways to misuse a primitive, and it means fewer escape hatches when you need an algorithm the library does not expose. With OpenSSL, the reverse holds: almost anything is reachable, and the cost is a much larger configuration and API surface to get right.

Crypto++ is the other comparison that comes up. It is a C++ library, so the fit depends on your language and build system before any cryptographic question is asked. libsodium is C with bindings into other languages, and its packaging story through pkg-config and the .pc files in this repository is aimed at C and C-ABI consumers. If you are writing C++, both are reachable, but the integration work is different.

The honest summary is that these are not interchangeable. libsodium is the smaller commitment, and it is smaller because it does less.

Maintenance, upgrade cost and licence considerations

The repository is not archived, and the last push was on 2026-09-20. The most recent release listed is 1.0.22, tagged 2026-04-09, following 1.0.21 on 2026-01-06 and 1.0.20 on 2024-05-25. The gap between 1.0.20 and 1.0.21 is roughly nineteen months; the gap between 1.0.21 and 1.0.22 is about three months. Release cadence has not been uniform, which is worth knowing if your upgrade planning assumes a steady tick.

The upgrade cost is low by design. The README states that stable releases between point releases contain no new features and no breaking changes, and that stable updates are safe to apply if you depend on a specific point release. So the routine path is: track stable, apply updates, and move point releases deliberately. The non-routine path is a point release jump, where the README says new features or significant changes are the trigger, so that is where you read the ChangeLog. The repository includes a ChangeLog file at the top level for exactly that.

On licensing, the README says the project is distributed under the ISC license, which is a short permissive licence. The repository metadata reports NOASSERTION instead, which usually means an automated licence detector could not classify the files. This is not legal advice, and the discrepancy is the kind of thing to put in front of whoever handles licensing at your organization before you ship, rather than resolve by picking whichever of the two statements is more convenient.

Editorial conclusion

Adopt libsodium when you want a small cryptographic API with documented primitives and you are prepared to treat the library as a dependency rather than an in-house crypto project. Do not adopt it if you need a TLS stack, a certificate authority, or a drop-in replacement for OpenSSL's command line and protocol surface: libsodium is not that. Before shipping, check the installation page for your platform, verify the release archive against the integrity-checking instructions, and read the versioning note so you know whether a stable update can be applied without changing your pinned point release.

Frequently asked questions

Official sources

1. Issues
2. jedisct1/libsodium on GitHub
3. Project website
4. README
5. Releases