sqlite3: add sqlcipher support

Port SQLCipher support from mattn/go-sqlite3 PR mattn#1109 by Jonathan Giannuzzi
onto current upstream master.

Embed SQLCipher 4.16.0 and keep the fork module path as github.com/mattn/go-sqlite3.
Downstream imports can stay unchanged behind a replace directive.

Update the SQLCipher upgrade helper to build modern upstream releases without the removed
userauth extension. The Homebrew path change and merge commit from the PR are intentionally
omitted.

Crypto provider:

Use CommonCrypto on Darwin and LibTomCrypt on non-Darwin platforms so embedded
SQLCipher builds no longer depend on OpenSSL/libcrypto at runtime,
making static compilation work, avoiding the need to ship libcrypto or
openssl shared libs / DLL files per platform.

Add generated vendorable LibTomCrypt bindings from the submodule, document the
provider split, and wire CI and upgrade tooling for the provider setup.

Author: benma

.github/workflows/go.yaml

@@ -36,6 +36,8 @@ jobs:
           echo "$(go env GOPATH)/bin" >> "$GITHUB_PATH"
 
       - uses: actions/checkout@v6
+        with:
+          submodules: true
 
       - name: 'Tags: default'
         run: go-acc . -- -race -v -tags ""
@@ -49,6 +51,9 @@ jobs:
       - name: 'Tags: vacuum'
         run: go-acc . -- -race -v -tags "sqlite_vacuum_full"
 
+      - name: 'Tags: sqlcipher'
+        run: go-acc . -- -race -v -tags "sqlcipher"
+
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v5
         with:
@@ -87,6 +92,8 @@ jobs:
         shell: msys2 {0}
 
       - uses: actions/checkout@v6
+        with:
+          submodules: true
 
       - name: 'Tags: default'
         run: go build -race -v -tags ""
@@ -106,6 +113,10 @@ jobs:
         run: go build -race -v -tags "sqlite_vacuum_full"
         shell: msys2 {0}
 
+      - name: 'Tags: sqlcipher'
+        run: go build -race -v -tags "sqlcipher"
+        shell: msys2 {0}
+
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v5
         with:

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "internal/libtomcrypt/src"]
+	path = internal/libtomcrypt/src
+	url = https://github.com/sqlcipher/libtomcrypt.git

LICENSE.LIBTOMCRYPT

