aegis-aead 0.2.1 → 0.2.3

package/README.md

@@ -1,19 +1,22 @@
-# aegis-aead
+# AEGIS for JavaScript
 
 [![npm](https://img.shields.io/npm/v/aegis-aead)](https://www.npmjs.com/package/aegis-aead)
 [![CI](https://github.com/jedisct1/js-aegis-aead/actions/workflows/ci.yml/badge.svg)](https://github.com/jedisct1/js-aegis-aead/actions/workflows/ci.yml)
 
+[View on npm](https://www.npmjs.com/package/aegis-aead)
+
 A compact, zero-dependency JavaScript/TypeScript implementation of [AEGIS](https://datatracker.ietf.org/doc/draft-irtf-cfrg-aegis-aead/), a family of fast, secure authenticated encryption algorithms.
 
 AEGIS provides both encryption with authentication and standalone MAC functionality, with a simple API that makes it hard to misuse.
 
 ## Table of Contents
 
-- [aegis-aead](#aegis-aead)
+- [AEGIS for JavaScript](#aegis-for-javascript)
   - [Table of Contents](#table-of-contents)
   - [Installation](#installation)
   - [Quick Start](#quick-start)
   - [Choosing an Algorithm](#choosing-an-algorithm)
+  - [Performance](#performance)
   - [Usage Examples](#usage-examples)
     - [Combined Mode](#combined-mode)
     - [Detached Mode](#detached-mode)
@@ -27,7 +30,7 @@ AEGIS provides both encryption with authentication and standalone MAC functional
   - [Security Considerations](#security-considerations)
     - [Nonce Safety](#nonce-safety)
     - [Tag Lengths](#tag-lengths)
-    - [Bitsliced Variants](#bitsliced-variants)
+    - [Constant-Time Implementation](#constant-time-implementation)
   - [Compatibility](#compatibility)
   - [Browser Example](#browser-example)
 
@@ -57,24 +60,35 @@ const decrypted = aegis128LDecrypt(sealed, associatedData, key);
 
 ## Choosing an Algorithm
 
-| Algorithm     | Key      | Nonce    | Best For                                 |
-| ------------- | -------- | -------- | ---------------------------------------- |
-| AEGIS-128L    | 16 bytes | 16 bytes | General use, high throughput             |
-| AEGIS-256     | 32 bytes | 32 bytes | Large nonce, unlimited messages          |
-| AEGIS-128X    | 16 bytes | 16 bytes | Interop with native SIMD implementations |
-| AEGIS-256X    | 32 bytes | 32 bytes | Interop + large nonce                    |
-| AEGIS-128L-BS | 16 bytes | 16 bytes | Side-channel protection                  |
-| AEGIS-256-BS  | 32 bytes | 32 bytes | Side-channel + large nonce               |
+| Algorithm  | Key      | Nonce    | Best For                                 |
+| ---------- | -------- | -------- | ---------------------------------------- |
+| AEGIS-128L | 16 bytes | 16 bytes | General use, high throughput             |
+| AEGIS-256  | 32 bytes | 32 bytes | Large nonce, unlimited messages          |
+| AEGIS-128X | 16 bytes | 16 bytes | Interop with native SIMD implementations |
+| AEGIS-256X | 32 bytes | 32 bytes | Interop + large nonce                    |
 
 Recommendations:
 
 - Default choice: AEGIS-128L offers excellent performance with safe random nonces up to 2^48 messages
 - Unlimited messages: AEGIS-256 when you need unlimited random nonces (32-byte nonce eliminates collision risk)
 - Interoperability: AEGIS-128X/256X when exchanging data with native implementations using these variants
-- Hostile environments: Bitsliced variants (-BS) when attackers may observe timing
 
 Note: The X variants are designed for SIMD parallelism in native code. In JavaScript they offer no speed benefit but are provided for interoperability.
 
+## Performance
+
+The numbers below come from `bun run bench` on an Apple M5 Max, with AES-GCM and ChaCha20-Poly1305 supplied by @noble/ciphers for comparison. Throughput is for combined-mode encryption with empty associated data; your mileage will vary with hardware and runtime.
+
+| Algorithm         |    64 B |     1 KB |    16 KB |     1 MB |
+| ----------------- | ------: | -------: | -------: | -------: |
+| AEGIS-128L        | 50 MB/s | 224 MB/s | 310 MB/s | 324 MB/s |
+| ChaCha20-Poly1305 | 36 MB/s | 175 MB/s | 248 MB/s | 256 MB/s |
+| AEGIS-256         | 36 MB/s | 146 MB/s | 198 MB/s | 204 MB/s |
+| AES-128-GCM       | 13 MB/s |  74 MB/s | 150 MB/s | 182 MB/s |
+| AES-256-GCM       | 12 MB/s |  66 MB/s | 122 MB/s | 143 MB/s |
+
+AEGIS-128L is the fastest option at every message size, reaching about 324 MB/s on large buffers — roughly 1.3x ChaCha20-Poly1305 and 1.8x AES-128-GCM.
+
 ## Usage Examples
 
 ### Combined Mode
@@ -153,7 +167,7 @@ const valid = aegis128LMacVerify(data, tag, key);
 
 ## API Overview
 
-All AEGIS variants follow the same API pattern. Replace `aegis128L` with your chosen algorithm (`aegis256`, `aegis128X2`, `aegis128X4`, `aegis256X2`, `aegis256X4`, `aegis128LBs`, `aegis256Bs`).
+All AEGIS variants follow the same API pattern. Replace `aegis128L` with your chosen algorithm (`aegis256`, `aegis128X2`, `aegis128X4`, `aegis256X2`, `aegis256X4`).
 
 ### Functions
 
@@ -219,16 +233,9 @@ All algorithms support 16-byte (128-bit) and 32-byte (256-bit) tags:
 const sealed = aegis128LEncrypt(msg, ad, key, undefined, 32);
 ```
 
-### Bitsliced Variants
-
-The `-BS` variants use a constant-time bitsliced AES implementation that doesn't use lookup tables. This prevents cache-timing attacks at the cost of ~20% performance.
-
-Use bitsliced variants when:
-- Running on shared infrastructure (cloud VMs, containers)
-- Attackers may observe timing information
-- Processing attacker-controlled data with secret keys
+### Constant-Time Implementation
 
-For most applications, standard variants are safe since AEGIS's continuous state mixing makes timing attacks impractical.
+All variants are built on a constant-time bitsliced AES implementation that doesn't use lookup tables, which prevents cache-timing attacks. The bitsliced code processes all state blocks in a single fused round, and it is also the fastest scalar implementation we know of, so the protection comes at no cost. There is no faster table-based fallback to choose, and no reason to want one.
 
 ## Compatibility
 

package/dist/aegis128l.d.ts

@@ -1,25 +1,29 @@
+/**
+ * AEGIS-128L implementation.
+ * Built on the constant-time bitsliced AES core, which processes all 8 state
+ * blocks simultaneously without lookup tables.
+ */
 /**
  * AEGIS-128L cipher state.
- * Uses 8 AES blocks (128 bytes) of internal state and processes 32-byte blocks.
+ * The state is kept in packed bitsliced form between operations so that
+ * pack/unpack does not need to be applied at every round.
  */
 export declare class Aegis128LState {
-    private s0;
-    private s1;
-    private s2;
-    private s3;
-    private s4;
-    private s5;
-    private s6;
-    private s7;
+    private st;
+    private constantInput;
     private tmp0;
     private tmp1;
     private z0;
     private z1;
-    private newS;
-    private tBuf;
     constructor();
+    /**
+     * Returns the 8 state blocks as byte arrays (for testing).
+     */
     get s(): Uint8Array[];
-    set s(states: Uint8Array[]);
+    /**
+     * Sets the 8 state blocks from byte arrays (for testing).
+     */
+    set s(blocks: Uint8Array[]);
     /**
      * Initializes the state with a key and nonce.
      * @param key - 16-byte encryption key
@@ -31,18 +35,21 @@ export declare class Aegis128LState {
      * @param m0 - First 16-byte message block
      * @param m1 - Second 16-byte message block
      */
-    update(m0: ArrayLike<number>, m1: ArrayLike<number>): void;
+    update(m0: Uint8Array, m1: Uint8Array): void;
     /**
      * Absorbs a 32-byte associated data block into the state.
-     * @param ai - 32-byte associated data block
+     * @param ai - Buffer holding the 32-byte associated data block
+     * @param off - Offset of the block within the buffer
      */
-    absorb(ai: Uint8Array): void;
+    absorb(ai: Uint8Array, off?: number): void;
     /**
      * Encrypts a 32-byte plaintext block and writes to output buffer.
-     * @param xi - 32-byte plaintext block
-     * @param out - 32-byte output buffer
+     * @param xi - Buffer holding the 32-byte plaintext block
+     * @param out - Output buffer receiving the 32-byte ciphertext block
+     * @param inOff - Offset of the plaintext block within xi
+     * @param outOff - Offset of the ciphertext block within out
      */
-    encTo(xi: Uint8Array, out: Uint8Array): void;
+    encTo(xi: Uint8Array, out: Uint8Array, inOff?: number, outOff?: number): void;
     /**
      * Encrypts a 32-byte plaintext block.
      * @param xi - 32-byte plaintext block
@@ -51,25 +58,19 @@ export declare class Aegis128LState {
     enc(xi: Uint8Array): Uint8Array;
     /**
      * Decrypts a 32-byte ciphertext block and writes to output buffer.
-     * @param ci - 32-byte ciphertext block
-     * @param out - 32-byte output buffer
+     * @param ci - Buffer holding the 32-byte ciphertext block
+     * @param out - Output buffer receiving the 32-byte plaintext block
+     * @param inOff - Offset of the ciphertext block within ci
+     * @param outOff - Offset of the plaintext block within out
      */
-    decTo(ci: Uint8Array, out: Uint8Array): void;
+    decTo(ci: Uint8Array, out: Uint8Array, inOff?: number, outOff?: number): void;
     /**
      * Decrypts a 32-byte ciphertext block.
      * @param ci - 32-byte ciphertext block
      * @returns 32-byte plaintext block
      */
     dec(ci: Uint8Array): Uint8Array;
-    /**
-     * Encrypts a 32-byte plaintext block in-place.
-     * @param block - 32-byte buffer (plaintext in, ciphertext out)
-     */
     encInPlace(block: Uint8Array): void;
-    /**
-     * Decrypts a 32-byte ciphertext block in-place.
-     * @param block - 32-byte buffer (ciphertext in, plaintext out)
-     */
     decInPlace(block: Uint8Array): void;
     /**
      * Decrypts a partial (final) ciphertext block smaller than 32 bytes.
@@ -79,12 +80,12 @@ export declare class Aegis128LState {
     decPartial(cn: Uint8Array): Uint8Array;
     /**
      * Finalizes encryption/decryption and produces an authentication tag.
-     * @param adLenBits - Associated data length in bits
-     * @param msgLenBits - Message length in bits
+     * @param adLen - Associated data length in bytes
+     * @param msgLen - Message length in bytes
      * @param tagLen - Tag length (16 or 32 bytes)
      * @returns Authentication tag
      */
-    finalize(adLenBits: bigint, msgLenBits: bigint, tagLen?: 16 | 32): Uint8Array;
+    finalize(adLen: number, msgLen: number, tagLen?: 16 | 32): Uint8Array;
 }
 /**
  * Encrypts a message using AEGIS-128L (detached mode).
@@ -186,4 +187,3 @@ export declare function aegis128LCreateKey(): Uint8Array;
  * @throws Error if no cryptographic random source is available
  */
 export declare function aegis128LCreateNonce(): Uint8Array;
-//# sourceMappingURL=aegis128l.d.ts.map