libsodium (libsodium v3.0.1)

libsodium bindings for Erlang and Elixir.

Each libsodium namespace is exposed by its own module, named after the C prefix: crypto_box_easy() is libsodium_crypto_box:easy/4. Functions accept and return binaries and integers, raise badarg for invalid argument types or lengths, and return libsodium's integer status (usually -1) when an operation such as decryption or verification fails.

Streaming and precomputed APIs use opaque native states (each module's state() type). Operations return new states and never modify their arguments, so a state can be reused or shared between processes, but it cannot be serialized or used with another module's functions.

All modules call libsodium_nif directly; starting the application is not required. Long-running operations move to dirty schedulers and streaming updates yield, so calls never block a normal scheduler for long.

Secret-key cryptography

Module	Description
`libsodium_crypto_aead_aegis128l`	AEGIS-128L
`libsodium_crypto_aead_aegis256`	AEGIS-256
`libsodium_crypto_aead_aes256gcm`	AES256-GCM
`libsodium_crypto_aead_chacha20poly1305`	ChaCha20-Poly1305
`libsodium_crypto_aead_xchacha20poly1305`	XChaCha20-Poly1305
`libsodium_crypto_auth`	Secret-key authentication
`libsodium_crypto_auth_hmacsha256`	HMAC-SHA-256
`libsodium_crypto_auth_hmacsha512`	HMAC-SHA-512
`libsodium_crypto_auth_hmacsha512256`	HMAC-SHA-512-256
`libsodium_crypto_ipcrypt`	IP address encryption
`libsodium_crypto_secretbox`	Secret-key authenticated encryption
`libsodium_crypto_secretbox_xchacha20poly1305`	XChaCha20-Poly1305 secret box
`libsodium_crypto_secretbox_xsalsa20poly1305`	XSalsa20-Poly1305 secret box
`libsodium_crypto_secretstream_xchacha20poly1305`	Encrypted streams

Public-key cryptography

Module	Description
`libsodium_crypto_box`	Public-key authenticated encryption
`libsodium_crypto_box_curve25519xchacha20poly1305`	X25519-XChaCha20-Poly1305 box
`libsodium_crypto_box_curve25519xsalsa20poly1305`	X25519-XSalsa20-Poly1305 box
`libsodium_crypto_kem`	Key encapsulation
`libsodium_crypto_kem_mlkem768`	ML-KEM-768 key encapsulation
`libsodium_crypto_kem_xwing`	X-Wing key encapsulation
`libsodium_crypto_kx`	Key exchange
`libsodium_crypto_sign`	Public-key signatures
`libsodium_crypto_sign_ed25519`	Ed25519 signatures
`libsodium_crypto_sign_ed25519ph`	Ed25519ph signatures

Hashing

Module	Description
`libsodium_crypto_generichash`	Generic hashing
`libsodium_crypto_generichash_blake2b`	BLAKE2b
`libsodium_crypto_hash`	Hashing (SHA-512)
`libsodium_crypto_hash_sha256`	SHA-256
`libsodium_crypto_hash_sha3256`	SHA3-256
`libsodium_crypto_hash_sha3512`	SHA3-512
`libsodium_crypto_hash_sha512`	SHA-512
`libsodium_crypto_shorthash`	Short-input hashing
`libsodium_crypto_shorthash_siphash24`	SipHash-2-4
`libsodium_crypto_shorthash_siphashx24`	SipHash-2-4 (128-bit)
`libsodium_crypto_xof_shake128`	SHAKE128 extendable-output function
`libsodium_crypto_xof_shake256`	SHAKE256 extendable-output function
`libsodium_crypto_xof_turboshake128`	TurboSHAKE128 extendable-output function
`libsodium_crypto_xof_turboshake256`	TurboSHAKE256 extendable-output function

Password hashing

Module	Description
`libsodium_crypto_pwhash`	Password hashing
`libsodium_crypto_pwhash_argon2i`	Argon2i password hashing
`libsodium_crypto_pwhash_argon2id`	Argon2id password hashing
`libsodium_crypto_pwhash_scryptsalsa208sha256`	Scrypt password hashing

Key derivation

Module	Description
`libsodium_crypto_kdf`	Key derivation
`libsodium_crypto_kdf_blake2b`	BLAKE2b key derivation
`libsodium_crypto_kdf_hkdf_sha256`	HKDF-SHA-256
`libsodium_crypto_kdf_hkdf_sha512`	HKDF-SHA-512

Advanced

Module	Description
`libsodium_crypto_core_ed25519`	Edwards25519 arithmetic
`libsodium_crypto_core_hchacha20`	HChaCha20 core
`libsodium_crypto_core_hsalsa20`	HSalsa20 core
`libsodium_crypto_core_keccak1600`	Keccak-f[1600] permutation
`libsodium_crypto_core_ristretto255`	Ristretto255 arithmetic
`libsodium_crypto_core_salsa20`	Salsa20 core
`libsodium_crypto_core_salsa2012`	Salsa20/12 core
`libsodium_crypto_onetimeauth`	One-time authentication
`libsodium_crypto_onetimeauth_poly1305`	Poly1305
`libsodium_crypto_scalarmult`	Point multiplication
`libsodium_crypto_scalarmult_curve25519`	X25519 point multiplication
`libsodium_crypto_scalarmult_ed25519`	Ed25519 point multiplication
`libsodium_crypto_scalarmult_ristretto255`	Ristretto255 point multiplication
`libsodium_crypto_stream`	Stream cipher
`libsodium_crypto_stream_chacha20`	ChaCha20 stream cipher
`libsodium_crypto_stream_salsa20`	Salsa20 stream cipher
`libsodium_crypto_stream_salsa2012`	Salsa20/12 stream cipher
`libsodium_crypto_stream_xchacha20`	XChaCha20 stream cipher
`libsodium_crypto_stream_xsalsa20`	XSalsa20 stream cipher
`libsodium_crypto_verify_16`	16-byte comparison
`libsodium_crypto_verify_32`	32-byte comparison
`libsodium_crypto_verify_64`	64-byte comparison

Helpers

Module	Description
`libsodium_randombytes`	Random data
`libsodium_runtime`	CPU features
`libsodium_utils`	Helpers
`libsodium_version`	Library version

Summary

Application API

start()

Start the libsodium application and its dependencies.

Deprecated API

call(Namespace, Function) deprecated

Equivalent to call(Namespace, Function, {}).

call(Namespace, Function, Arguments) deprecated

Call the native function for Namespace and Function with the elements of Arguments, as the port driver did. For example, call(crypto_box, keypair, {}) calls libsodium_nif:crypto_box_keypair/0.

Application API

start()

-spec start() -> Result when Result :: {ok, [atom()]} | {error, term()}.

Start the libsodium application and its dependencies.

The native library loads on first use, so this is optional.

{ok, _Started} = libsodium:start().

Deprecated API

call(Namespace, Function)

This function is deprecated. libsodium:call/2 is deprecated; call the namespace module, such as libsodium_crypto_box, instead.

-spec call(Namespace, Function) -> Result
              when Namespace :: atom(), Function :: atom(), Result :: dynamic().

Equivalent to call(Namespace, Function, {}).

call(Namespace, Function, Arguments)

This function is deprecated. libsodium:call/3 is deprecated; call the namespace module, such as libsodium_crypto_box, instead.

-spec call(Namespace, Function, Arguments) -> Result
              when Namespace :: atom(), Function :: atom(), Arguments :: tuple(), Result :: dynamic().

Unknown functions raise undef.