@@ -0,0 +1,29 @@
+LibTomCrypt is licensed under DUAL licensing terms.
+
+Choose and use the license of your needs.
+
+[LICENSE #1]
+
+LibTomCrypt is public domain.  As should all quality software be.
+
+Tom St Denis
+
+[/LICENSE #1]
+
+[LICENSE #2]
+
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+                    Version 2, December 2004
+
+ Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>
+
+ Everyone is permitted to copy and distribute verbatim or modified
+ copies of this license document, and changing it is allowed as long
+ as the name is changed.
+
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. You just DO WHAT THE FUCK YOU WANT TO. 
+
+[/LICENSE #2]

LICENSE.SQLCIPHER

@@ -0,0 +1,27 @@
+SQLCipher
+http://zetetic.net
+
+Copyright (c) 2008-2024, ZETETIC LLC
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of the ZETETIC LLC nor the
+      names of its contributors may be used to endorse or promote products
+      derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY ZETETIC LLC ''AS IS'' AND ANY
+EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL ZETETIC LLC BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -1,3 +1,50 @@
+go-sqlite3-sqlcipher fork
+=========================
+
+This repository is a fork of [mattn/go-sqlite3](https://github.com/mattn/go-sqlite3)
+that adds SQLCipher support. The Go module path remains
+`github.com/mattn/go-sqlite3` so existing imports continue to work with a
+`replace` directive.
+
+Replace the module with this fork:
+
+```go
+require github.com/mattn/go-sqlite3 v1.14.47
+
+replace github.com/mattn/go-sqlite3 => github.com/BitBoxSwiss/go-sqlite3-sqlcipher <version>
+```
+
+Build with the `sqlcipher` tag to use the embedded SQLCipher amalgamation:
+
+```sh
+go build -tags sqlcipher ./...
+```
+
+The embedded `sqlcipher` tag uses these crypto providers:
+
+| Platform | Crypto provider | External runtime crypto dependency |
+| --- | --- | --- |
+| iOS/macOS | CommonCrypto via Apple frameworks | No |
+| Android | LibTomCrypt from the submodule source | No |
+| Linux | LibTomCrypt from the submodule source | No |
+| Windows | LibTomCrypt from the submodule source, with `advapi32` for RNG seeding | No OpenSSL DLL |
+| `libsqlcipher` tag | Determined by the linked external `libsqlcipher` | Depends on that library |
+
+Initialize the LibTomCrypt submodule when working on the fork:
+
+```sh
+git submodule update --init
+```
+
+The fork checks in generated LibTomCrypt binding files under
+`internal/libtomcrypt` so downstream `go mod vendor` users can build with
+`-mod=vendor` without initializing this submodule.
+
+This fork is based on the original work by Yasuhiro Matsumoto and the
+`mattn/go-sqlite3` contributors. SQLCipher support is based on
+[PR #1109](https://github.com/mattn/go-sqlite3/pull/1109) by
+[jgiannuzzi](https://github.com/jgiannuzzi).
+
 go-sqlite3
 ==========
 
@@ -41,9 +88,12 @@ This package follows the official [Golang Release Policy](https://golang.org/doc
   - [macOS](#mac-osx)
   - [Windows](#windows)
   - [Errors](#errors)
-- [User Authentication](#user-authentication)
+- [Encryption](#encryption)
   - [Compile](#compile)
   - [Usage](#usage-1)
+- [User Authentication](#user-authentication)
+  - [Compile](#compile-1)
+  - [Usage](#usage-2)
     - [Create protected database](#create-protected-database)
     - [Password Encoding](#password-encoding)
       - [Available Encoders](#available-encoders)
@@ -106,11 +156,17 @@ Boolean values can be one of:
 | Auto Vacuum | `_auto_vacuum` \| `_vacuum` | <ul><li>`0` \| `none`</li><li>`1` \| `full`</li><li>`2` \| `incremental`</li></ul> | For more information see [PRAGMA auto_vacuum](https://www.sqlite.org/pragma.html#pragma_auto_vacuum) |
 | Busy Timeout | `_busy_timeout` \| `_timeout` | `int` | Specify value for sqlite3_busy_timeout. For more information see [PRAGMA busy_timeout](https://www.sqlite.org/pragma.html#pragma_busy_timeout) |
 | Case Sensitive LIKE | `_case_sensitive_like` \| `_cslike` | `boolean` | For more information see [PRAGMA case_sensitive_like](https://www.sqlite.org/pragma.html#pragma_case_sensitive_like) |
+| Cipher Compatibility | `_cipher_compatibility` | `int` | For more information see [PRAGMA cipher_compatibility](https://www.zetetic.net/sqlcipher/sqlcipher-api/#cipher_compatibility) |
+| Cipher Migrate | `_cipher_migrate` | - | For more information see [PRAGMA cipher_migrate](https://www.zetetic.net/sqlcipher/sqlcipher-api/#cipher_migrate) |
+| Cipher Page Size | `_cipher_page_size` | `int` | For more information see [PRAGMA cipher_page_size](https://www.zetetic.net/sqlcipher/sqlcipher-api/#cipher_page_size) |
+| Cipher Plaintext Header Size | `_cipher_plaintext_header_size` | `int` | For more information see [PRAGMA cipher_plaintext_header_size](https://www.zetetic.net/sqlcipher/sqlcipher-api/#cipher_plaintext_header_size) |
+| Cipher Use HMAC | `_cipher_use_hmac` | `int` | For more information see [PRAGMA cipher_use_hmac](https://www.zetetic.net/sqlcipher/sqlcipher-api/#cipher_use_hmac) |
 | Defer Foreign Keys | `_defer_foreign_keys` \| `_defer_fk` | `boolean` | For more information see [PRAGMA defer_foreign_keys](https://www.sqlite.org/pragma.html#pragma_defer_foreign_keys) |
 | Foreign Keys | `_foreign_keys` \| `_fk` | `boolean` | For more information see [PRAGMA foreign_keys](https://www.sqlite.org/pragma.html#pragma_foreign_keys) |
 | Ignore CHECK Constraints | `_ignore_check_constraints` | `boolean` | For more information see [PRAGMA ignore_check_constraints](https://www.sqlite.org/pragma.html#pragma_ignore_check_constraints) |
 | Immutable | `immutable` | `boolean` | For more information see [Immutable](https://www.sqlite.org/c3ref/open.html) |
 | Journal Mode | `_journal_mode` \| `_journal` | <ul><li>DELETE</li><li>TRUNCATE</li><li>PERSIST</li><li>MEMORY</li><li>WAL</li><li>OFF</li></ul> | For more information see [PRAGMA journal_mode](https://www.sqlite.org/pragma.html#pragma_journal_mode) |
+| Encryption Key | `_key` | `string` | Sets the database encryption key to use with [SQLCipher](https://github.com/sqlcipher/sqlcipher). For more information see [PRAGMA key](https://www.zetetic.net/sqlcipher/sqlcipher-api/#PRAGMA_key)
 | Locking Mode | `_locking_mode` \| `_locking` | <ul><li>NORMAL</li><li>EXCLUSIVE</li></ul> | For more information see [PRAGMA locking_mode](https://www.sqlite.org/pragma.html#pragma_locking_mode) |
 | Mode | `mode` | <ul><li>ro</li><li>rw</li><li>rwc</li><li>memory</li></ul> | Access Mode of the database. For more information see [SQLite Open](https://www.sqlite.org/c3ref/open.html) |
 | Mutex Locking | `_mutex` | <ul><li>no</li><li>full</li></ul> | Specify mutex mode. |
@@ -350,6 +406,18 @@ For example the TDM-GCC Toolchain can be found [here](https://jmeubank.github.io
     go install github.com/mattn/go-sqlite3
     ```
 
+# Encryption
+
+## Compile
+
+To use the database encryption feature, the package has to be compiled with the tags `sqlcipher` (to use the built-in implementation) or `libsqlcipher` (to link directly to libsqlcipher).
+
+The built-in implementation requires OpenSSL to be installed (`libssl-dev` or `openssl-devel` on Linux). It is not required on macOS, where CommonCrypto gets used and is part of the system.
+
+### Usage
+
+Pass your encryption key via the `_key` argument in the connection string. See the [SQLCipher documentation](https://www.zetetic.net/sqlcipher/sqlcipher-api/#PRAGMA_key) for more details.
+
 # User Authentication
 
 ***This is deprecated***
@@ -594,6 +662,16 @@ The -binding suffix was added to avoid build failures under gccgo.
 
 In this repository, those files are an amalgamation of code that was copied from SQLite3. The license of that code is the same as the license of SQLite3.
 
+sqlcipher-binding.c and sqlcipher-binding.h are an amalgamation of code that
+was copied from [SQLCipher](https://github.com/sqlcipher/sqlcipher). See
+[LICENSE.SQLCIPHER](./LICENSE.SQLCIPHER) for the SQLCipher copyright notice
+and license terms.
+
+internal/libtomcrypt contains generated files copied from
+[LibTomCrypt](https://github.com/sqlcipher/libtomcrypt). See
+[LICENSE.LIBTOMCRYPT](./LICENSE.LIBTOMCRYPT) for the LibTomCrypt license
+terms.
+
 # Author
 
 Yasuhiro Matsumoto (a.k.a mattn)

backup.go

@@ -6,10 +6,14 @@
 package sqlite3
 
 /*
-#ifndef USE_LIBSQLITE3
-#include "sqlite3-binding.h"
-#else
+#if defined(USE_LIBSQLITE3)
 #include <sqlite3.h>
+#elif defined(USE_LIBSQLCIPHER)
+#include <sqlcipher/sqlite3.h>
+#elif defined(USE_SQLCIPHER)
+#include "sqlcipher-binding.h"
+#else
+#include "sqlite3-binding.h"
 #endif
 #include <stdlib.h>
 */

callback.go

@@ -11,10 +11,14 @@ package sqlite3
 // code for SQLite custom functions is in here.
 
 /*
-#ifndef USE_LIBSQLITE3
-#include "sqlite3-binding.h"
-#else
+#if defined(USE_LIBSQLITE3)
 #include <sqlite3.h>
+#elif defined(USE_LIBSQLCIPHER)
+#include <sqlcipher/sqlite3.h>
+#elif defined(USE_SQLCIPHER)
+#include "sqlcipher-binding.h"
+#else
+#include "sqlite3-binding.h"
 #endif
 #include <stdlib.h>
 

error.go

@@ -6,10 +6,14 @@
 package sqlite3
 
 /*
-#ifndef USE_LIBSQLITE3
-#include "sqlite3-binding.h"
-#else
+#if defined(USE_LIBSQLITE3)
 #include <sqlite3.h>
+#elif defined(USE_LIBSQLCIPHER)
+#include <sqlcipher/sqlite3.h>
+#elif defined(USE_SQLCIPHER)
+#include "sqlcipher-binding.h"
+#else
+#include "sqlite3-binding.h"
 #endif
 */
 import "C"

internal/libtomcrypt/libtomcrypt.go

@@ -0,0 +1,16 @@
+// Copyright (C) 2026 BitBoxSwiss.
+//
+// Use of this source code is governed by an MIT-style
+// license that can be found in the LICENSE file.
+
+//go:build sqlcipher && !libsqlcipher && !darwin
+// +build sqlcipher,!libsqlcipher,!darwin
+
+package libtomcrypt
+
+/*
+#cgo CFLAGS: -DLTC_SOURCE
+#cgo CFLAGS: -I${SRCDIR}
+#cgo windows LDFLAGS: -ladvapi32
+*/
+import "C"