libsodium_crypto_secretbox (libsodium v3.0.1)
View SourceSecret-key authenticated encryption with XSalsa20-Poly1305 (see
primitive/0).
easy/3 returns the macbytes/0 byte authentication tag followed by the
ciphertext, and detached/3 returns them separately. Keys are
keybytes/0 bytes and nonces noncebytes/0 bytes; the nonce is long
enough to be generated at random, but must never be reused with the same
key.
crypto_secretbox/3 and open/3 are the NaCl compatibility interface,
which requires zerobytes/0 leading zero bytes of padding on the
plaintext and produces (and expects) boxzerobytes/0 leading zero bytes
on the ciphertext. New code should use easy/3 and open_easy/3.
Key = libsodium_crypto_secretbox:keygen(),
Nonce = libsodium_randombytes:buf(libsodium_crypto_secretbox:noncebytes()),
Ciphertext = libsodium_crypto_secretbox:easy(<<"message">>, Nonce, Key),
<<"message">> = libsodium_crypto_secretbox:open_easy(Ciphertext, Nonce, Key).Summary
Types
A crypto_secretbox_KEYBYTES (32-byte) binary.
A crypto_secretbox_MACBYTES (16-byte) binary.
A crypto_secretbox_NONCEBYTES (24-byte) binary.
Functions
Return crypto_secretbox_boxzerobytes(), in bytes.
NaCl compatibility interface: encrypt M, which must start with
zerobytes/0 zero bytes, with the nonce N and key K.
Encrypt and authenticate M with the nonce N and key K, returning
the ciphertext and the macbytes/0 byte authentication tag
separately as {C, MAC}, or -1 on failure.
Encrypt and authenticate M with the noncebytes/0 byte nonce N
and the keybytes/0 byte key K.
Return crypto_secretbox_keybytes(), in bytes.
Generate a random keybytes/0 byte key.
Return crypto_secretbox_macbytes(), in bytes.
Return crypto_secretbox_messagebytes_max(), in bytes.
Return crypto_secretbox_noncebytes(), in bytes.
NaCl compatibility interface: verify and decrypt C, which must
start with boxzerobytes/0 zero bytes, with the nonce N and key
K.
Verify the detached tag MAC and decrypt C with the nonce N and
key K. Returns the plaintext, or -1 when verification fails.
Verify and decrypt the ciphertext C produced by easy/3 with the
nonce N and key K. Returns the plaintext, or -1 when
verification fails or C is shorter than macbytes/0.
Return crypto_secretbox_primitive() as an atom.
Return crypto_secretbox_zerobytes(), in bytes.
Types
Functions
-spec boxzerobytes() -> Result when Result :: 16.
Return crypto_secretbox_boxzerobytes(), in bytes.
-spec crypto_secretbox(M, N, K) -> Result when M :: binary(), N :: n(), K :: k(), Result :: binary() | -1.
NaCl compatibility interface: encrypt M, which must start with
zerobytes/0 zero bytes, with the nonce N and key K.
Returns a ciphertext of the same length as M that starts with
boxzerobytes/0 zero bytes, followed by the authentication tag and
the encrypted message, or -1 when M is shorter than
zerobytes/0. Non-zero padding bytes leak the authentication key.
-spec detached(M, N, K) -> Result when M :: binary(), N :: n(), K :: k(), Result :: {binary(), mac()} | -1.
Encrypt and authenticate M with the nonce N and key K, returning
the ciphertext and the macbytes/0 byte authentication tag
separately as {C, MAC}, or -1 on failure.
Encrypt and authenticate M with the noncebytes/0 byte nonce N
and the keybytes/0 byte key K.
Returns the macbytes/0 byte authentication tag followed by the
ciphertext, or -1 on failure.
-spec keybytes() -> Result when Result :: 32.
Return crypto_secretbox_keybytes(), in bytes.
-spec keygen() -> Result when Result :: k().
Generate a random keybytes/0 byte key.
-spec macbytes() -> Result when Result :: 16.
Return crypto_secretbox_macbytes(), in bytes.
-spec messagebytes_max() -> Result when Result :: non_neg_integer().
Return crypto_secretbox_messagebytes_max(), in bytes.
-spec noncebytes() -> Result when Result :: 24.
Return crypto_secretbox_noncebytes(), in bytes.
NaCl compatibility interface: verify and decrypt C, which must
start with boxzerobytes/0 zero bytes, with the nonce N and key
K.
Returns a plaintext of the same length as C that starts with
zerobytes/0 zero bytes, or -1 when verification fails or C is
shorter than zerobytes/0.
-spec open_detached(C, MAC, N, K) -> Result when C :: binary(), MAC :: mac(), N :: n(), K :: k(), Result :: binary() | -1.
Verify the detached tag MAC and decrypt C with the nonce N and
key K. Returns the plaintext, or -1 when verification fails.
Verify and decrypt the ciphertext C produced by easy/3 with the
nonce N and key K. Returns the plaintext, or -1 when
verification fails or C is shorter than macbytes/0.
-spec primitive() -> Result when Result :: xsalsa20poly1305.
Return crypto_secretbox_primitive() as an atom.
-spec zerobytes() -> Result when Result :: 32.
Return crypto_secretbox_zerobytes(), in bytes.