@spec box(message(), extended_nonce(), public_key(), private_key()) ::
  {secret_key(), iolist()}

Encrypts a message with your private key and the recipient's public key using Curve25519_XSalsa20_Poly1305.

This function behaves like crypto_box() and crypto_box_easy() do in NaCl and libsodium.

Parameters

• message - Plaintext message to be encrypted
• nonce - 24-byte extended nonce
• their_public - Recipient's 32-byte public X25519 key
• your_private - Your 32-byte private X25519 key

Returns a tuple with the computed shared secret key and the encrypted message.

The returned shared secret key can be used with secretbox/3 for subsequent encrypted messages to the same recipient to avoid having to re-compute the key with box/4 for each message. Doing this would be similar to using crypto_box_afternm() in NaCl, which uses the pre-computed shared secret for multiple messages.

Calls compute_shared_secret/2 then calls secretbox/3 with the result.

@spec box_open(encrypted_message(), extended_nonce(), public_key(), private_key()) ::
  {secret_key(), iolist()} | :error

Decrypts a message with your private key and the sender's public key using Curve25519_XSalsa20_Poly1305.

This function behaves like crypto_box_open() and crypto_box_open_easy() do in NaCl and libsodium.

Parameters

• message - The encrypted message
• nonce - 24-byte extended nonce
• their_public - Sender's 32-byte public X25519 key
• your_private - Your 32-byte private X25519 key

Returns a tuple with the computed shared secret key and the decrypted plaintext.

The returned shared secret key can be used with secretbox_open/3 for subsequent messages from the same sender to avoid having to re-compute the key with box_open/4 for each message. Doing this would be similar to using crypto_box_open_afternm() in NaCl, which uses the pre-computed shared secret for multiple messages.

Calls compute_shared_secret/2 then calls secretbox_open/3 with the result.

@spec compute_shared_secret(public_key(), private_key()) :: secret_key()

Computes the shared secret key given a peer's X25519 public key and your X25519 private key.

Similar to NaCl/libsodium crypto_box_beforenm()/crypto_box_open_beforenm().

Calls :crypto.compute_key/4 then calls Salchicha.Salsa.hsalsa20/2 with the resultant key and 16 zeroes as the input vector.

@spec generate_box_keypair(private_key() | nil) :: {public_key(), private_key()}

Generates a random X25519 key pair for public-key encryption (box/4 and box_open/4).

If a private key is provided it will recover the public key instead of generating a random key pair.

Behaves like NaCl/libsodium crypto_box_keypair(). Calls :crypto.generate_key/3

@spec generate_nonce() :: extended_nonce()

Generates a random 24-byte extended nonce

XSalsa20 and XChaCha20 use a 24-byte nonce, up from the 8 and 8/12 byte nonces of the respective Salsa20 and ChaCha20 ciphers.

You should never reuse the same nonce for a given secret key. 24 bytes are said to be large enough to generate nonces randomly - doing so would be ill-advised with 8-byte nonces since collision would be much more likely.

@spec generate_secret_key() :: secret_key()

Generates a random 32-byte key

@spec generate_sign_keypair(private_key() | nil) :: {public_key(), private_key()}

Generates a random Ed25519 key pair for message signing and signature verification.

If a private key is provided it will recover the public key instead of generating a random key pair.

Behaves like NaCl/libsodium crypto_sign_keypair(). Calls :crypto.generate_key/3

@spec secretbox(message(), extended_nonce(), secret_key()) :: iolist()

Encrypts a message with a secret key using the XSalsa20_Poly1305 authenticated cipher.

This function behaves like crypto_secretbox() does in NaCl.

Parameters

• message - Plaintext message to be encrypted
• nonce - 24-byte extended nonce
• key - 32-byte secret key

The return value is the cipher text prepended by the 16-byte tag (MAC), compatible with NaCl.

Returns an iolist/0 to reduce binary copies. Call IO.iodata_to_binary/1 if you need a single binary.

Calls Salchicha.Salsa.xsalsa20_poly1305_encrypt/3 then concatenates the tag and cipher text

@spec secretbox_open(encrypted_message(), extended_nonce(), secret_key()) ::
  iolist() | :error

Decrypts a message that was encrypted with secretbox/3 using the XSalsa20_Poly1305 authenticated cipher.

