Chacha20-Poly1305

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:

  • Hacl_Chacha20Poly1305_32.h contains the API for the portable C implementation that can be compiled and run on any platform that is 32-bit or higher.

  • Hacl_Chacha20Poly1305_128.h contains the API for the 128-bit vectorized C implementation that can be compiled and run on any platform that supports 128-bit SIMD instructions.

  • Hacl_Chacha20Poly1305_256.h contains the API for the 256-bit vectorized C implementation that can be compiled and run on any platform that supports 256-bit SIMD instructions.

All memory for the output variables have to be allocated by the caller.

Available Implementations#

#include "Hacl_Chacha20Poly1305_32.h"

This implementation works on all CPUs.

Example#

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

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

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

// 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[16];

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

// 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_Chacha20Poly1305_32_aead_decrypt(
  key, nonce, aad_len, (uint8_t*)aad, msg_len, (uint8_t*)recovered, cipher, mac);

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

free(recovered);
free(cipher);

API Reference#

Warning

doxygenfunction: Cannot find function “Hacl_Chacha20Poly1305_32_aead_encrypt” in doxygen xml output for project “HACL Packages” from directory: ../../build/doxygen/xml/

Warning

doxygenfunction: Cannot find function “Hacl_Chacha20Poly1305_32_aead_decrypt” in doxygen xml output for project “HACL Packages” from directory: ../../build/doxygen/xml/

Contents