Which API to use

HACL* APIs are specialized for a given architecture revision and do not have any agility overhead. Consider, for instance, Chacha-Poly encryption from Hacl_Chacha20Poly1305_256.h:

  uint8_t *k,
  uint8_t *n,
  uint32_t aadlen,
  uint8_t *aad,
  uint32_t mlen,
  uint8_t *m,
  uint8_t *cipher,
  uint8_t *mac

In order to use this function, you must ascertain that the architecture you’re running on supports 256-bit vector instructions (AVX2 + SSE4); furthermore, your code will have to be changed if you need another AEAD algorithm such as AES-GCM. This is an efficient API, as it does not require any extra API calls and does not allocate any intermediary state.

EverCrypt APIs, on the other hand, can do CPU detection for clients, via a helper function found in EverCrypt_AutoConfig2.h.

void EverCrypt_AutoConfig2_init();

EverCrypt APIs are generally agile, i.e. clients only need to change one argument to a function call in order to use a different algorithm; furthermore, those APIs are multiplexing, i.e. they automatically pick the most suitable implementation based on he results of target CPU detection.

This means that the EverCrypt API for Chacha-Poly is found in EverCrypt_AEAD.h; clients are expected to first allocate state, passing in the desired AEAD algorithm as a parameter (agility):

EverCrypt_AEAD_create_in(Spec_Agile_AEAD_alg a, EverCrypt_AEAD_state_s **dst, uint8_t *k);

Then, will clients be able to encrypt:

  EverCrypt_AEAD_state_s *s,
  uint8_t *iv,
  uint32_t iv_len,
  uint8_t *ad,
  uint32_t ad_len,
  uint8_t *plain,
  uint32_t plain_len,
  uint8_t *cipher,
  uint8_t *tag