luajitos

XChaCha20-Poly1305.h (5233B)

---

 /*
  * XChaCha20-Poly1305 AEAD Implementation
  *
  * Compliant with:
  * - draft-irtf-cfrg-xchacha (XChaCha: eXtended-nonce ChaCha and AEAD)
  * - Used in libsodium, WireGuard, age encryption
  *
  * Key Differences from ChaCha20-Poly1305:
  * - 192-bit nonces (24 bytes) instead of 96-bit (12 bytes)
  * - Safe to use random nonces (no collision concerns)
  * - Same performance as ChaCha20-Poly1305
  * - HChaCha20 for key derivation from extended nonce
  *
  * Security Features:
  * - 256-bit keys
  * - 192-bit nonces (can be randomly generated)
  * - Authenticated encryption (AEAD)
  * - Fast software implementation (~1-2 GB/s)
  * - No hardware acceleration needed
  * - No timing attacks
  *
  * Advantages over ChaCha20-Poly1305:
  * - Larger nonce space (2^192 vs 2^96)
  * - Can use random nonces without collision risk
  * - No need for nonce counter management
  * - Simpler to use correctly
  *
  * Use XChaCha20-Poly1305 when:
  * - You want to use random nonces
  * - You don't want to track nonce state
  * - You need nonce misuse resistance
  */
 
 #ifndef XCHACHA20_POLY1305_H
 #define XCHACHA20_POLY1305_H
 
 #include <stdint.h>
 #include <stdlib.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /* Constants */
 #define XCHACHA20_KEY_SIZE 32      /* 256 bits */
 #define XCHACHA20_NONCE_SIZE 24    /* 192 bits (extended) */
 #define XCHACHA20_BLOCK_SIZE 64    /* 512 bits */
 #define XCHACHA20_TAG_SIZE 16      /* 128 bits */
 
 /* XChaCha20 context (reuses ChaCha20 internals) */
 typedef struct {
     uint32_t state[16];
     uint8_t keystream[64];
     size_t keystream_pos;
     uint64_t counter;
 } xchacha20_context;
 
 /* Poly1305 context */
 typedef struct {
     uint32_t r[5];
     uint32_t h[5];
     uint32_t pad[4];
     uint8_t buffer[16];
     size_t buffer_len;
     uint64_t total_len;
 } xchacha20_poly1305_context_mac;
 
 /* XChaCha20-Poly1305 AEAD context */
 typedef struct {
     xchacha20_context cipher;
     xchacha20_poly1305_context_mac mac;
     uint64_t aad_len;
     uint64_t data_len;
 } xchacha20_poly1305_context;
 
 /**
  * Initialize XChaCha20-Poly1305 AEAD
  *
  * @param ctx AEAD context
  * @param key 256-bit (32 byte) encryption key
  * @param nonce 192-bit (24 byte) nonce (can be random!)
  * @return 0 on success, -1 on error
  *
  * Security Notes:
  * - Nonces can be randomly generated (192 bits is large enough)
  * - No need to track nonce counter
  * - Collision probability: ~2^96 messages before concern
  * - Provides both encryption and authentication
  */
 int xchacha20_poly1305_init(xchacha20_poly1305_context *ctx,
                              const uint8_t *key,
                              const uint8_t *nonce);
 
 /**
  * XChaCha20-Poly1305 AEAD Encryption
  *
  * @param ctx Initialized context
  * @param aad Additional authenticated data (can be NULL if aad_len is 0)
  * @param aad_len AAD length in bytes
  * @param plaintext Input plaintext
  * @param pt_len Plaintext length in bytes
  * @param ciphertext Output ciphertext buffer (must be pt_len bytes)
  * @param tag Output authentication tag (must be 16 bytes)
  * @return 0 on success, -1 on error
  *
  * Security Notes:
  * - AAD is authenticated but not encrypted
  * - Maximum plaintext: 2^38 - 64 bytes (~256 GB)
  * - Tag must be sent with ciphertext
  * - Verify tag before using decrypted data
  *
  * Performance:
  * - Same speed as ChaCha20-Poly1305 (~1-2 GB/s)
  * - Minimal overhead from HChaCha20 key derivation
  */
 int xchacha20_poly1305_encrypt(xchacha20_poly1305_context *ctx,
                                 const uint8_t *aad, size_t aad_len,
                                 const uint8_t *plaintext, size_t pt_len,
                                 uint8_t *ciphertext,
                                 uint8_t *tag);
 
 /**
  * XChaCha20-Poly1305 AEAD Decryption
  *
  * @param ctx Initialized context
  * @param aad Additional authenticated data (must match encryption)
  * @param aad_len AAD length in bytes
  * @param ciphertext Input ciphertext
  * @param ct_len Ciphertext length in bytes
  * @param tag Authentication tag from encryption (16 bytes)
  * @param plaintext Output plaintext buffer (must be ct_len bytes)
  * @return 0 on success, -1 on authentication failure
  *
  * Security Notes:
  * - Returns -1 if authentication tag doesn't match
  * - Plaintext is NOT valid if function returns -1
  * - Constant-time tag comparison
  * - MUST verify return value before using plaintext
  */
 int xchacha20_poly1305_decrypt(xchacha20_poly1305_context *ctx,
                                 const uint8_t *aad, size_t aad_len,
                                 const uint8_t *ciphertext, size_t ct_len,
                                 const uint8_t *tag,
                                 uint8_t *plaintext);
 
 /**
  * Clean up context (zeros sensitive data)
  *
  * @param ctx Context to clean
  *
  * Security: Zeros all key material and state
  */
 void xchacha20_poly1305_cleanup(xchacha20_poly1305_context *ctx);
 
 /**
  * HChaCha20 - Key derivation for XChaCha20
  * (Internal function, exposed for testing)
  *
  * @param key 256-bit input key
  * @param nonce 128-bit input (first 16 bytes of XChaCha nonce)
  * @param subkey 256-bit output subkey
  */
 void hchacha20(const uint8_t key[32], const uint8_t nonce[16], uint8_t subkey[32]);
 
 #ifdef __cplusplus
 }
 #endif
 
 #endif /* XCHACHA20_POLY1305_H */