libsodium_crypto_aead_chacha20poly1305 (libsodium v3.0.1)

View Source

ChaCha20-Poly1305 authenticated encryption with additional data, in both the IETF variant (RFC 8439, ietf_* functions) and the original variant.

The IETF variant uses a nonce of ietf_npubbytes/0 (12) bytes and limits a single message to about 256 GiB; the original variant uses a nonce of npubbytes/0 (8) bytes. Keys are keybytes/0 bytes for both. Nonces are too short to be chosen at random safely for many messages and must never be reused with the same key; prefer libsodium_crypto_aead_xchacha20poly1305 for random nonces.

Key = libsodium_crypto_aead_chacha20poly1305:ietf_keygen(),
Nonce = libsodium_randombytes:buf(libsodium_crypto_aead_chacha20poly1305:ietf_npubbytes()),
Ciphertext = libsodium_crypto_aead_chacha20poly1305:ietf_encrypt(<<"message">>, <<"header">>, Nonce, Key),
<<"message">> = libsodium_crypto_aead_chacha20poly1305:ietf_decrypt(Ciphertext, <<"header">>, Nonce, Key).

Summary

Types

ietf_npub()

A crypto_aead_chacha20poly1305_ietf_NPUBBYTES (12-byte) binary.

k()

A crypto_aead_chacha20poly1305_ietf_KEYBYTES (32-byte) binary.

mac()

A crypto_aead_chacha20poly1305_ietf_ABYTES (16-byte) binary.

npub()

A crypto_aead_chacha20poly1305_NPUBBYTES (8-byte) binary.

Functions

abytes()

Return crypto_aead_chacha20poly1305_abytes(), in bytes.

decrypt(C, NPub, K)

Verify and decrypt the ciphertext C produced by encrypt/4 with the additional data AD (default empty), nonce NPub, and key K.

decrypt(C, AD, NPub, K)

Verify and decrypt the ciphertext C produced by encrypt/4 with the additional data AD (default empty), nonce NPub, and key K.

decrypt_detached(C, MAC, NPub, K)

Like decrypt/4, verifying the detached tag MAC for C. Returns the plaintext, or -1 when verification fails.

decrypt_detached(C, MAC, AD, NPub, K)

Like decrypt/4, verifying the detached tag MAC for C. Returns the plaintext, or -1 when verification fails.

encrypt(M, NPub, K)

Encrypt and authenticate M together with the additional data AD (default empty) using the original construction with the npubbytes/0 byte nonce NPub and the keybytes/0 byte key K.

encrypt(M, AD, NPub, K)

Encrypt and authenticate M together with the additional data AD (default empty) using the original construction with the npubbytes/0 byte nonce NPub and the keybytes/0 byte key K.

encrypt_detached(M, NPub, K)

Like encrypt/4, returning the ciphertext and the abytes/0 byte authentication tag separately as {C, MAC}, or -1 on failure.

encrypt_detached(M, AD, NPub, K)

Like encrypt/4, returning the ciphertext and the abytes/0 byte authentication tag separately as {C, MAC}, or -1 on failure.

ietf_abytes()

Return crypto_aead_chacha20poly1305_ietf_abytes(), in bytes.

ietf_decrypt(C, NPub, K)

Verify and decrypt the ciphertext C with the additional data AD (default empty), nonce NPub, and key K.

ietf_decrypt(C, AD, NPub, K)

Verify and decrypt the ciphertext C with the additional data AD (default empty), nonce NPub, and key K.

ietf_decrypt_detached(C, MAC, NPub, K)

Verify the detached tag MAC and decrypt C with the additional data AD (default empty). Returns the plaintext, or -1 when verification fails.

ietf_decrypt_detached(C, MAC, AD, NPub, K)

Verify the detached tag MAC and decrypt C with the additional data AD (default empty). Returns the plaintext, or -1 when verification fails.

ietf_encrypt(M, NPub, K)

Encrypt and authenticate M together with the additional data AD (default empty) using the ietf_npubbytes/0 byte nonce NPub and the ietf_keybytes/0 byte key K.

ietf_encrypt(M, AD, NPub, K)

Encrypt and authenticate M together with the additional data AD (default empty) using the ietf_npubbytes/0 byte nonce NPub and the ietf_keybytes/0 byte key K.

ietf_encrypt_detached(M, NPub, K)

Encrypt and authenticate M with the additional data AD (default empty), returning the ciphertext and the ietf_abytes/0 byte authentication tag separately as {C, MAC}, or -1 on failure.

ietf_encrypt_detached(M, AD, NPub, K)

Encrypt and authenticate M with the additional data AD (default empty), returning the ciphertext and the ietf_abytes/0 byte authentication tag separately as {C, MAC}, or -1 on failure.

ietf_keybytes()

Return crypto_aead_chacha20poly1305_ietf_keybytes(), in bytes.

