Public-key Authenticated Encryption

Public-key Authenticated Encryption#

Public-key authenticated encryption (Crypto Box).

This module provides a combined- and detached API with and without precomputation. Please make sure that you use the correct pairs of functions to encrypt and decrypt messages as these APIs are not meant to be mixed.

Furthermore, NaCl supports in-place encryption/decryption. Thus, the message and ciphertext are allowed to overlap.

API Reference#

Combined mode#

In combined mode, the authentication tag and encrypted message are stored consecutively in memory. Thus, c must always point to memory with length 16 (tag length) + mlen (message length).

uint32_t Hacl_NaCl_crypto_box_easy(uint8_t *c, uint8_t *m, uint32_t mlen, uint8_t *n, uint8_t *pk, uint8_t *sk)#

Encrypt a message using the recipient’s public key, the sender’s secret key, and a nonce.

Parameters:

  • c – Pointer to 16 (tag length) + mlen bytes of memory where the authentication tag and ciphertext is written to.

  • m – Pointer to mlen bytes of memory where the message is read from.

  • mlen – Length of the message.

  • n – Pointer to 24 (crypto_box_NONCEBYTES) bytes of memory where the nonce is read from.

  • pk – Pointer to 32 bytes of memory where the public key of the recipient is read from.

  • sk – Pointer to 32 bytes of memory where the secret key of the sender is read from.

uint32_t Hacl_NaCl_crypto_box_open_easy(uint8_t *m, uint8_t *c, uint32_t clen, uint8_t *n, uint8_t *pk, uint8_t *sk)#

Verify and decrypt a ciphertext produced by crypto_box_easy.

Parameters:

  • m – Pointer to clen - 16 (tag length) bytes of memory where the decrypted message is written to.

  • c – Pointer to clen bytes of memory where the ciphertext is read from. Note: the ciphertext must include the tag.

  • clen – Length of the ciphertext.

  • n – Pointer to 24 (crypto_box_NONCEBYTES) bytes of memory where the nonce is read from.

  • pk – Pointer to 32 bytes of memory where the public key of the sender is read from.

  • sk – Pointer to 32 bytes of memory where the secret key of the recipient is read from.

Detached mode#

In detached mode, the authentication tag and encrypted message are stored separately. Thus, c must always point to mlen bytes of memory and tag must always point to 16 (tag length) bytes of memory.

Note: NaCl supports in-place encryption/decryption. Thus, the message and ciphertext are allowed to overlap.

uint32_t Hacl_NaCl_crypto_box_detached(uint8_t *c, uint8_t *tag, uint8_t *m, uint32_t mlen, uint8_t *n, uint8_t *pk, uint8_t *sk)#

Encrypt a message using the recipient’s public key, the sender’s secret key, and a nonce.

Parameters:

  • c – Pointer to mlen bytes of memory where the ciphertext is written to.

  • tag – Pointer to 16 (tag length) bytes of memory where the authentication tag is written to.

  • m – Pointer to mlen bytes of memory where the message is read from.

  • mlen – Length of the message.

  • n – Pointer to 24 (crypto_box_NONCEBYTES) bytes of memory where the nonce is read from.

  • pk – Pointer to 32 bytes of memory where their public key is read from.

  • sk – Pointer to 32 bytes of memory where my secret key is read from.

uint32_t Hacl_NaCl_crypto_box_open_detached(uint8_t *m, uint8_t *c, uint8_t *tag, uint32_t mlen, uint8_t *n, uint8_t *pk, uint8_t *sk)#

Verify and decrypt a ciphertext produced by crypto_box_detached.

Parameters:

  • m – Pointer to mlen bytes of memory where the decrypted message is written to.

  • c – Pointer to mlen bytes of memory where the ciphertext is read from. Note: the ciphertext must include the tag.

  • tag – Pointer to 16 (tag length) bytes of memory where the authentication tag is read from.

  • mlen – Length of the message (and ciphertext).

  • n – Pointer to 24 (crypto_box_NONCEBYTES) bytes of memory where the nonce is read from.

  • pk – Pointer to 32 bytes of memory where the public key of the sender is read from.

  • sk – Pointer to 32 bytes of memory where the secret key of the recipient is read from.

With Precomputation#

Applications that send several messages to the same recipient or receive several messages from the same sender can precompute a shared secret k once and reuse it in subsequent _afternm calls to increase performance.

uint32_t Hacl_NaCl_crypto_box_beforenm(uint8_t *k, uint8_t *pk, uint8_t *sk)#

Compute a shared secret key given a public key and secret key.

Parameters:

  • k – Pointer to 32 (crypto_box_BEFORENMBYTES) bytes of memory where the shared secret is written to.

  • pk – Pointer to 32 bytes of memory where their public key is read from.

  • sk – Pointer to 32 bytes of memory where my secret key is read from.

Combined mode#

uint32_t Hacl_NaCl_crypto_box_easy_afternm(uint8_t *c, uint8_t *m, uint32_t mlen, uint8_t *n, uint8_t *k)#

See crypto_box_easy.

uint32_t Hacl_NaCl_crypto_box_open_easy_afternm(uint8_t *m, uint8_t *c, uint32_t clen, uint8_t *n, uint8_t *k)#

See crypto_box_open_easy.

Detached mode#

uint32_t Hacl_NaCl_crypto_box_detached_afternm(uint8_t *c, uint8_t *tag, uint8_t *m, uint32_t mlen, uint8_t *n, uint8_t *k)#

See crypto_box_detached.

uint32_t Hacl_NaCl_crypto_box_open_detached_afternm(uint8_t *m, uint8_t *c, uint8_t *tag, uint32_t mlen, uint8_t *n, uint8_t *k)#

See crypto_box_open_detached.

Contents