libsodium_crypto_box_curve25519xchacha20poly1305 (libsodium v3.0.1)

View Source

Public-key authenticated encryption with X25519, XChaCha20, and Poly1305.

This is the same construction as libsodium_crypto_box, using XChaCha20 instead of XSalsa20. Keys are publickeybytes/0 and secretkeybytes/0 bytes, and nonces are noncebytes/0 bytes. Random nonces are safe at this size, but a nonce must never be reused for the same pair of keys. Ciphertexts are macbytes/0 bytes longer than their messages.

beforenm/2 precomputes the beforenmbytes/0 byte shared key used by the _afternm variants. seal/2 and seal_open/3 provide anonymous encryption to a public key; sealed boxes are sealbytes/0 bytes longer than their messages.

{AlicePK, AliceSK} = libsodium_crypto_box_curve25519xchacha20poly1305:keypair(),
{BobPK, BobSK} = libsodium_crypto_box_curve25519xchacha20poly1305:keypair(),
Nonce = libsodium_randombytes:buf(libsodium_crypto_box_curve25519xchacha20poly1305:noncebytes()),
Ciphertext = libsodium_crypto_box_curve25519xchacha20poly1305:easy(<<"message">>, Nonce, BobPK, AliceSK),
<<"message">> = libsodium_crypto_box_curve25519xchacha20poly1305:open_easy(Ciphertext, Nonce, AlicePK, BobSK).

Summary

Types

k()

A crypto_box_curve25519xchacha20poly1305_BEFORENMBYTES (32-byte) binary.

mac()

A crypto_box_curve25519xchacha20poly1305_MACBYTES (16-byte) binary.

n()

A crypto_box_curve25519xchacha20poly1305_NONCEBYTES (24-byte) binary.

pk()

A crypto_box_curve25519xchacha20poly1305_PUBLICKEYBYTES (32-byte) binary.

seed()

A crypto_box_curve25519xchacha20poly1305_SEEDBYTES (32-byte) binary.

sk()

A crypto_box_curve25519xchacha20poly1305_SECRETKEYBYTES (32-byte) binary.

Functions

beforenm(PK, SK)

Precompute the beforenmbytes/0 byte shared key for the public key PK and the secret key SK, for use with the _afternm functions.

beforenmbytes()

Return crypto_box_curve25519xchacha20poly1305_beforenmbytes(), in bytes.

detached(M, N, PK, SK)

Like easy/4, but returns the ciphertext and the macbytes/0 byte authentication tag separately as {C, MAC}.

detached_afternm(M, N, K)

Like detached/4, using the shared key K precomputed by beforenm/2. Returns {C, MAC}.

easy(M, N, PK, SK)

Encrypt and authenticate M with the nonce N, the recipient's public key PK, and the sender's secret key SK.

easy_afternm(M, N, K)

Like easy/4, using the shared key K precomputed by beforenm/2.

keypair()

Generate a random key pair. Returns {PK, SK}.

macbytes()

Return crypto_box_curve25519xchacha20poly1305_macbytes(), in bytes.

messagebytes_max()

Return crypto_box_curve25519xchacha20poly1305_messagebytes_max(), in bytes.

noncebytes()

Return crypto_box_curve25519xchacha20poly1305_noncebytes(), in bytes.

open_detached(C, MAC, N, PK, SK)

Verify the detached tag MAC and decrypt C with the nonce N, the sender's public key PK, and the recipient's secret key SK.

open_detached_afternm(C, MAC, N, K)

Like open_detached/5, using the shared key K precomputed by beforenm/2. Returns -1 when verification fails.

open_easy(C, N, PK, SK)

Verify and decrypt C, produced by easy/4, with the nonce N, the sender's public key PK, and the recipient's secret key SK.

open_easy_afternm(C, N, K)

Like open_easy/4, using the shared key K precomputed by beforenm/2. Returns -1 when verification fails.

publickeybytes()

Return crypto_box_curve25519xchacha20poly1305_publickeybytes(), in bytes.

seal(M, PK)

Anonymously encrypt M for the recipient's public key PK using a new ephemeral key pair. The result is sealbytes/0 bytes longer than M.

seal_open(C, PK, SK)

Open the sealed box C with the recipient's key pair PK and SK.

sealbytes()

Return crypto_box_curve25519xchacha20poly1305_sealbytes(), in bytes.

secretkeybytes()

Return crypto_box_curve25519xchacha20poly1305_secretkeybytes(), in bytes.

seed_keypair(Seed)

Deterministically derive a key pair from the seedbytes/0 byte Seed. Returns {PK, SK}.

seedbytes()

Return crypto_box_curve25519xchacha20poly1305_seedbytes(), in bytes.

Types

k()

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

A crypto_box_curve25519xchacha20poly1305_BEFORENMBYTES (32-byte) binary.

mac()

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

A crypto_box_curve25519xchacha20poly1305_MACBYTES (16-byte) binary.

n()

-type n() :: <<_:192>>.

A crypto_box_curve25519xchacha20poly1305_NONCEBYTES (24-byte) binary.

pk()

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

A crypto_box_curve25519xchacha20poly1305_PUBLICKEYBYTES (32-byte) binary.

