Add support for SQLCipher

.github/workflows/go.yaml

@@ -21,7 +21,14 @@ jobs:
       GO: ${{ matrix.go }}
     steps:
       - if: startsWith(matrix.os, 'macos')
-        run: brew update
+        run: |
+          brew update
+          brew install sqlcipher
+
+      - if: startsWith(matrix.os, 'ubuntu')
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends libsqlcipher-dev
 
       - uses: actions/setup-go@v2
         with:
@@ -43,9 +50,18 @@ jobs:
       - name: 'Tags: libsqlite3'
         run: go-acc . -- -race -v -tags "libsqlite3"
 
+      - name: 'Tags: sqlcipher'
+        run: go-acc . -- -race -v -tags "sqlcipher"
+
+      - name: 'Tags: libsqlcipher'
+        run: go-acc . -- -race -v -tags "libsqlcipher"
+
       - name: 'Tags: full'
         run: go-acc . -- -race -v -tags "sqlite_allow_uri_authority sqlite_app_armor sqlite_column_metadata sqlite_foreign_keys sqlite_fts5 sqlite_icu sqlite_introspect sqlite_json sqlite_math_functions sqlite_os_trace sqlite_preupdate_hook sqlite_secure_delete sqlite_see sqlite_stat4 sqlite_trace sqlite_unlock_notify sqlite_userauth sqlite_vacuum_incr sqlite_vtable"
 
+      - name: 'Tags: sqlcipher+full'
+        run: go-acc . -- -race -v -tags "sqlcipher sqlite_allow_uri_authority sqlite_app_armor sqlite_column_metadata sqlite_foreign_keys sqlite_fts5 sqlite_icu sqlite_introspect sqlite_json sqlite_math_functions sqlite_os_trace sqlite_preupdate_hook sqlite_secure_delete sqlite_see sqlite_stat4 sqlite_trace sqlite_unlock_notify sqlite_userauth sqlite_vacuum_incr sqlite_vtable"
+
       - name: 'Tags: vacuum'
         run: go-acc . -- -race -v -tags "sqlite_vacuum_full"
 
@@ -73,7 +89,7 @@ jobs:
       - uses: msys2/setup-msys2@v2
         with:
           update: true
-          install: mingw-w64-x86_64-toolchain mingw-w64-x86_64-sqlite3
+          install: mingw-w64-x86_64-toolchain mingw-w64-x86_64-sqlite3 mingw-w64-x86_64-sqlcipher
           msystem: MINGW64
           path-type: inherit
 
@@ -96,12 +112,26 @@ jobs:
         run: go build -race -v -tags "libsqlite3"
         shell: msys2 {0}
 
+      - name: 'Tags: sqlcipher'
+        run: go build -race -v -tags "sqlcipher"
+        shell: msys2 {0}
+
+      - name: 'Tags: libsqlcipher'
+        run: go build -race -v -tags "libsqlcipher"
+        shell: msys2 {0}
+
       - name: 'Tags: full'
         run: |
           echo 'skip this test'
           echo go build -race -v -tags "sqlite_allow_uri_authority sqlite_app_armor sqlite_column_metadata sqlite_foreign_keys sqlite_fts5 sqlite_icu sqlite_introspect sqlite_json sqlite_math_functions sqlite_preupdate_hook sqlite_secure_delete sqlite_see sqlite_stat4 sqlite_trace sqlite_unlock_notify sqlite_userauth sqlite_vacuum_incr sqlite_vtable"
         shell: msys2 {0}
 
+      - name: 'Tags: sqlcipher+full'
+        run: |
+          echo 'skip this test'
+          echo go build -race -v -tags "sqlcipher sqlite_allow_uri_authority sqlite_app_armor sqlite_column_metadata sqlite_foreign_keys sqlite_fts5 sqlite_icu sqlite_introspect sqlite_json sqlite_math_functions sqlite_preupdate_hook sqlite_secure_delete sqlite_see sqlite_stat4 sqlite_trace sqlite_unlock_notify sqlite_userauth sqlite_vacuum_incr sqlite_vtable"
+        shell: msys2 {0}
+
       - name: 'Tags: vacuum'
         run: go build -race -v -tags "sqlite_vacuum_full"
         shell: msys2 {0}

README.md

@@ -43,9 +43,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)
@@ -109,11 +112,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. |
@@ -354,6 +363,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 package supports the SQLite User Authentication module.
@@ -596,6 +617,34 @@ 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). The license of that code is the same as the license of SQLCipher:
+```
+Copyright (c) 2008, 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.
+```
+
 # 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"