ietf_keygen()

Generate a random ietf_keybytes/0 byte key.

ietf_messagebytes_max()

Return crypto_aead_chacha20poly1305_ietf_messagebytes_max(), in bytes.

ietf_npubbytes()

Return crypto_aead_chacha20poly1305_ietf_npubbytes(), in bytes.

ietf_nsecbytes()

Return crypto_aead_chacha20poly1305_ietf_nsecbytes(), in bytes.

keybytes()

Return crypto_aead_chacha20poly1305_keybytes(), in bytes.

keygen()

Generate a random keybytes/0 byte key.

messagebytes_max()

Return crypto_aead_chacha20poly1305_messagebytes_max(), in bytes.

npubbytes()

Return crypto_aead_chacha20poly1305_npubbytes(), in bytes.

nsecbytes()

Return crypto_aead_chacha20poly1305_nsecbytes(), in bytes.

Types

ietf_npub()

-type ietf_npub() :: <<_:96>>.

A crypto_aead_chacha20poly1305_ietf_NPUBBYTES (12-byte) binary.

k()

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

A crypto_aead_chacha20poly1305_ietf_KEYBYTES (32-byte) binary.

mac()

-type mac() :: <<_:128>>.

A crypto_aead_chacha20poly1305_ietf_ABYTES (16-byte) binary.

npub()

-type npub() :: <<_:64>>.

A crypto_aead_chacha20poly1305_NPUBBYTES (8-byte) binary.

Functions

abytes()

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

Return crypto_aead_chacha20poly1305_abytes(), in bytes.

decrypt(C, NPub, K)

-spec decrypt(C, NPub, K) -> Result
                 when C :: binary(), NPub :: npub(), K :: k(), Result :: binary() | -1.

Verify and decrypt the ciphertext C produced by encrypt/4 with the additional data AD (default empty), nonce NPub, and key K.

Returns the plaintext, or -1 when verification fails.

decrypt(C, AD, NPub, K)

-spec decrypt(C, AD, NPub, K) -> Result
                 when C :: binary(), AD :: binary(), NPub :: npub(), K :: k(), Result :: binary() | -1.

Verify and decrypt the ciphertext C produced by encrypt/4 with the additional data AD (default empty), nonce NPub, and key K.

Returns the plaintext, or -1 when verification fails.

decrypt_detached(C, MAC, NPub, K)

-spec decrypt_detached(C, MAC, NPub, K) -> Result
                          when
                              C :: binary(),
                              MAC :: mac(),
                              NPub :: npub(),
                              K :: k(),
                              Result :: binary() | -1.

Like decrypt/4, verifying the detached tag MAC for C. Returns the plaintext, or -1 when verification fails.

decrypt_detached(C, MAC, AD, NPub, K)

-spec decrypt_detached(C, MAC, AD, NPub, K) -> Result
                          when
                              C :: binary(),
                              MAC :: mac(),
                              AD :: binary(),
                              NPub :: npub(),
                              K :: k(),
                              Result :: binary() | -1.

Like decrypt/4, verifying the detached tag MAC for C. Returns the plaintext, or -1 when verification fails.

encrypt(M, NPub, K)

-spec encrypt(M, NPub, K) -> Result
                 when M :: binary(), NPub :: npub(), K :: k(), Result :: binary() | -1.

Encrypt and authenticate M together with the additional data AD (default empty) using the original construction with the npubbytes/0 byte nonce NPub and the keybytes/0 byte key K.

Returns the ciphertext followed by an abytes/0 byte authentication tag, or -1 on failure.

encrypt(M, AD, NPub, K)

-spec encrypt(M, AD, NPub, K) -> Result
                 when M :: binary(), AD :: binary(), NPub :: npub(), K :: k(), Result :: binary() | -1.

Encrypt and authenticate M together with the additional data AD (default empty) using the original construction with the npubbytes/0 byte nonce NPub and the keybytes/0 byte key K.

Returns the ciphertext followed by an abytes/0 byte authentication tag, or -1 on failure.

encrypt_detached(M, NPub, K)

-spec encrypt_detached(M, NPub, K) -> Result
                          when M :: binary(), NPub :: npub(), K :: k(), Result :: {binary(), mac()} | -1.

Like encrypt/4, returning the ciphertext and the abytes/0 byte authentication tag separately as {C, MAC}, or -1 on failure.

encrypt_detached(M, AD, NPub, K)

-spec encrypt_detached(M, AD, NPub, K) -> Result
                          when
                              M :: binary(),
                              AD :: binary(),
                              NPub :: npub(),
                              K :: k(),
                              Result :: {binary(), mac()} | -1.

Like encrypt/4, returning the ciphertext and the abytes/0 byte authentication tag separately as {C, MAC}, or -1 on failure.

ietf_abytes()

-spec ietf_abytes() -> Result when Result :: 16.

