Overview

libsodium is a modern, easy-to-use cryptography library based on NaCl. It provides authenticated encryption, public-key cryptography, digital signatures, key exchange, and hashing — all with safe defaults. No algorithm selection required: libsodium chooses the best algorithm for each operation.

Symmetric Encryption (SecretBox)

uses libsodium;

{ generate a secret key — store it securely! }
var key   := SecretBoxKeyGen();   { 32 random bytes }
var nonce := SecretBoxNonce();    { 24 random bytes — generate fresh per message }

{ encrypt }
var cipher := SecretBoxEncrypt('Hello, secret world!', nonce, key);

{ decrypt }
var plain := SecretBoxDecrypt(cipher, nonce, key);
WriteLn(plain);   { Hello, secret world! }

{ store nonce + cipher together (nonce is not secret) }
var stored := nonce + cipher;

Asymmetric Encryption (Box)

uses libsodium;

{ each party generates a keypair }
var alice := BoxKeyGen();
var bob   := BoxKeyGen();

{ alice encrypts for bob }
var nonce  := BoxNonce();
var cipher := BoxEncrypt('Hi Bob!', nonce, bob.PublicKey, alice.SecretKey);

{ bob decrypts }
var plain := BoxDecrypt(cipher, nonce, alice.PublicKey, bob.SecretKey);
WriteLn(plain);   { Hi Bob! }

{ anonymous sender (sealed box) — bob only needs his keypair }
var sealed := SealedBoxEncrypt('secret message', bob.PublicKey);
var msg    := SealedBoxDecrypt(sealed, bob.PublicKey, bob.SecretKey);

Digital Signatures (Ed25519)

uses libsodium;

{ generate signing keypair }
var keys := SignKeyGen();

{ sign a message }
var signed    := Sign('{"amount":100,"to":"bob"}', keys.SecretKey);
var detached  := SignDetached('{"amount":100}', keys.SecretKey);

{ verify (raises on failure) }
var message := SignOpen(signed, keys.PublicKey);
WriteLn(message);

{ verify detached signature }
if SignVerify('{"amount":100}', detached, keys.PublicKey) then
  WriteLn('Signature valid')
else
  WriteLn('INVALID!');

Key Exchange (X25519)

uses libsodium;

{ client and server each generate a keypair }
var client := KXKeyGen();
var server := KXKeyGen();

{ both sides derive the same session keys independently }
var clientKeys := KXClientSession(client.PublicKey, client.SecretKey, server.PublicKey);
var serverKeys := KXServerSession(server.PublicKey, server.SecretKey, client.PublicKey);

{ clientKeys.Tx = serverKeys.Rx  (client sends → server receives) }
{ clientKeys.Rx = serverKeys.Tx  (server sends → client receives) }

Hashing & HMAC

uses libsodium;

{ BLAKE2b — fast, secure, preferred }
var hash := GenericHash('data to hash', 32);
WriteLn(ToHex(hash));

{ keyed BLAKE2b — message authentication }
var key  := RandomBytes(32);
var mac  := GenericHashKeyed('message', key, 32);

{ SHA-256 / SHA-512 }
var h256 := SHA256('hello');
var h512 := SHA512('hello');

{ HMAC }
var hmac := HMAC256('message', 'secret-key');
if HMACVerify(hmac, expectedMac) then
  WriteLn('authentic');

Password Hashing & Random

uses libsodium;

{ hash a password for storage }
var hash := PwHash('my-password', PwHashOpsInteractive(), PwHashMemInteractive());
{ stores: $argon2id$v=19$... }

{ verify at login }
if PwHashVerify(hash, 'my-password') then
  WriteLn('correct password');

{ derive encryption key from password }
var salt := RandomBytes(16);
var key  := PwHashKey('password', salt, 32,
              PwHashOpsSensitive(), PwHashMemSensitive());

{ safe random bytes }
var token := ToBase64(RandomBytes(32), Base64UrlSafe());
WriteLn(token);   { random URL-safe token }