sodium.hheader. Including individual headers is neither required nor recommended.
sodium_init()function must then be called before any other function. It is safe to call
sodium_init()multiple times, or from different threads; it will immediately return
1without doing anything if the library had already been initialized.
crypto_pwhash()function first. This computes a secret key from a password, using an intentionally CPU-intensive and memory-hard function (to slow down brute-force attacks).
*_keygen()function should always be prefered.
DllMain()function (Windows), or
__attribute__((constructor))(gcc, clang, icc on MacOS and ELF-based systems) to call
randombytes_buf(nonce, sizeof nonce)
crypto_secretbox_easy()to encrypt the message, and send/store the resulting ciphertext along with the nonce. Unlike the key, the nonce doesn't have to be secret.
crypto_secretbox_open_easy()to decrypt the ciphertext using the same key and nonce.
Bsecurely communicate without a pre-shared secret key?
crypto_kx_keypair()to create their own key pair. Secret keys have to remain secret, but
Acan send its public key to
Bor even make it available to everyone. The same applies to
B's public key.
B's public key and its key pair to create a set of shared keys to communicate with
A's public key and its key pair to create a set of shared keys to communicate with
Bwill be identical. There are two of them. One can be used to encrypt and decrypt message in one direction (from
B) and the other one to encrypt and decrypt messages in the other direction (from
Aencrypts a message for
Busing a shared secret key using
crypto_aead(), an authentication tag is also computed, and should be sent to
Balong with the encrypted payload.
Bcan create such a tag.
crypto_kx), a valid tag for a message can only be created by the sender.
crypto_kx_seed_keypair()can derive specialized key pairs from the same 32 byte seed.
crypto_scalarmult_ed25519_base()functions for scalar multiplicaton over edwards25519.
(encryption_key || message)first, then encrypt
(recipient_id || signature || message).
(sender_id || message), then sign the ciphertext.
(H(sender_id || message) || message)(if using AES-GCM or Salsa/ChaCha-Poly1305), then sign the ciphertext.
recipient_idis public data that uniquely identifies a party.
crypto_stream()barely documented and not even present in some bindings?
crypto_stream()API generates a deterministic sequence of bytes from a seed, and optionally applies the XOR operation between that sequence and some input sequence.
crypto_secretstreammust generally be used over
crypto_stream, as they will add and verify an authentication tag to detect data that has been corrupted or tampered with.
crypto_stream()is only useful as a building block to design custom constructions. As-is, it is completely insecure.
(key, nonce)tuple for every message.
crypto_generichashand with the
crypto_secretstreamAPIs. These are the trickiest to implement bindings for, and will provide good insights about how to design your bindings.