sodium.hheader. Including individual headers is neither required nor recommended.
sodium_init()function must 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 has 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 preferred.
DllMain()function (Windows) or
__attribute__((constructor))(GCC, Clang, icc on macOS and ELF-based systems) to call
0on success and
-1to indicate an error.
warn_unused_resultattribute and will cause a compiler warning if ignored. Such warnings must not be ignored.
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 must remain secret, but
Acan send their public key to
Bor make it available to everyone. The same applies to
B's public key and their own key pair to create a set of shared keys to communicate with
A's public key and their own key pair to create a set of shared keys to communicate with
Bwill be identical. There are two of them, so one can be used to encrypt and decrypt messages in one direction (from
B), and the other can be used 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 multiplication 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 Salsa20/ChaCha20-Poly1305) then sign the ciphertext.
recipient_idare 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_secretstreamshould be used over
crypto_streamas 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_secretstreamAPIs. These are the trickiest to implement bindings for and will provide good insights about how to design your bindings.