Secret-key Authenticated Encryption#

Secret-key Authenticated Encryption (Secret Box).

This module provides a combined- and detached API. 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#

// Generate a symmetric key for encryption.
uint8_t key[HACL_NACL_CRYPTO_SECRETBOX_KEYBYTES];
generate_random(key, HACL_NACL_CRYPTO_SECRETBOX_KEYBYTES);

const char* plaintext = "Hello, World!";
const size_t plaintext_size = strlen(plaintext);

// Generate a nonce.
uint8_t nonce[HACL_NACL_CRYPTO_SECRETBOX_NONCEBYTES];
generate_random(nonce, HACL_NACL_CRYPTO_SECRETBOX_NONCEBYTES);

// Encrypt.
uint8_t* ciphertext =
  (uint8_t*)malloc(HACL_NACL_CRYPTO_SECRETBOX_MACBYTES + plaintext_size);
uint32_t res_enc = Hacl_NaCl_crypto_secretbox_easy(
  ciphertext, (uint8_t*)plaintext, plaintext_size, nonce, key);

// Decrypt.
uint8_t* decrypted = (uint8_t*)malloc(plaintext_size);
uint32_t res_dec = Hacl_NaCl_crypto_secretbox_open_easy(
  decrypted,
  ciphertext,
  HACL_NACL_CRYPTO_SECRETBOX_MACBYTES + plaintext_size,
  nonce,
  key);

free(decrypted);
free(ciphertext);

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_secretbox_easy(uint8_t *c, uint8_t *m, uint32_t mlen, uint8_t *n, uint8_t *k)#

Encrypt a message with a key and nonce.

Parameters

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

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

  • mlen – Length of message.

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

  • k – Pointer to 32 (crypto_secretbox_KEYBYTES) bytes where the key is read from.

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

Verify and decrypt a ciphertext produced with crypto_secretbox_easy.

Parameters

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

  • c – Pointer to clen bytes where the ciphertext is read from. The authentication tag must be included.

  • clen – Length of ciphertext.

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

  • k – Pointer to 32 (crypto_secretbox_KEYBYTES) bytes where the key is read from.

Detached mode#

// Generate a symmetric key for encryption.
uint8_t key[HACL_NACL_CRYPTO_SECRETBOX_KEYBYTES];
generate_random(key, HACL_NACL_CRYPTO_SECRETBOX_KEYBYTES);

const char* plaintext = "Hello, World!";
const size_t plaintext_size = strlen(plaintext);

// Generate a nonce.
uint8_t nonce[HACL_NACL_CRYPTO_SECRETBOX_NONCEBYTES];
generate_random(nonce, HACL_NACL_CRYPTO_SECRETBOX_NONCEBYTES);

// Encrypt.
uint8_t* ciphertext = (uint8_t*)malloc(plaintext_size);
uint8_t tag[HACL_NACL_CRYPTO_SECRETBOX_MACBYTES];
uint32_t res_enc = Hacl_NaCl_crypto_secretbox_detached(
  ciphertext, tag, (uint8_t*)plaintext, plaintext_size, nonce, key);

// Decrypt.
uint8_t* decrypted = (uint8_t*)malloc(plaintext_size);
uint32_t res_dec = Hacl_NaCl_crypto_secretbox_open_detached(
  decrypted, ciphertext, tag, plaintext_size, nonce, key);

free(decrypted);
free(ciphertext);

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

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

Encrypt a message with a key and nonce.

Note: c and m can point to the same memory for in-place encryption.

Parameters

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

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

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

  • mlen – Length of message.

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

  • k – Pointer to 32 (crypto_secretbox_KEYBYTES) bytes where the key is read from.

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

Verify and decrypt a ciphertext produced with Hacl_NaCl_crypto_secretbox_detached.

Note: m and c can point to the same memory for in-place decryption.

Parameters

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

  • c – Pointer to mlen bytes where the ciphertext is read from.

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

  • mlen – Length of message (and ciphertext).

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

  • k – Pointer to 32 (crypto_secretbox_KEYBYTES) bytes where the key is read from.