libsodium_crypto_box (libsodium v3.0.1)

Public-key authenticated encryption (X25519, XSalsa20, and Poly1305).

A sender encrypts a message with the recipient's public key PK and their own secret key SK; the recipient opens it with the sender's public key and their own secret key. Keys are publickeybytes/0 and secretkeybytes/0 bytes, and nonces are noncebytes/0 bytes. A nonce must never be reused for the same pair of keys; random nonces are safe at this size. 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 using an ephemeral sender key pair; sealed boxes are sealbytes/0 bytes longer than their messages.

crypto_box/4, open/4, afternm/3, and open_afternm/3 are the NaCl compatibility interface: messages must start with zerobytes/0 zero bytes and ciphertexts with boxzerobytes/0 zero bytes. Prefer the easy API.

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

Summary

Types

k()

A crypto_box_BEFORENMBYTES (32-byte) binary.

mac()

A crypto_box_MACBYTES (16-byte) binary.

n()

A crypto_box_NONCEBYTES (24-byte) binary.

pk()

A crypto_box_PUBLICKEYBYTES (32-byte) binary.

seed()

A crypto_box_SEEDBYTES (32-byte) binary.

sk()

A crypto_box_SECRETKEYBYTES (32-byte) binary.

Functions

afternm(M, N, K)

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

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_beforenmbytes(), in bytes.

boxzerobytes()

Return crypto_box_boxzerobytes(), in bytes.

crypto_box(M, N, PK, SK)

NaCl-compatible encryption of M, which must start with zerobytes/0 zero bytes, using the nonce N, the recipient's public key PK, and the sender's secret key SK.

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_macbytes(), in bytes.

messagebytes_max()

Return crypto_box_messagebytes_max(), in bytes.

noncebytes()

Return crypto_box_noncebytes(), in bytes.

open(C, N, PK, SK)

NaCl-compatible verification and decryption of C, which must start with boxzerobytes/0 zero bytes, using the nonce N, the sender's public key PK, and the recipient's secret key SK.

open_afternm(C, N, K)

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

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.

primitive()

Return crypto_box_primitive() as an atom.

publickeybytes()

Return crypto_box_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; only the recipient can open it, but the sender cannot be identified.

seal_open(C, PK, SK)

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

sealbytes()

Return crypto_box_sealbytes(), in bytes.

secretkeybytes()

Return crypto_box_secretkeybytes(), in bytes.

seed_keypair(Seed)

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

seedbytes()

Return crypto_box_seedbytes(), in bytes.

zerobytes()

Return crypto_box_zerobytes(), in bytes.

Types

k()

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

A crypto_box_BEFORENMBYTES (32-byte) binary.

mac()

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

A crypto_box_MACBYTES (16-byte) binary.

n()

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

A crypto_box_NONCEBYTES (24-byte) binary.

pk()

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

A crypto_box_PUBLICKEYBYTES (32-byte) binary.

seed()

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

A crypto_box_SEEDBYTES (32-byte) binary.

sk()

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

A crypto_box_SECRETKEYBYTES (32-byte) binary.

Functions

afternm(M, N, K)

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

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

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_beforenmbytes(), in bytes.

boxzerobytes()

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

Return crypto_box_boxzerobytes(), in bytes.

crypto_box(M, N, PK, SK)

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

NaCl-compatible encryption of M, which must start with zerobytes/0 zero bytes, using the nonce N, the recipient's public key PK, and the sender's secret key SK.

Returns a ciphertext of the same length as M whose first boxzerobytes/0 bytes are zero, or -1 when M is shorter than zerobytes/0.

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_macbytes(), in bytes.

messagebytes_max()

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

Return crypto_box_messagebytes_max(), in bytes.

noncebytes()

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

Return crypto_box_noncebytes(), in bytes.

open(C, N, PK, SK)

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

NaCl-compatible verification and decryption of C, which must start with boxzerobytes/0 zero bytes, using the nonce N, the sender's public key PK, and the recipient's secret key SK.

Returns a plaintext of the same length as C whose first zerobytes/0 bytes are zero, or -1 when verification fails.

open_afternm(C, N, K)

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

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

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.

primitive()

-spec primitive() -> Result when Result :: curve25519xsalsa20poly1305.

Return crypto_box_primitive() as an atom.

publickeybytes()

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

Return crypto_box_publickeybytes(), in bytes.

seal(M, PK)

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

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_sealbytes(), in bytes.

secretkeybytes()

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

Return crypto_box_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_seedbytes(), in bytes.

zerobytes()

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

Return crypto_box_zerobytes(), in bytes.