Return crypto_aead_chacha20poly1305_ietf_abytes(), in bytes.

ietf_decrypt(C, NPub, K)

-spec ietf_decrypt(C, NPub, K) -> Result
                      when C :: binary(), NPub :: ietf_npub(), K :: k(), Result :: binary() | -1.

Verify and decrypt the ciphertext C with the additional data AD (default empty), nonce NPub, and key K.

Returns the plaintext, or -1 when verification fails.

ietf_decrypt(C, AD, NPub, K)

-spec ietf_decrypt(C, AD, NPub, K) -> Result
                      when
                          C :: binary(),
                          AD :: binary(),
                          NPub :: ietf_npub(),
                          K :: k(),
                          Result :: binary() | -1.

Verify and decrypt the ciphertext C with the additional data AD (default empty), nonce NPub, and key K.

Returns the plaintext, or -1 when verification fails.

ietf_decrypt_detached(C, MAC, NPub, K)

-spec ietf_decrypt_detached(C, MAC, NPub, K) -> Result
                               when
                                   C :: binary(),
                                   MAC :: mac(),
                                   NPub :: ietf_npub(),
                                   K :: k(),
                                   Result :: binary() | -1.

Verify the detached tag MAC and decrypt C with the additional data AD (default empty). Returns the plaintext, or -1 when verification fails.

ietf_decrypt_detached(C, MAC, AD, NPub, K)

-spec ietf_decrypt_detached(C, MAC, AD, NPub, K) -> Result
                               when
                                   C :: binary(),
                                   MAC :: mac(),
                                   AD :: binary(),
                                   NPub :: ietf_npub(),
                                   K :: k(),
                                   Result :: binary() | -1.

Verify the detached tag MAC and decrypt C with the additional data AD (default empty). Returns the plaintext, or -1 when verification fails.

ietf_encrypt(M, NPub, K)

-spec ietf_encrypt(M, NPub, K) -> Result
                      when M :: binary(), NPub :: ietf_npub(), K :: k(), Result :: binary() | -1.

Encrypt and authenticate M together with the additional data AD (default empty) using the ietf_npubbytes/0 byte nonce NPub and the ietf_keybytes/0 byte key K.

Returns the ciphertext followed by an ietf_abytes/0 byte authentication tag, or -1 on failure.

ietf_encrypt(M, AD, NPub, K)

-spec ietf_encrypt(M, AD, NPub, K) -> Result
                      when
                          M :: binary(),
                          AD :: binary(),
                          NPub :: ietf_npub(),
                          K :: k(),
                          Result :: binary() | -1.

Encrypt and authenticate M together with the additional data AD (default empty) using the ietf_npubbytes/0 byte nonce NPub and the ietf_keybytes/0 byte key K.

Returns the ciphertext followed by an ietf_abytes/0 byte authentication tag, or -1 on failure.

ietf_encrypt_detached(M, NPub, K)

-spec ietf_encrypt_detached(M, NPub, K) -> Result
                               when
                                   M :: binary(),
                                   NPub :: ietf_npub(),
                                   K :: k(),
                                   Result :: {binary(), mac()} | -1.

Encrypt and authenticate M with the additional data AD (default empty), returning the ciphertext and the ietf_abytes/0 byte authentication tag separately as {C, MAC}, or -1 on failure.

ietf_encrypt_detached(M, AD, NPub, K)

-spec ietf_encrypt_detached(M, AD, NPub, K) -> Result
                               when
                                   M :: binary(),
                                   AD :: binary(),
                                   NPub :: ietf_npub(),
                                   K :: k(),
                                   Result :: {binary(), mac()} | -1.

Encrypt and authenticate M with the additional data AD (default empty), returning the ciphertext and the ietf_abytes/0 byte authentication tag separately as {C, MAC}, or -1 on failure.

ietf_keybytes()

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

Return crypto_aead_chacha20poly1305_ietf_keybytes(), in bytes.

ietf_keygen()

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

Generate a random ietf_keybytes/0 byte key.

ietf_messagebytes_max()

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

Return crypto_aead_chacha20poly1305_ietf_messagebytes_max(), in bytes.

ietf_npubbytes()

-spec ietf_npubbytes() -> Result when Result :: 12.

Return crypto_aead_chacha20poly1305_ietf_npubbytes(), in bytes.

ietf_nsecbytes()

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

Return crypto_aead_chacha20poly1305_ietf_nsecbytes(), in bytes.

keybytes()

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

Return crypto_aead_chacha20poly1305_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_aead_chacha20poly1305_messagebytes_max(), in bytes.

npubbytes()

-spec npubbytes() -> Result when Result :: 8.

Return crypto_aead_chacha20poly1305_npubbytes(), in bytes.

nsecbytes()

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

Return crypto_aead_chacha20poly1305_nsecbytes(), in bytes.