libsodium: A Misuse-Resistant Crypto Library

libsodium was created by Frank Denis as a portable, cross-platform build of the NaCl (Networking and Cryptography library) library developed by Daniel Bernstein, Tanja Lange, and Peter Schwabe. The core philosophy is making correct cryptographic usage as easy as possible and incorrect usage as hard as possible. Secure defaults, simple APIs, and opinionated algorithm choices prevent the common mistakes that plague lower-level libraries.

crypto_secretbox provides secret-key authenticated encryption using XSalsa20-Poly1305. The API takes a message, a 24-byte nonce (randomly generated), and a 32-byte key. The output is a ciphertext that is both encrypted and authenticated. crypto_secretbox_open decrypts and verifies the authentication tag atomically, returning an error if tampering is detected. This prevents decryption of corrupted or maliciously modified ciphertexts.

crypto_box provides public-key authenticated encryption between two parties using X25519-XSalsa20-Poly1305. Given a sender's private key and recipient's public key, it encrypts and authenticates the message so only the intended recipient can decrypt it, and the recipient can verify the sender's identity. crypto_box_seal is the anonymous variant: the sender is hidden, and only encryption (not sender authentication) is provided.

crypto_sign implements digital signatures using Ed25519. Key generation produces a 64-byte private key (actually a seed concatenated with the public key) and a 32-byte public key. Signing produces a 64-byte signature. Verification is fast and constant-time. Ed25519 signatures are deterministic (same message and key always produce the same signature), eliminating the randomness-failure vulnerabilities that affected ECDSA in some implementations.

crypto_generichash provides general-purpose hashing using BLAKE2b. Unlike SHA-256, BLAKE2b does not require a separate HMAC construction for keyed hashing; it accepts an optional key directly. Output length is configurable from 16 to 64 bytes. BLAKE2b is faster than SHA-256 and SHA-512 on modern 64-bit processors while providing equivalent or better security properties.

crypto_kdf provides key derivation from a master key using BLAKE2b. Given a 32-byte master key, a context string (8 bytes identifying the purpose), and a subkey ID (64-bit number), it derives a cryptographically independent subkey of configurable length. This allows deriving multiple independent keys from a single master key for different purposes without any correlation between derived keys.

crypto_pwhash provides password hashing using Argon2id, the winner of the Password Hashing Competition. Argon2id combines memory-hard computation (resisting GPU attacks) with time-hard computation (resisting ASIC attacks). Parameters include operations limit (time cost) and memory limit, which can be tuned to the security requirements. crypto_pwhash_str produces a standard string suitable for storage that includes the algorithm and parameters.

crypto_box_seal encrypts a message to a recipient without revealing the sender. It generates a temporary ephemeral key pair, performs a key exchange with the recipient's public key, and then discards the ephemeral private key. The recipient can decrypt using their private key but cannot identify the sender. This is suitable for anonymous submission systems and one-way encrypted channels.

libsodium has bindings in virtually every major programming language. PyNaCl provides idiomatic Python bindings with Pythonic exceptions and bytes objects. libsodium-wrappers provides JavaScript/Node.js bindings (WASM for browsers). libsodium.js is a pure JavaScript port. Binding quality varies: prefer official or widely-maintained bindings that wrap the C library rather than reimplementing the algorithms.

OpenSSL's low-level API requires explicit decisions about algorithms, key sizes, modes, padding, and IV management. Incorrect combinations are silently accepted. libsodium provides a single correct implementation per use case with no configuration required. For example, encrypting with OpenSSL requires choosing cipher, mode, key derivation, IV generation, and padding; with libsodium's crypto_secretbox, you provide a key, nonce, and message, and the rest is handled correctly.

libsodium is the recommended starting point for any project requiring cryptographic operations in supported languages. Its small API surface reduces the chance of misuse, its algorithms are modern and well-analyzed, and its cross-platform C implementation is thoroughly tested. Switching to a lower-level library like OpenSSL should only be necessary when you need specific algorithms not available in libsodium or require FIPS 140-2 validation.

Which libsodium function should you use to hash a password for storage in a database?

libsodium recap: secure defaults and hard-to-misuse API, built on NaCl primitives by Bernstein et al., crypto_secretbox for secret-key encryption (XSalsa20-Poly1305), crypto_box for public-key encryption (X25519), crypto_sign for Ed25519 signatures, crypto_generichash for BLAKE2b hashing, crypto_pwhash for Argon2id password hashing, sealed boxes for anonymous encryption, and language bindings for most major platforms.