Chacha20-Poly1305

HACL implements the Chacha20-Poly1305 Authenticated Encryption with Associated Data (AEAD) construction specified in RFC 8439. The library includes three implementations of this construction, all with the same API, for different platforms. All memory for the output variables have to be allocated by the caller.

Available Implementations

32128256

#include "Hacl_AEAD_Chacha20Poly1305.h"

A portable C implementation that can be compiled and run on any platform that is 32-bit or higher.

This implementation works on all CPUs.

API Reference

Example (32)

// HACL* will define these (or something similar) in a future version.
#define HACL_AEAD_CHACHA20_POLY1305_KEY_LEN 32
#define HACL_AEAD_CHACHA20_POLY1305_NONCE_LEN 12
#define HACL_AEAD_CHACHA20_POLY1305_MAC_LEN 16

// Note: This is only an example, and you must bring your own random.

// Create a key ...
uint8_t key[HACL_AEAD_CHACHA20_POLY1305_KEY_LEN];
generate_random(key, HACL_AEAD_CHACHA20_POLY1305_KEY_LEN);

// ... and a nonce.
uint8_t nonce[HACL_AEAD_CHACHA20_POLY1305_NONCE_LEN];
generate_random(nonce, HACL_AEAD_CHACHA20_POLY1305_NONCE_LEN);

// We don't authenticate additional data in this example.
const char* aad = "";
const uint32_t aad_len = strlen(aad);

// This is our message.
const char* msg = "Hello, World!";
const uint32_t msg_len = strlen(msg);

// We need to allocate the same amount of memory for the ciphertext as for
// the plaintext ...
uint8_t* cipher = (uint8_t*)malloc(msg_len);
// ... and also need to provide additional memory for the mac.
// Note that encyption and decryption can also be done in-place, i.e.,
// cipher and plaintext can point to the same memory.
uint8_t mac[HACL_AEAD_CHACHA20_POLY1305_MAC_LEN];

// Encryption.
Hacl_AEAD_Chacha20Poly1305_encrypt(
  cipher, mac, (uint8_t*)msg, msg_len, (uint8_t*)aad, aad_len, key, nonce);

// Decryption.
// Allocate the same amount of memory for the recovered message as for the
// ciphertext.
uint8_t* recovered = (uint8_t*)malloc(msg_len);

uint32_t res = Hacl_AEAD_Chacha20Poly1305_decrypt(
  (uint8_t*)recovered, cipher, msg_len, (uint8_t*)aad, aad_len, key, nonce, mac);

if (res == 0) {
  printf("Decryption successful.");
}

free(recovered);
free(cipher);

32128256

void Hacl_AEAD_Chacha20Poly1305_encrypt(uint8_t *output, uint8_t *tag, uint8_t *input, uint32_t input_len, uint8_t *data, uint32_t data_len, uint8_t *key, uint8_t *nonce)

Encrypt a message input with key key.

The arguments key, nonce, data, and data_len are same in encryption/decryption. Note: Encryption and decryption can be executed in-place, i.e., input and output can point to the same memory.

Parameters:

• output – Pointer to input_len bytes of memory where the ciphertext is written to.

• tag – Pointer to 16 bytes of memory where the mac is written to.

• input – Pointer to input_len bytes of memory where the message is read from.

• input_len – Length of the message.

• data – Pointer to data_len bytes of memory where the associated data is read from.

• data_len – Length of the associated data.

• key – Pointer to 32 bytes of memory where the AEAD key is read from.

• nonce – Pointer to 12 bytes of memory where the AEAD nonce is read from.

uint32_t Hacl_AEAD_Chacha20Poly1305_decrypt(uint8_t *output, uint8_t *input, uint32_t input_len, uint8_t *data, uint32_t data_len, uint8_t *key, uint8_t *nonce, uint8_t *tag)

Decrypt a ciphertext input with key key.

The arguments key, nonce, data, and data_len are same in encryption/decryption. Note: Encryption and decryption can be executed in-place, i.e., output and input can point to the same memory.

If decryption succeeds, the resulting plaintext is stored in output and the function returns the success code 0. If decryption fails, the array output remains unchanged and the function returns the error code 1.

Parameters:

• output – Pointer to input_len bytes of memory where the message is written to.

• input – Pointer to input_len bytes of memory where the ciphertext is read from.

• input_len – Length of the ciphertext.

• data – Pointer to data_len bytes of memory where the associated data is read from.

• data_len – Length of the associated data.

• key – Pointer to 32 bytes of memory where the AEAD key is read from.

• nonce – Pointer to 12 bytes of memory where the AEAD nonce is read from.

• tag – Pointer to 16 bytes of memory where the mac is read from.

Returns:

0 on succeess; 1 on failure.