seed()

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

A crypto_box_curve25519xchacha20poly1305_SEEDBYTES (32-byte) binary.

sk()

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

A crypto_box_curve25519xchacha20poly1305_SECRETKEYBYTES (32-byte) binary.

Functions

beforenm(PK, SK)

-spec beforenm(PK, SK) -> Result when PK :: pk(), SK :: sk(), Result :: k() | -1.

Precompute the beforenmbytes/0 byte shared key for the public key PK and the secret key SK, for use with the _afternm functions.

Returns -1 when PK is a low-order point.

beforenmbytes()

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

Return crypto_box_curve25519xchacha20poly1305_beforenmbytes(), in bytes.

detached(M, N, PK, SK)

-spec detached(M, N, PK, SK) -> Result
                  when M :: binary(), N :: n(), PK :: pk(), SK :: sk(), Result :: {binary(), mac()} | -1.

Like easy/4, but returns the ciphertext and the macbytes/0 byte authentication tag separately as {C, MAC}.

detached_afternm(M, N, K)

-spec detached_afternm(M, N, K) -> Result
                          when M :: binary(), N :: n(), K :: k(), Result :: {binary(), mac()} | -1.

Like detached/4, using the shared key K precomputed by beforenm/2. Returns {C, MAC}.

easy(M, N, PK, SK)

-spec easy(M, N, PK, SK) -> Result
              when M :: binary(), N :: n(), PK :: pk(), SK :: sk(), Result :: binary() | -1.

Encrypt and authenticate M with the nonce N, the recipient's public key PK, and the sender's secret key SK.

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

easy_afternm(M, N, K)

-spec easy_afternm(M, N, K) -> Result when M :: binary(), N :: n(), K :: k(), Result :: binary() | -1.

Like easy/4, using the shared key K precomputed by beforenm/2.

keypair()

-spec keypair() -> Result when Result :: {pk(), sk()} | -1.

Generate a random key pair. Returns {PK, SK}.

macbytes()

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

Return crypto_box_curve25519xchacha20poly1305_macbytes(), in bytes.

messagebytes_max()

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

Return crypto_box_curve25519xchacha20poly1305_messagebytes_max(), in bytes.

noncebytes()

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

Return crypto_box_curve25519xchacha20poly1305_noncebytes(), in bytes.

open_detached(C, MAC, N, PK, SK)

-spec open_detached(C, MAC, N, PK, SK) -> Result
                       when
                           C :: binary(),
                           MAC :: mac(),
                           N :: n(),
                           PK :: pk(),
                           SK :: sk(),
                           Result :: binary() | -1.

Verify the detached tag MAC and decrypt C with the nonce N, the sender's public key PK, and the recipient's secret key SK.

Returns the plaintext, or -1 when verification fails.

open_detached_afternm(C, MAC, N, K)

-spec open_detached_afternm(C, MAC, N, K) -> Result
                               when
                                   C :: binary(),
                                   MAC :: mac(),
                                   N :: n(),
                                   K :: k(),
                                   Result :: binary() | -1.

Like open_detached/5, using the shared key K precomputed by beforenm/2. Returns -1 when verification fails.

open_easy(C, N, PK, SK)

-spec open_easy(C, N, PK, SK) -> Result
                   when C :: binary(), N :: n(), PK :: pk(), SK :: sk(), Result :: binary() | -1.

Verify and decrypt C, produced by easy/4, with the nonce N, the sender's public key PK, and the recipient's secret key SK.

Returns the plaintext, or -1 when verification fails.

open_easy_afternm(C, N, K)

-spec open_easy_afternm(C, N, K) -> Result
                           when C :: binary(), N :: n(), K :: k(), Result :: binary() | -1.

Like open_easy/4, using the shared key K precomputed by beforenm/2. Returns -1 when verification fails.

publickeybytes()

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

Return crypto_box_curve25519xchacha20poly1305_publickeybytes(), in bytes.

seal(M, PK)

-spec seal(M, PK) -> Result when M :: binary(), PK :: pk(), Result :: binary() | -1.

Anonymously encrypt M for the recipient's public key PK using a new ephemeral key pair. The result is sealbytes/0 bytes longer than M.

seal_open(C, PK, SK)

-spec seal_open(C, PK, SK) -> Result when C :: binary(), PK :: pk(), SK :: sk(), Result :: binary() | -1.

Open the sealed box C with the recipient's key pair PK and SK.

Returns the plaintext, or -1 when verification fails. Raises badarg when C is shorter than sealbytes/0.

sealbytes()

-spec sealbytes() -> Result when Result :: 48.

Return crypto_box_curve25519xchacha20poly1305_sealbytes(), in bytes.

secretkeybytes()

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

Return crypto_box_curve25519xchacha20poly1305_secretkeybytes(), in bytes.

seed_keypair(Seed)

-spec seed_keypair(Seed) -> Result when Seed :: seed(), Result :: {pk(), sk()} | -1.

Deterministically derive a key pair from the seedbytes/0 byte Seed. Returns {PK, SK}.

seedbytes()

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

Return crypto_box_curve25519xchacha20poly1305_seedbytes(), in bytes.