libsodium_crypto_secretstream_xchacha20poly1305 (libsodium v3.0.1)

Authenticated encryption of a sequence of messages with XChaCha20-Poly1305, detecting truncation, reordering, and duplication.

The sender calls init_push/1 with a keybytes/0 byte key to obtain an opaque state/0 and a headerbytes/0 byte header to transmit, then push/4 for each message. The receiver calls init_pull/2 with the header and key and then pull/3 for each ciphertext. Every call returns a new state and leaves its argument unchanged; reusing an old state re-encrypts with the same nonce and must be avoided.

Each message carries a tag: tag_message/0, tag_push/0 (end of a logical chunk), tag_rekey/0 (derive a new key), or tag_final/0 (end of the stream). Ciphertexts are abytes/0 bytes longer than their messages.

Key = libsodium_crypto_secretstream_xchacha20poly1305:keygen(),
{Push0, Header} = libsodium_crypto_secretstream_xchacha20poly1305:init_push(Key),
{Push1, C1} = libsodium_crypto_secretstream_xchacha20poly1305:push(Push0, <<"hello">>, <<>>, libsodium_crypto_secretstream_xchacha20poly1305:tag_message()),
{_, C2} = libsodium_crypto_secretstream_xchacha20poly1305:push(Push1, <<"world">>, <<>>, libsodium_crypto_secretstream_xchacha20poly1305:tag_final()),
Pull0 = libsodium_crypto_secretstream_xchacha20poly1305:init_pull(Header, Key),
{Pull1, <<"hello">>, 0} = libsodium_crypto_secretstream_xchacha20poly1305:pull(Pull0, C1, <<>>),
{_, <<"world">>, 3} = libsodium_crypto_secretstream_xchacha20poly1305:pull(Pull1, C2, <<>>).

Summary

Types

header()

A crypto_secretstream_xchacha20poly1305_HEADERBYTES (24-byte) binary.

k()

A crypto_secretstream_xchacha20poly1305_KEYBYTES (32-byte) binary.

state()

An opaque native crypto_secretstream_xchacha20poly1305_state.

Functions

abytes()

Return crypto_secretstream_xchacha20poly1305_abytes(), in bytes.

headerbytes()

Return crypto_secretstream_xchacha20poly1305_headerbytes(), in bytes.

init_pull(Header, K)

Start decrypting a stream from the headerbytes/0 byte Header produced by init_push/1 and the key K.

init_push(K)

Start an encrypted stream with the keybytes/0 byte key K.

keybytes()

Return crypto_secretstream_xchacha20poly1305_keybytes(), in bytes.

keygen()

Generate a random keybytes/0 byte key.

messagebytes_max()

Return crypto_secretstream_xchacha20poly1305_messagebytes_max(), in bytes.

pull(State, C, AD)

Verify and decrypt the next ciphertext C (at least abytes/0 bytes) with the additional data AD using the stream State.

push(State, M, AD, Tag)

Encrypt M with the additional data AD (may be empty) and the tag Tag (an integer from 0 to 255, normally one of the tag_* constants) using the stream State.

rekey(State)

Explicitly derive a new key for the stream State and return the updated state. The receiver must call rekey/1 at the same point in the stream.

statebytes()

Return crypto_secretstream_xchacha20poly1305_statebytes(), in bytes.

tag_final()

Return crypto_secretstream_xchacha20poly1305_tag_final().

tag_message()

Return crypto_secretstream_xchacha20poly1305_tag_message().

tag_push()

Return crypto_secretstream_xchacha20poly1305_tag_push().

tag_rekey()

Return crypto_secretstream_xchacha20poly1305_tag_rekey().

Types

k()

-type k() :: <<_:256>>.

A crypto_secretstream_xchacha20poly1305_KEYBYTES (32-byte) binary.

state()

-type state() :: libsodium_nif:crypto_secretstream_xchacha20poly1305_state().

An opaque native crypto_secretstream_xchacha20poly1305_state.

Operations never modify a state: each returns a new one, so earlier states remain valid and can be reused or shared between processes. States cannot be serialized; they exist only within the running VM.

Functions

abytes()

-spec abytes() -> Result when Result :: 17.

Return crypto_secretstream_xchacha20poly1305_abytes(), in bytes.

headerbytes()

-spec headerbytes() -> Result when Result :: 24.

Return crypto_secretstream_xchacha20poly1305_headerbytes(), in bytes.

init_pull(Header, K)

-spec init_pull(Header, K) -> Result when Header :: header(), K :: k(), Result :: state() | -1.

Start decrypting a stream from the headerbytes/0 byte Header produced by init_push/1 and the key K.

Returns the stream state, or -1 on failure.

init_push(K)

-spec init_push(K) -> Result when K :: k(), Result :: {state(), header()} | -1.

Start an encrypted stream with the keybytes/0 byte key K.

Returns {State, Header}, where Header must be sent to the receiver for init_pull/2, or -1 on failure.

keybytes()

-spec keybytes() -> Result when Result :: 32.

Return crypto_secretstream_xchacha20poly1305_keybytes(), in bytes.

keygen()

-spec keygen() -> Result when Result :: k().

Generate a random keybytes/0 byte key.

messagebytes_max()

-spec messagebytes_max() -> Result when Result :: non_neg_integer().

Return crypto_secretstream_xchacha20poly1305_messagebytes_max(), in bytes.

pull(State, C, AD)

-spec pull(State, C, AD) -> Result
              when
                  State :: state(),
                  C :: binary(),
                  AD :: binary(),
                  Result :: {binary(), binary(), 0..255} | -1.

Verify and decrypt the next ciphertext C (at least abytes/0 bytes) with the additional data AD using the stream State.

Returns {NewState, M, Tag}, or -1 when C is invalid, out of order, or tampered with. A tag_final/0 tag marks the end of the stream.

push(State, M, AD, Tag)

-spec push(State, M, AD, Tag) -> Result
              when
                  State :: state(),
                  M :: binary(),
                  AD :: binary(),
                  Tag :: 0..255,
                  Result :: {state(), binary()} | -1.

Encrypt M with the additional data AD (may be empty) and the tag Tag (an integer from 0 to 255, normally one of the tag_* constants) using the stream State.

Returns {NewState, C}, where C is abytes/0 bytes longer than M, or -1 on failure.

rekey(State)

-spec rekey(State) -> Result when State :: state(), Result :: state().

Explicitly derive a new key for the stream State and return the updated state. The receiver must call rekey/1 at the same point in the stream.

statebytes()

-spec statebytes() -> Result when Result :: 52.

Return crypto_secretstream_xchacha20poly1305_statebytes(), in bytes.

tag_final()

-spec tag_final() -> Result when Result :: 3.

Return crypto_secretstream_xchacha20poly1305_tag_final().

tag_message()

-spec tag_message() -> Result when Result :: 0.

Return crypto_secretstream_xchacha20poly1305_tag_message().

tag_push()

-spec tag_push() -> Result when Result :: 1.

Return crypto_secretstream_xchacha20poly1305_tag_push().

tag_rekey()

-spec tag_rekey() -> Result when Result :: 2.

Return crypto_secretstream_xchacha20poly1305_tag_rekey().