Auditing WebBuf: How We Verified 13 Cryptographic Packages

WebBuf is Identellica’s cryptographic library for TypeScript and JavaScript. It provides everything needed for binary data manipulation, hashing, elliptic curve operations, and authenticated encryption—all with Rust/WASM-optimized performance.

Before using any cryptographic library in production, you need to verify it works correctly. We just completed a comprehensive audit of all 13 WebBuf packages. The result: 598 tests passed, 2 bugs found and fixed.

The full audit report is available at github.com/identellica/webbuf.

Why Audit a Cryptographic Library?

Cryptographic bugs are uniquely dangerous. They don’t crash your application or throw obvious errors. They silently compromise security while everything appears to work normally.

Consider a subtle bug in an overflow check. Your code runs fine in testing. It handles normal inputs correctly. But an attacker who understands the bug can craft inputs that bypass your security entirely. You won’t know until it’s too late.

This is why cryptographic code requires verification against known standards. It’s not enough that the code “seems to work.” It must produce exactly the right output for every input, match official test vectors byte-for-byte, and interoperate correctly with other trusted implementations.

Our Audit Methodology

We used three complementary approaches to verify each package:

Official Test Vectors. Standards bodies like NIST publish test vectors—known input/output pairs that any correct implementation must match. We tested against NIST FIPS 180-4 for SHA-256, NIST SP 800-38A for AES-CBC, RFC 4231 for HMAC-SHA256, and official vectors from the BLAKE3 and RIPEMD-160 specifications.

Cross-Implementation Verification. We compared WebBuf’s output against other trusted implementations. The Web Crypto API is built into every browser and has been extensively audited. The @noble/secp256k1 library is widely used and well-reviewed. When WebBuf produces identical output to these implementations, we have strong confidence in correctness.

Property-Based Testing. Beyond specific test vectors, we verified security properties. Does modifying a single byte of ciphertext cause authentication to fail? Does using the wrong key fail cleanly? Do edge cases like empty inputs and maximum-size values work correctly? These tests catch bugs that standard test vectors might miss.

This audit was AI-assisted, consistent with Identellica’s AI-first development approach. The combination of AI-generated test cases and human review proved effective at achieving comprehensive coverage.

What We Tested

The 13 packages fall into four categories:

Core Utilities (4 packages, 262 tests)

• @webbuf/webbuf - Buffer type with hex/base64 encoding
• @webbuf/fixedbuf - Fixed-size buffer wrapper for type safety
• @webbuf/numbers - Fixed-size integers (U8 through U256, big/little endian)
• @webbuf/rw - Binary reader/writer for serialization

These packages handle the foundational data types. We verified encoding correctness against Node.js Buffer, tested boundary conditions, and confirmed round-trip serialization works for all types.

Hash Functions (3 packages, 131 tests)

• @webbuf/blake3 - BLAKE3 hash and keyed MAC
• @webbuf/sha256 - SHA-256 hash and HMAC-SHA256
• @webbuf/ripemd160 - RIPEMD-160 hash

Each hash function was tested against official specification vectors. SHA-256 was verified against NIST FIPS 180-4 vectors including the famous “one million letter a” test. BLAKE3 was tested against all 18 official test vectors for both hash and keyed MAC modes. RIPEMD-160 was verified against the original paper’s test vectors.

Elliptic Curves (1 package, 35 tests)

• @webbuf/secp256k1 - ECDSA signatures and ECDH key exchange

The secp256k1 package was cross-verified against @noble/secp256k1 for public key generation, signature creation/verification, and ECDH shared secret computation. We tested with known private key → public key pairs and verified that invalid keys and signatures are correctly rejected.

Encryption (5 packages, 170 tests)

• @webbuf/aescbc - AES-CBC encryption (raw, no authentication)
• @webbuf/acb3 - AES-CBC + BLAKE3 MAC (authenticated encryption)
• @webbuf/acb3dh - ACB3 with ECDH key exchange
• @webbuf/acs2 - AES-CBC + SHA-256 HMAC (authenticated encryption)
• @webbuf/acs2dh - ACS2 with ECDH key exchange

AES-CBC was tested against NIST SP 800-38A vectors for 128, 192, and 256-bit keys. We verified bidirectional Web Crypto interoperability—WebBuf can decrypt what Web Crypto encrypts, and vice versa.

The authenticated encryption packages (acb3, acs2) use the Encrypt-then-MAC construction. We verified that the MAC is computed over IV || ciphertext, that any single-byte modification causes authentication failure, and that the construction matches manual assembly using the underlying primitives.

Bugs We Found

The audit discovered two bugs, both now fixed.

Bug #1: fixedbuf clone() created a shared view

The clone() method was supposed to create an independent copy of a buffer. Instead, it created a view that shared the same underlying memory. Modifying the “clone” would modify the original.

// Before the fix - this was broken
const original = FixedBuf.fromRandom(32);
const cloned = original.clone();
cloned.buf[0] = 0xff; // This modified original too!

This bug could cause subtle data corruption in any application that assumed cloned buffers were independent. The fix was a one-line change in fixedbuf.ts.

Bug #2: U32 overflow check used wrong constant

The U32BE.fromBn() and U32LE.fromBn() methods had incorrect overflow checks. They were checking against 0xffffffffffffffffn (the maximum U64 value) instead of 0xffffffffn (the maximum U32 value).

This meant values larger than 2^32-1 but smaller than 2^64-1 would be silently accepted and truncated. The fix was correcting two constants in numbers/src/index.ts.

Both bugs were found because the audit tests specifically checked boundary conditions and independence of cloned data. This is exactly why audits matter— these bugs passed normal usage testing but failed under rigorous verification.

Key Findings

All cryptographic primitives are correctly implemented. Every official test vector passes. The implementations match their specifications exactly.

Web Crypto interoperability is confirmed. For AES-CBC, SHA-256, and HMAC-SHA256, WebBuf produces byte-for-byte identical output to the browser’s native Web Crypto API. This provides strong validation since Web Crypto is one of the most widely audited cryptographic implementations.

Cross-implementation verification passes. The secp256k1 package produces identical results to @noble/secp256k1 for all operations tested, including edge cases like the minimum valid private key.

Encrypt-then-MAC construction is correct. Both acb3 and acs2 properly implement the Encrypt-then-MAC pattern, computing the MAC over IV || ciphertext as required for security. Tamper detection works correctly—any modification to MAC, IV, or ciphertext causes authentication failure.

Conclusion

WebBuf has passed a comprehensive security audit. All 13 packages are verified against official standards, cross-checked against trusted implementations, and tested for correct security properties.

The two bugs we found demonstrate the value of rigorous auditing. Both bugs would have been difficult to detect through normal testing but were immediately caught by verification against expected behavior.

All 598 audit tests are preserved in the repository and run as part of CI/CD. Any future changes that break correctness will be caught immediately.

WebBuf is open source and available on GitHub and npm:

• GitHub: github.com/identellica/webbuf
• npm: npm install @webbuf/webbuf
• Full Audit Report: audits/2024-12-audit.md

If you find any issues or want to contribute additional test coverage, please open an issue or pull request on GitHub.

---

WebBuf is developed by Identellica and released under the MIT license.