libsodium_crypto_stream_chacha20 (libsodium v3.0.1)
View SourceThe ChaCha20 stream cipher, in both its original form (64-bit nonce and
64-bit block counter) and the IETF variant from RFC 8439 (ietf_*
functions: 96-bit nonce and 32-bit block counter, limiting a single
message to 256 GiB).
crypto_stream_chacha20/3 and ietf/3 return raw keystream; 'xor'/3
and ietf_xor/3 encrypt or decrypt by combining a message with it, and the
_ic variants start at a given 64-byte block counter.
This is not authenticated encryption: ciphertexts can be modified without
detection, so pair it with a MAC or use libsodium_crypto_aead_chacha20poly1305
instead. A nonce must never be reused with the same key; the short nonces
here are too small to choose at random safely for many messages, which
libsodium_crypto_stream_xchacha20 avoids.
K = libsodium_crypto_stream_chacha20:keygen(),
N = libsodium_randombytes:buf(libsodium_crypto_stream_chacha20:noncebytes()),
C = libsodium_crypto_stream_chacha20:'xor'(<<"message">>, N, K),
<<"message">> = libsodium_crypto_stream_chacha20:'xor'(C, N, K).Summary
Types
A crypto_stream_chacha20_ietf_NONCEBYTES (12-byte) binary.
A crypto_stream_chacha20_KEYBYTES (32-byte) binary.
A crypto_stream_chacha20_NONCEBYTES (8-byte) binary.
Functions
Return CLen bytes of keystream for the noncebytes/0 byte nonce N and the keybytes/0 byte key K.
Return CLen bytes of IETF ChaCha20 keystream for the
ietf_noncebytes/0 byte nonce N and the ietf_keybytes/0 byte key
K. CLen must not exceed ietf_messagebytes_max/0.
Return crypto_stream_chacha20_ietf_keybytes(), in bytes.
Generate a random ietf_keybytes/0 byte key.
Return crypto_stream_chacha20_ietf_messagebytes_max(), in bytes.
Return crypto_stream_chacha20_ietf_noncebytes(), in bytes.
Encrypt or decrypt M with IETF ChaCha20 using the nonce N and key
K, starting at block counter 0.
Like ietf_xor/3, but start at the 32-bit block counter IC. Raises
badarg when the message would overflow the block counter.
Return crypto_stream_chacha20_keybytes(), in bytes.
Generate a random keybytes/0 byte key.
Return crypto_stream_chacha20_messagebytes_max(), in bytes.
Return crypto_stream_chacha20_noncebytes(), in bytes.
Encrypt or decrypt M by combining it with the keystream for the nonce
N and key K, starting at block counter 0.
Like 'xor'/3, but start at the 64-byte block counter IC, so the
message is combined with the keystream from byte IC * 64 onwards.
Types
Functions
-spec crypto_stream_chacha20(CLen, N, K) -> Result when CLen :: non_neg_integer(), N :: n(), K :: k(), Result :: binary().
Return CLen bytes of keystream for the noncebytes/0 byte nonce N and the keybytes/0 byte key K.
-spec ietf(CLen, N, K) -> Result when CLen :: non_neg_integer(), N :: ietf_n(), K :: k(), Result :: binary().
Return CLen bytes of IETF ChaCha20 keystream for the
ietf_noncebytes/0 byte nonce N and the ietf_keybytes/0 byte key
K. CLen must not exceed ietf_messagebytes_max/0.
-spec ietf_keybytes() -> Result when Result :: 32.
Return crypto_stream_chacha20_ietf_keybytes(), in bytes.
-spec ietf_keygen() -> Result when Result :: k().
Generate a random ietf_keybytes/0 byte key.
-spec ietf_messagebytes_max() -> Result when Result :: non_neg_integer().
Return crypto_stream_chacha20_ietf_messagebytes_max(), in bytes.
-spec ietf_noncebytes() -> Result when Result :: 12.
Return crypto_stream_chacha20_ietf_noncebytes(), in bytes.
Encrypt or decrypt M with IETF ChaCha20 using the nonce N and key
K, starting at block counter 0.
-spec ietf_xor_ic(M, N, IC, K) -> Result when M :: binary(), N :: ietf_n(), IC :: 0..4294967295, K :: k(), Result :: binary().
Like ietf_xor/3, but start at the 32-bit block counter IC. Raises
badarg when the message would overflow the block counter.
-spec keybytes() -> Result when Result :: 32.
Return crypto_stream_chacha20_keybytes(), in bytes.
-spec keygen() -> Result when Result :: k().
Generate a random keybytes/0 byte key.
-spec messagebytes_max() -> Result when Result :: non_neg_integer().
Return crypto_stream_chacha20_messagebytes_max(), in bytes.
-spec noncebytes() -> Result when Result :: 8.
Return crypto_stream_chacha20_noncebytes(), in bytes.
Encrypt or decrypt M by combining it with the keystream for the nonce
N and key K, starting at block counter 0.
-spec xor_ic(M, N, IC, K) -> Result when M :: binary(), N :: n(), IC :: non_neg_integer(), K :: k(), Result :: binary().
Like 'xor'/3, but start at the 64-byte block counter IC, so the
message is combined with the keystream from byte IC * 64 onwards.