This function behaves like crypto_secretbox_open() does in NaCl.

Parameters

• message - The encrypted message (tag prepended to cipher text)
• nonce - 24-byte extended nonce
• key - 32-byte secret key

The return value is the decrypted plaintext (as an iolist) or :error if authentication failed.

Returns an iolist/0 to reduce binary copies. Call IO.iodata_to_binary/1 if you need the message as a binary.

Splits tag and cipher text then calls Salchicha.Salsa.xsalsa20_poly1305_decrypt/4

@spec sign(message(), private_key()) :: signature()

Sign a message with an Ed25519 private key

Behaves like NaCl/libsodium crypto_sign(). Calls :crypto.sign/4

Verifies a message signature with the signer's Ed25519 public key

Behaves like NaCl/libsodium crypto_sign_open(). Calls :crypto.sign/4

@spec xchacha20_poly1305_decrypt(
  encrypted_message(),
  extended_nonce(),
  secret_key(),
  aad()
) ::
  binary() | :error

Decrypts a message that was encrypted in "combined mode" using the XChaCha20_Poly1305 AEAD cipher.

This function behaves like crypto_aead_xchacha20poly1305_ietf_decrypt() does in libsodium.

Parameters

• message - The encrypted message (tag appended to cipher text)
• nonce - 24-byte extended nonce
• key - 32-byte secret key
• aad - Additional authenticated data (defaults to <<>> i.e. no AAD)

The return value is the decrypted plaintext as a binary or :error if authentication failed.

Splits cipher text and tag then calls Salchicha.Chacha.xchacha20_poly1305_decrypt/5

@spec xchacha20_poly1305_decrypt_detached(
  encrypted_message(),
  extended_nonce(),
  secret_key(),
  aad(),
  tag()
) :: binary() | :error

Decrypts a message that was encrypted in "detacheded mode" using the XChaCha20_Poly1305 AEAD cipher.

This function behaves like crypto_aead_xchacha20poly1305_ietf_decrypt_detached() does in libsodium.

Parameters

• cipher_text - The encrypted message (only the cipher text, not appended with the tag)
• nonce - 24-byte extended nonce
• key - 32-byte secret key
• aad - Additional authenticated data (defaults to <<>> i.e. no AAD)
• tag - 16-byte Poly1305 authentication tag or MAC

The return value is the decrypted plaintext as a binary or :error if authentication failed.

This function differs from xchacha20_poly1305_decrypt/4 by returning the tag and cipher text separately

This "detached mode" function differs from the "combined mode" xchacha20_poly1305_decrypt/4 in that the cipher text and tag are supplied as separate parameters, not combined as a single message.

Calls Salchicha.Chacha.xchacha20_poly1305_decrypt/5

@spec xchacha20_poly1305_encrypt(message(), extended_nonce(), secret_key(), aad()) ::
  iolist()

Encrypts a message with a secret key using the XChaCha20_Poly1305 AEAD cipher in "combined mode".

This function behaves like crypto_aead_xchacha20poly1305_ietf_encrypt() does in libsodium.

Parameters

• message - Plaintext message to be encrypted
• nonce - 24-byte extended nonce
• key - 32-byte secret key
• aad - Additional authenticated data (defaults to <<>> i.e. no AAD)

The return value is the cipher text appended by the 16-byte tag (MAC), i.e. "combined mode".

Returns an iolist/0 to reduce binary copies. Call IO.iodata_to_binary/1 if you need a single binary.

Calls Salchicha.Chacha.xchacha20_poly1305_encrypt/4 then concatenates the cipher text and tag

@spec xchacha20_poly1305_encrypt_detached(
  message(),
  extended_nonce(),
  secret_key(),
  aad()
) ::
  {cipher_text(), tag()}

Encrypts a message with a secret key using the XChaCha20_Poly1305 AEAD cipher in "detached mode".

This function behaves like crypto_aead_xchacha20poly1305_ietf_encrypt_detached() does in libsodium.

Parameters

• See xchacha20_poly1305_encrypt/4

This "detached mode" function differs from the "combined mode" xchacha20_poly1305_encrypt/4 by returning the tag and cipher text separately in a tuple in the form {cipher_text, tag}. Both cipher_text and tag will already be binaries.

Calls Salchicha.Chacha.xchacha20_poly1305_encrypt/4