luajitos

ChaCha20-Poly1305.h (5485B)

---

 /*
  * ChaCha20-Poly1305 AEAD Implementation
  *
  * Compliant with:
  * - RFC 8439 (ChaCha20 and Poly1305 for IETF Protocols)
  * - Used in TLS 1.3, WireGuard, OpenSSH
  *
  * ⚠️  WARNING: 96-bit Nonces - DO NOT use random nonces!
  * - MUST use sequential counter nonces (never reuse!)
  * - Random nonces have collision risk after ~2^32 messages
  * - Consider XChaCha20-Poly1305 for random nonces (192-bit)
  *
  * Security Features:
  * - 256-bit keys
  * - 96-bit nonces (MUST be sequential or unique)
  * - Authenticated encryption (AEAD)
  * - Fast software implementation (~1-2 GB/s)
  * - No hardware acceleration needed
  * - No timing attacks
  * - Simpler than AES-GCM
  *
  * Advantages over AES-GCM:
  * - Faster on CPUs without AES-NI
  * - Simpler implementation
  * - No cache-timing vulnerabilities
  * - Better performance on mobile devices
  *
  * When to use XChaCha20-Poly1305 instead:
  * - You want to use random nonces (simpler, safer)
  * - You can't reliably track nonce state
  * - You're encrypting many messages (>2^32)
  */
 
 #ifndef CHACHA20_POLY1305_H
 #define CHACHA20_POLY1305_H
 
 #include <stdint.h>
 #include <stdlib.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /* Constants */
 #define CHACHA20_KEY_SIZE 32      /* 256 bits */
 #define CHACHA20_NONCE_SIZE 12    /* 96 bits (IETF version) */
 #define CHACHA20_BLOCK_SIZE 64    /* 512 bits */
 #define POLY1305_KEY_SIZE 32      /* 256 bits */
 #define POLY1305_TAG_SIZE 16      /* 128 bits */
 
 /* ChaCha20 context */
 typedef struct {
     uint32_t state[16];
     uint8_t keystream[64];
     size_t keystream_pos;
     uint64_t counter;
 } chacha20_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;
 } poly1305_context;
 
 /* ChaCha20-Poly1305 AEAD context */
 typedef struct {
     chacha20_context cipher;
     poly1305_context mac;
     uint64_t aad_len;
     uint64_t data_len;
 } chacha20_poly1305_context;
 
 /**
  * Initialize ChaCha20-Poly1305 AEAD
  *
  * @param ctx AEAD context
  * @param key 256-bit (32 byte) encryption key
  * @param nonce 96-bit (12 byte) nonce
  * @return 0 on success, -1 on error
  *
  * ⚠️  Security Notes:
  * - NEVER reuse (key, nonce) pairs
  * - DO NOT use random nonces (collision risk after ~2^32 messages)
  * - MUST use sequential counter or guaranteed-unique nonces
  * - For random nonces, use XChaCha20-Poly1305 instead (192-bit)
  * - Used in TLS 1.3, WireGuard, SSH
  * - Provides both encryption and authentication
  */
 int chacha20_poly1305_init(chacha20_poly1305_context *ctx,
                            const uint8_t *key,
                            const uint8_t *nonce);
 
 /**
  * ChaCha20-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:
  * - ~1-2 GB/s in software (no hardware needed)
  * - Faster than AES-GCM on CPUs without AES-NI
  */
 int chacha20_poly1305_encrypt(chacha20_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);
 
 /**
  * ChaCha20-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 chacha20_poly1305_decrypt(chacha20_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 chacha20_poly1305_cleanup(chacha20_poly1305_context *ctx);
 
 /**
  * Standalone ChaCha20 encryption/decryption
  * (Use ChaCha20-Poly1305 AEAD for authenticated encryption)
  *
  * @param key 256-bit key
  * @param nonce 96-bit nonce
  * @param counter Initial counter (usually 0 or 1)
  * @param input Input data
  * @param output Output buffer (can be same as input)
  * @param len Data length
  * @return 0 on success
  */
 int chacha20_crypt(const uint8_t *key, const uint8_t *nonce,
                    uint32_t counter, const uint8_t *input,
                    uint8_t *output, size_t len);
 
 #ifdef __cplusplus
 }
 #endif
 
 #endif /* CHACHA20_POLY1305_H */