SQLCipher WebAssembly

A production-ready WebAssembly build of SQLCipher with real OpenSSL-based encryption, high-level JavaScript API, and comprehensive test coverage.

Features

Real Encryption: Full SQLCipher encryption using OpenSSL 3.3.2 compiled to WebAssembly
High-Level API: Easy-to-use JavaScript wrapper with automatic memory management
Cross-Platform: Works in Node.js and browsers, compatible with native SQLCipher databases
Comprehensive Tests: 5 test suites covering all functionality including cross-platform compatibility
Nix Flake Environment: Reproducible development environment
Type Definitions: TypeScript definitions included
Benchmarked: Performance benchmarks for critical operations

Security

This build uses real cryptographic primitives from OpenSSL 3.3.2, providing:

AES-256-CBC encryption
PBKDF2-HMAC-SHA1 key derivation (64,000 iterations by default)
HMAC-SHA1 for authentication
Cryptographically secure random number generation

Databases created with this library are fully compatible with native SQLCipher (C++ version).

Prerequisites

Nix with flakes enabled
direnv (optional but recommended)

Enable Nix Flakes

Add to your ~/.config/nix/nix.conf (or /etc/nix/nix.conf):

experimental-features = nix-command flakes

Build Variants

Three build targets are available, all using SQLCipher v4.9.0:

Target	Script(s)	Shell	Emscripten	Crypto	Output
WASM (Node.js/Browser)	`build-wasm.sh`	`nix develop`	Latest (in-tree)	OpenSSL 3.3.2	`dist/` + `target/results/sqlcipher-wasm.zip`
WebGL (Unity 2022.3.22f)	`build-webgl.sh`	`nix develop .#webgl`	3.1.10 (pinned)	OpenSSL 3.3.2	`target/results/sqlcipher-webgl.zip`
Amalgamation (Unity, any emcc)	`build-libtomcrypt.sh` → `build-amalgamation.sh`	`nix develop`	n/a (source bundle)	libtomcrypt 1.18.2	`target/results/sqlcipher-amalgamation.zip`

The WebGL build additionally enables SQLITE_ENABLE_SNAPSHOT and SQLITE_ENABLE_COLUMN_METADATA.

When to use the Amalgamation bundle

The WebGL target above emits a prebuilt libsqlcipher.a that must ABI-match the emcc Unity ships with. That's fine for a single pinned Unity version but breaks across upgrades: a .a built with emcc 3.1.10 (Unity 2022.3.22f) linked into Unity 6000.4 (emcc 3.1.38) traps at runtime with signature_mismatch:time — libc signatures like time_t drifted between emcc versions.

The Amalgamation target sidesteps this entirely: it ships portable C source (one sqlite3.c, one libtomcrypt.c, and a small set of headers) that Unity's own bundled emcc compiles in-tree, so the same bundle works across 2022.3, 6000.x, and future Unity versions with no toolchain pin.

Crypto is libtomcrypt instead of OpenSSL because OpenSSL has no usable source-drop path (Perl-driven Configure, generated opensslconf.h, hundreds of per-file -D flags). libtomcrypt amalgamates cleanly into a single .c once curated to the subset SQLCipher actually calls (AES, SHA1/2, HMAC, CBC/ECB, PBKDF2, PRNG, registration helpers).

Quick Start

WASM (Node.js / Browser)

Interactive:

nix develop
./build-openssl.sh
./build-wasm.sh
npm test

One-liner:

nix develop --command bash -c './build-openssl.sh && ./build-wasm.sh'

WebGL (Unity 2022.3.22f, prebuilt .a)

Interactive:

nix develop .#webgl
./build-openssl.sh
./build-webgl.sh

One-liner:

nix develop .#webgl --command bash -c './build-openssl.sh && ./build-webgl.sh'

Amalgamation (Unity, any emcc — source bundle)

Interactive:

nix develop
./build-libtomcrypt.sh
./build-amalgamation.sh

One-liner:

nix develop --command bash -c './build-libtomcrypt.sh && ./build-amalgamation.sh'

The output target/results/sqlcipher-amalgamation/ is a flat drop-in directory:

sqlite3.c              SQLCipher amalgamation (compile flags baked in at top)
sqlite3.h              SQLCipher public header
libtomcrypt.c          curated libtomcrypt amalgamation
tomcrypt*.h            13 libtomcrypt headers (angled includes rewritten to quoted)
LICENSE_libtomcrypt    libtomcrypt license
README.txt             Unity integration notes

