NaCl API: Box and SecretBox¶

Public-Key Encryption: Box¶

The simplest API for Box encryption and decryption is as follows:

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

The encryption function Hacl_NaCl_crypto_box_easy takes as its arguments an output array c of length mlen+16 bytes, an input array m of length mlen bytes, a nonce n1 of length 24 bytes, the Curve25519 private key sk of the sender (32 bytes), and the Curve25519 public key pk of the recipient (32 bytes). The function returns 0 on success and -1 (i.e. 0xffffffff) on failure.

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

The corresponding decryption function Hacl_NaCl_crypto_box_open_easy takes the dual arguments: an input array c of length clen>16 bytes, an output array m of length clen-16 bytes, a nonce n1 of length 24 bytes, the Curve25519 public key pk of the sender (32 bytes), and the Curve25519 private key sk of the recipient (32 bytes). The function retuens 0 on success and -1 (i.e. 0xffffffff) on failure.

Hacl_NaCl.h also contains two other APIs for Box:

• Hacl_NaCl_crypto_box_detached and Hacl_NaCl_crypto_box_open_detached store the 16-byte authentication tag in in a separate buffer called tag
• To share the expensive X25519 ECDH computation across multiple invocations between the same sender and recipient keys, callers can first call Hacl_NaCl_crypto_box_beforenm and then use the result to call Hacl_NaCl_crypto_box_detached_afternm or Hacl_NaCl_crypto_box_easy_afternm multiple times.

Symmetric Encryption: SecretBox¶

The NaCl API also provides a symmetric encryption primive with the following “easy” API:

uint32_t
Hacl_NaCl_crypto_secretbox_easy(uint8_t *c, uint8_t *m, uint32_t mlen, uint8_t *n, uint8_t *k);

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

The main difference from the Box API is that these functions take a shared symmetric key k as input (instead of Curve25519 keys for the sender and recipient.) As with Box, there is a separate detached version of this API.