Copy the directory into Assets/Plugins/WebGL/sqlcipher/ — that's it. No plugin importer compile flags, no include paths, no force-includes. Every -D and -I that would normally be needed is either prepended into sqlite3.c itself or obviated by the flat layout (quoted sibling includes resolve via clang's current-file-directory search). The same bundle compiles unchanged on Unity 2022.3 (emcc 3.1.10), Unity 6000.4 (emcc 3.1.38), and whatever emcc the next Unity ships.

Project Structure

.
├── flake.nix                       # Nix flake (default + webgl shells)
├── .envrc                          # direnv configuration
├── lib.sh                          # Shared build utilities (includes patch_amalgamation)
├── build-openssl.sh                # OpenSSL WASM build script
├── build-wasm.sh                   # SQLCipher WASM build (CJS/ESM)
├── build-webgl.sh                  # SQLCipher static lib build (Unity WebGL, emcc-pinned)
├── build-libtomcrypt.sh            # libtomcrypt curated-amalgamation stage (no emcc)
├── build-amalgamation.sh           # SQLCipher + libtomcrypt source bundle (Unity, any emcc)
├── package.json                    # NPM package configuration
├── target/
│   ├── build/                      # Intermediate build artifacts
│   │   ├── openssl-3.3.2/          # OpenSSL source (shared)
│   │   ├── libtomcrypt-1.18.2/     # libtomcrypt source (shared)
│   │   ├── libtomcrypt-amalg/      # Curated libtomcrypt amalgamation output
│   │   ├── amalgamation/           # SQLCipher amalgamation working dir
│   │   └── emcc-<version>/         # Per-emscripten-version builds
│   │       ├── openssl-wasm/       # Compiled OpenSSL
│   │       ├── sqlcipher-wasm/     # WASM build working dir
│   │       └── sqlcipher-webgl/    # WebGL build working dir
│   └── results/                    # Final build outputs
│       ├── sqlcipher-wasm/         # WASM artifacts (unpacked)
│       ├── sqlcipher-wasm.zip      # WASM archive
│       ├── sqlcipher-webgl/        # WebGL artifacts (unpacked)
│       │   ├── libsqlcipher.a
│       │   └── openssl/
│       │       ├── libcrypto.a
│       │       └── libssl.a
│       ├── sqlcipher-webgl.zip     # WebGL archive
│       ├── sqlcipher-amalgamation/ # Source bundle (unpacked)
│       └── sqlcipher-amalgamation.zip # Source bundle archive
├── dist/                           # NPM package output
│   ├── sqlcipher.cjs               # CommonJS module (Node.js)
│   ├── sqlcipher.mjs               # ES module (browser)
│   └── sqlcipher.wasm              # WebAssembly binary
├── lib/
│   └── sqlite-api.cjs              # High-level JavaScript API
├── test/
│   ├── run-all-tests.cjs           # Test suite runner
│   ├── test.cjs                    # Core functionality tests
│   ├── e2e-test.cjs                # End-to-end tests
│   ├── file-db-test.cjs            # File persistence tests
│   ├── encryption-test.cjs         # Encryption tests
│   └── cross-platform-db-test.cjs  # C++ <-> WASM compatibility (generated)
├── bench/
│   └── benchmark.cjs               # Performance benchmarks
├── examples/
│   └── example.cjs                 # Usage examples
├── tools/
│   └── prepare-cross-platform-test.sh
└── docs/
    └── archive/

Build Process

All build scripts source lib.sh which auto-detects the emscripten version and sets up versioned build/cache directories. This allows the default and webgl shells to coexist without conflicts.

1. OpenSSL Build (`build-openssl.sh`)

Downloads and compiles OpenSSL 3.3.2 to WebAssembly:

Configured for WASM target (linux-generic32)
Optimized build (-O3 -flto)
Disabled features: ASM, threads, engines, hardware acceleration
Static library output to target/build/emcc-<version>/openssl-wasm/
OpenSSL source tarball is shared across emscripten versions

2. SQLCipher WASM Build (`build-wasm.sh`)

Compiles SQLCipher with OpenSSL into CJS/ESM modules:

Copies SQLCipher v4.9.0 source from Nix store
Configures and creates amalgamation (sqlite3.c)
Patches amalgamation to use OpenSSL crypto provider
Compiles and links with OpenSSL static libraries
Outputs to dist/ (for npm) and target/results/sqlcipher-wasm/
Creates target/results/sqlcipher-wasm.zip

3. SQLCipher WebGL Build (`build-webgl.sh`)

Compiles SQLCipher into a static library for Unity 2022.3.22f WebGL:

Same amalgamation process as WASM build
Compiles with emscripten 3.1.10 (ABI-compatible with Unity's bundled emscripten)
Outputs libsqlcipher.a + OpenSSL libs to target/results/sqlcipher-webgl/
Creates target/results/sqlcipher-webgl.zip

4. libtomcrypt Amalgamation Stage (`build-libtomcrypt.sh`)

Prepares a curated libtomcrypt amalgamation consumed by build-amalgamation.sh. This is a source-transform stage — no emcc is invoked.

Downloads libtomcrypt 1.18.2 tarball (shared across runs)
Enumerates the subset SQLCipher calls: AES, SHA1/2 family, HMAC, CBC/ECB modes, PBKDF2 (PKCS#5 alg2), PRNGs, registration/argchk helpers
Inlines aes_tab.c into aes.c so the amalgamation has no side-file dependency
Concatenates the subset into target/build/libtomcrypt-amalg/libtomcrypt.c
Copies the 13 upstream headers to target/build/libtomcrypt-amalg/headers/
Smoke-tests the result compiles cleanly with host cc

Unrelated algorithms (Blowfish, Camellia, Khazad, MDx, RIPEMD, etc.) are intentionally omitted — they collide on static symbols (T-tables, per-algo F/G macros) when amalgamated, and SQLCipher never touches them.

5. Unity Source Bundle (`build-amalgamation.sh`)

Assembles the SQLCipher + libtomcrypt source bundle consumable by Unity's own emcc, so the same output works across Unity versions without ABI pinning.

Asserts build-libtomcrypt.sh has been run (its output is in target/build/libtomcrypt-amalg/)
Builds the SQLCipher amalgamation (sqlite3.c + sqlite3.h) via the standard ./configure && make sqlite3.c flow — still no emcc
Patches sqlite3.c to activate the libtomcrypt provider and disable OpenSSL/NSS/CC
Copies the prebuilt libtomcrypt.c and headers alongside
Prepends the SQLCipher/SQLite #define block directly to the top of the bundled sqlite3.c so no -D flags are ever needed at compile time
Rewrites #include <tomcrypt.h> (in sqlite3.c's crypto_libtomcrypt section) to "tomcrypt.h" so it resolves from the plugin's own directory without an -I path
Flattens all libtomcrypt headers alongside libtomcrypt.c in the bundle root so quote-include lookups succeed out of the box
Creates target/results/sqlcipher-amalgamation.zip

Compilation Flags (shared by WASM and WebGL builds):

SQLITE_HAS_CODEC - Enable encryption
SQLCIPHER_CRYPTO_OPENSSL - Use OpenSSL crypto provider
SQLITE_TEMP_STORE=2 - Use memory for temporary storage
SQLITE_THREADSAFE=1 - Thread-safe (required by SQLCipher v4.9.0)
SQLITE_ENABLE_FTS5 - Full-text search
SQLITE_ENABLE_RTREE - Spatial indexing
SQLITE_ENABLE_JSON1 - JSON support

WebGL build adds:

SQLITE_ENABLE_SNAPSHOT - Database snapshot support
SQLITE_ENABLE_COLUMN_METADATA - Column metadata API

Amalgamation bundle substitutes the OpenSSL provider with libtomcrypt:

SQLCIPHER_CRYPTO_LIBTOMCRYPT replaces SQLCIPHER_CRYPTO_OPENSSL
LTC_SOURCE enables libtomcrypt internal symbols
every flag is prepended directly into sqlite3.c / libtomcrypt.c at bundle assembly time — no external -D or force-include header needed

Usage

Basic Example

const { SQLiteAPI } = require('./lib/sqlite-api.cjs');
const initSqlcipher = require('./dist/sqlcipher.js');

async function main() {
    // Initialize the WASM module
    const Module = await initSqlcipher();
    const sqlite = new SQLiteAPI(Module);

    // Create an encrypted database
    const db = sqlite.open('/mydb.db', 'my-secret-password');

    // Create a table
    db.exec('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)');

    // Insert data
    db.exec(
        'INSERT INTO users (name, email) VALUES (?, ?)',
        ['Alice', 'alice@example.com']
    );

    // Query data
    const users = db.query('SELECT * FROM users WHERE name = ?', ['Alice']);
    console.log(users);
    // => [{ id: 1, name: 'Alice', email: 'alice@example.com' }]

    // Close database
    db.close();
}

main();

Encryption Examples

// Open with password
const db = sqlite.open('/encrypted.db', 'password123');

// Change password (re-key)
db.exec("PRAGMA rekey = 'new-password'");

// Multiple databases with different passwords
const db1 = sqlite.open('/db1.db', 'password1');
const db2 = sqlite.open('/db2.db', 'password2');

// Check encryption worked
db1.exec('SELECT count(*) FROM sqlite_master'); // OK
db2.exec('SELECT count(*) FROM sqlite_master'); // OK

Browser Usage

<script type="module">
  import initSqlcipher from './dist/sqlcipher.js';
  import { SQLiteAPI } from './lib/sqlite-api.js';

  const Module = await initSqlcipher();
  const sqlite = new SQLiteAPI(Module);

  const db = sqlite.open('/mydb.db', 'secret');
  console.log('SQLCipher ready!');
</script>

API Reference

`SQLiteAPI`

High-level JavaScript API for SQLCipher.

`open(path, password?)`

Open or create a database.

path - Database file path (e.g., /mydb.db)
password - Encryption password (optional for unencrypted databases)
Returns: Database instance

`Database` Methods

`exec(sql, params?)`

Execute SQL statement.

sql - SQL statement
params - Optional array of parameters for ? placeholders
Returns: void

`query(sql, params?)`

Execute query and return results.

sql - SQL query
params - Optional array of parameters
Returns: Array of result objects

`close()`

Close the database connection.

`getChanges()`

Get number of rows changed by last statement.

Returns: number

Test Suite

The test suite includes 5 comprehensive test suites:

1. Unit Tests (`test/test.cjs`)

Module loading and initialization
Basic SQL operations
Memory management
API correctness

2. End-to-End Tests (`test/e2e-test.cjs`)

Complete workflows
Multi-step operations
Error handling
Edge cases

3. File Database Tests (`test/file-db-test.cjs`)

File persistence
VFS (Virtual File System)
Database reopening
File operations

4. Encryption Tests (`test/encryption-test.cjs`)

PRAGMA key interface
Password verification
Multiple databases with different passwords
Database re-keying
Wrong password handling
API key vs PRAGMA key equivalence

5. Cross-Platform Tests (`test/cross-platform-db-test.cjs`)

C++ (native SQLCipher) -> WASM compatibility
Database created with native SQLCipher, read by WASM
Binary compatibility verification
Real-world migration scenarios

Run all tests:

npm test

Run tests in watch mode:

npm run test:watch

Benchmarks

Run performance benchmarks:

npm run bench

Benchmarks measure:

Module initialization time
Memory allocation performance
Database operations (INSERT, SELECT, UPDATE, DELETE)
Query performance
Encryption overhead
Memory usage patterns

Cross-Platform Compatibility

Databases created with this WASM build are 100% compatible with native SQLCipher.

Testing Cross-Platform Compatibility

Generate and run the cross-platform test:

./tools/prepare-cross-platform-test.sh
node test/cross-platform-db-test.cjs

This creates a database with native SQLCipher (C++), encodes it, and verifies WASM can read it.

Migrating from Native SQLCipher

Just copy your .db file and open it with the same password:

const db = sqlite.open('/path/to/existing.db', 'same-password');
const data = db.query('SELECT * FROM your_table');

Using WASM Databases in Native Apps

The reverse also works - databases created in WASM can be used in native applications.

Development

Rebuilding

Clean rebuild (WASM):

rm -rf target/ dist/
./build-openssl.sh && ./build-wasm.sh

Clean rebuild (WebGL):

rm -rf target/
./build-openssl.sh && ./build-webgl.sh

Full clean:

rm -rf target/ dist/

Adding Tests

Add to appropriate test file in test/:

test('Your test name', () => {
    const db = sqlite.open('/test.db', 'password');
    db.exec('CREATE TABLE test (id INTEGER)');
    const result = db.query('SELECT * FROM test');
    assert.strictEqual(result.length, 0);
    db.close();
});

Tests are automatically picked up by npm test.

CI/CD

GitHub Actions workflows:

CI/CD (.github/workflows/ci.yml) - Build, test, and publish on releases
PR Checks (.github/workflows/pr-check.yml) - Quick validation on pull requests

CI pipeline:

Build OpenSSL + SQLCipher WASM (nix develop)
Build OpenSSL + SQLCipher WebGL (nix develop .#webgl)
Run tests and benchmarks
Upload sqlcipher-wasm.zip and sqlcipher-webgl.zip as artifacts
Publish to NPM and create GitHub Release on tags

Troubleshooting

Build fails with "SQLCIPHER_SRC not set"

Enter the Nix environment:

nix develop

Build fails with OpenSSL errors

Rebuild OpenSSL:

rm -rf target/build/
./build-openssl.sh

Tests fail with "Cannot find module"

Build first:

./build-openssl.sh && ./build-wasm.sh

"file is encrypted or is not a database"

Wrong password or corrupted database. Verify password:

try {
    const db = sqlite.open('/test.db', 'password');
    db.query('SELECT * FROM sqlite_master'); // Will fail if wrong password
} catch (err) {
    console.log('Wrong password or corrupted database');
}

Out of memory during build

Increase Node.js memory:

export NODE_OPTIONS="--max-old-space-size=4096"
./build-wasm.sh

Cross-platform test fails

Make sure native SQLCipher is available (provided by Nix environment):

nix develop --command bash -c "which sqlcipher"

Performance Tips

Batch operations - Use transactions for multiple inserts
Prepare statements - Reuse prepared statements for repeated queries
Appropriate memory settings - Adjust PRAGMA cache_size
Index wisely - Create indexes for frequently queried columns
Use the benchmarks - Profile before optimizing

Example batch insert:

db.exec('BEGIN TRANSACTION');
for (let i = 0; i < 1000; i++) {
    db.exec('INSERT INTO users (name) VALUES (?)', [`User ${i}`]);
}
db.exec('COMMIT');

Contributing

Contributions welcome! Areas for improvement:

Browser-based test runner
More comprehensive benchmarks
IndexedDB persistence examples
Worker thread examples
React/Vue/Svelte integration examples
Performance optimization guides

Publishing

The package is configured for NPM publishing:

npm version patch  # or minor, major
git push --tags

Create a GitHub release to trigger automatic publishing to:

NPM registry
GitHub Packages

Environment Variables

In the Nix environment:

SQLCIPHER_SRC - Path to SQLCipher source (set by flake.nix)
EM_CACHE - Emscripten cache directory (set by lib.sh per emcc version)
NODE_PATH - Node.js module search path

Resources

License

MIT License - See LICENSE file for details

Dependencies:

SQLCipher - BSD-style license
SQLite - Public domain
OpenSSL - Apache License 2.0
Emscripten - MIT/NCSA License

Acknowledgments

SQLCipher team for the encrypted SQLite fork
OpenSSL team for the cryptographic library
Emscripten team for the WASM toolchain
SQLite team for the amazing database engine
Nix community for reproducible builds

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

SQLCipher WebAssembly

Features

Security

Prerequisites

Enable Nix Flakes

Build Variants

When to use the Amalgamation bundle

Quick Start

WASM (Node.js / Browser)

WebGL (Unity 2022.3.22f, prebuilt .a)

Amalgamation (Unity, any emcc — source bundle)

Project Structure

Build Process

1. OpenSSL Build (build-openssl.sh)

2. SQLCipher WASM Build (build-wasm.sh)

3. SQLCipher WebGL Build (build-webgl.sh)

4. libtomcrypt Amalgamation Stage (build-libtomcrypt.sh)

5. Unity Source Bundle (build-amalgamation.sh)

Usage

Basic Example

Encryption Examples

Browser Usage

API Reference

SQLiteAPI

open(path, password?)

Database Methods

exec(sql, params?)

query(sql, params?)

close()

getChanges()

Test Suite

1. Unit Tests (test/test.cjs)

2. End-to-End Tests (test/e2e-test.cjs)

3. File Database Tests (test/file-db-test.cjs)

4. Encryption Tests (test/encryption-test.cjs)

5. Cross-Platform Tests (test/cross-platform-db-test.cjs)

Benchmarks

Cross-Platform Compatibility

Testing Cross-Platform Compatibility

Migrating from Native SQLCipher

Using WASM Databases in Native Apps

Development

Rebuilding

Adding Tests

CI/CD

Troubleshooting

Build fails with "SQLCIPHER_SRC not set"

Build fails with OpenSSL errors

Tests fail with "Cannot find module"

"file is encrypted or is not a database"

Out of memory during build

Cross-platform test fails

Performance Tips

Contributing

Publishing

Environment Variables

Resources

License

Acknowledgments

1. OpenSSL Build (`build-openssl.sh`)

2. SQLCipher WASM Build (`build-wasm.sh`)

3. SQLCipher WebGL Build (`build-webgl.sh`)

4. libtomcrypt Amalgamation Stage (`build-libtomcrypt.sh`)

5. Unity Source Bundle (`build-amalgamation.sh`)

`SQLiteAPI`

`open(path, password?)`

`Database` Methods

`exec(sql, params?)`

`query(sql, params?)`

`close()`

`getChanges()`

1. Unit Tests (`test/test.cjs`)

2. End-to-End Tests (`test/e2e-test.cjs`)

3. File Database Tests (`test/file-db-test.cjs`)

4. Encryption Tests (`test/encryption-test.cjs`)

5. Cross-Platform Tests (`test/cross-platform-db-test.cjs`)