sqlite3免费加密开源项目sqlcipher简单使用

一、概述

使用sqlite3的免费版本是不支持加密的。为了能使用上加密sqlite3，有一个免费的开源项目sqlcipher提供了免费和付费的加密sqlite功能。我们当然选择免费的版本啦。

官方网站：
https://www.zetetic.net/sqlcipher/open-source/

文档目录：
https://www.zetetic.net/sqlcipher/documentation/

设计简介：
https://www.zetetic.net/sqlcipher/design/

API文档：
https://www.zetetic.net/sqlcipher/sqlcipher-api/

源码下载
git clone https://github.com/sqlcipher/sqlcipher.git

如何编译
查看源码的README.md 的编译过程。

二、实际编译

2.1 编译脚本

我们使用的目标板是aarch64(arm64)的linux环境，我们的查看一下我们的编译环境。编译环境如下：

$ env | grep aarch

CXX=aarch64-linux-gnu-g++
LD=aarch64-linux-gnu-ld
AR=aarch64-linux-gnu-ar
NM=aarch64-linux-gnu-nm
PATH=/home/xx/.local/bin:/usr/local/openresty/nginx/sbin:/usr/local/openresty/bin:/usr/local/node-v18.16.0-linux-x64/bin:/home/xx/workspace/toolchain/go/bin:/home/xx/.cargo/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin:/snap/bin:/usr/local/openresty/nginx/sbin:/home/xx/workspace/toolchain/gcc-arm-8.3-2019.03-x86_64-aarch64-linux-gnu/bin:/home/xx/sonar_tools/sonar-scanner-4.7.0.2747-linux/bin:/home/xx/sonar_tools/build-wrapper-linux-x86
CC=aarch64-linux-gnu-gcc
CROSS_COMPILE=/home/xx/workspace/rk3568-git/rk_hal/src/rk3568/prebuilts/gcc/linux-x86/aarch64/gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu/bin/aarch64-linux-gnu-

下面是交叉编译的脚本如下：

# cat build.sh
export AARCH64_SYSROOT=/your/aarch64/sysroot_path
./configure --enable-tempstore=yes  --host aarch64 CFLAGS="-DSQLITE_HAS_CODEC --sysroot=$AARCH64_SYSROOT"  LDFLAGS="-lcrypto --sysroot=$AARCH64_SYSROOT" --prefix=$AARCH64_SYSROOT/usr/local
unset AARCH64_SYSROOT

2.2 编译和安装

make

编译生成了./.libs/libsqlcipher.a 库，是一个静态库。应该也能生成动态库。

make install

安装了头文件和库

include
  └── sqlcipher
	    ├── sqlite3ext.h
	    └── sqlite3.h
bin
 └── sqlcipher

三、实际使用

3.1 应用代码编写与编译

在使用过程中和sqlite3原生的api一样使用。
在应用代码中，去掉原生的sqlite3.h头文件，包含sqlcipher/sqlite3.h和 sqlcipher/sqlite3ext.h头文件。你会发现原生头文件和sqlcipher的防止重复包含宏定义相同，所以一定要去掉原生的有文件。
在应用代码的编译中，Makefile加入编译选项CFLAGS += -DSQLITE_CORE=1 -DSQLITE_HAS_CODEC=1。不加就会报错identifier “sqlite3_api” is undefined。 在链接阶段链接-lcrypto -lsqlcipher。无需再
链接-lsqlite3。

3.2 设置密码

int sqlite3_key(sqlite3 *db, const void *pKey, int nKey);

上述函数等价于sqlite语句PRAGMA key = 'passphrase';

3.3 修改密码

sqlite3_rekey(sqlite3 *db, const void *pKey, int nKey);

上述函数等价于PRAGMA rekey = 'new-passphrase';

修改密码的流程一般是先输入旧的密码然后修改新密码。先sqlite3_key 然后sqlite3_rekey。等价于下面sqlite操作。

PRAGMA key = 'passphrase'; -- start with the existing database passphrase
PRAGMA rekey = 'new-passphrase'; -- rekey will reencrypt with the new passphrase

验证：对于之前没有密码的数据库可以字节rekey吗？

3.4 使用sqlcipher打开加密数据库

sqlcipher
.open file.db
PRAGMA key = 'passphrase'

• 成功示例：

# sqlcipher file.db
SQLite version 3.41.2 2023-03-22 11:56:21 (SQLCipher 4.5.4 community)
Enter ".help" for usage hints.
sqlite> PRAGMA key = '123456';
ok
sqlite> select * from sqlite_master;

• 失败示例：

# sqlcipher 
SQLite version 3.41.2 2023-03-22 11:56:21 (SQLCipher 4.5.4 community)
Enter ".help" for usage hints.
Connected to a transient in-memory database.
Use ".open FILENAME" to reopen on a persistent database.
sqlite> .open file.db
sqlite> PRAGMA key = '123456adss';
ok
sqlite>  select * from sqlite_master;
Parse error: file is not a database (26)
sqlite> .q

如果未加密的数据库可以直接使用selelct访问sqlite_master表，加密的数据库访问时，会报错。未加密的数据库，使用原生的sqlite3工具也能打开，加密的
数据库使用sqlite3打开后设置密码无反应ok,select访问报错file is not a database。

3.5 sqlchiper 数据库备份

调用backup = sqlite3_backup_init(new_db, “main”, dbh->db, “main”)时报错了。报错如下：
sqlite3 backup init error, backup is not supported with encrypted databases。看来加密数据库不支持这样的备份API。

在API中找到了一个这个函数，用来进行加密和非加密之间复制和拷贝。
SQLCipher用法注意:

如果当前数据库是明文数据库，SQLCipher不会加密。如果当前数据库已加密，且pNew0或nNew0，则SQLCipher不会解密。这个例程仅适用于已经加密的数据库，以便更改密钥。
根据SQLCipher文档，从明文到加密或加密到明文的转换应该使用附加的数据库和sqlcipher_export()方便函数。

sqlcipher_export() 函数
sqlcipher_export是一个方便的函数，它将主数据库的全部内容复制到附加数据库，包括架构、触发器、虚拟表和所有数据。它的主要功能是可以轻松地从非加密数据库迁移到加密数据库，
从加密数据库迁移到非加密数据库，或者在 SQLCipher 支持的加密数据库的各种选项之间迁移。有关此主题的其他信息和讨论，请参阅这篇关于如何使用 SQLCipher 加密明文数据库的帖子

Example 1: Encrypt a Plaintext Database

$ ./sqlcipher plaintext.db
sqlite> ATTACH DATABASE 'encrypted.db' AS encrypted KEY 'testkey';
sqlite> SELECT sqlcipher_export('encrypted');
sqlite> DETACH DATABASE encrypted;

Example 2: Decrypt a SQLCipher database to a Plaintext Database

$ ./sqlcipher encrypted.db
sqlite> PRAGMA key = 'testkey';
sqlite> ATTACH DATABASE 'plaintext.db' AS plaintext KEY '';  -- empty key will disable encryption
sqlite> SELECT sqlcipher_export('plaintext');
sqlite> DETACH DATABASE plaintext;

Example 3: Convert from a 3.x to 4.x Database

$ ./sqlcipher 1.1.x.db
sqlite> PRAGMA key = 'testkey';
sqlite> PRAGMA cipher_page_size = 1024;
sqlite> PRAGMA kdf_iter = 64000;
sqlite> PRAGMA cipher_hmac_algorithm = HMAC_SHA1;
sqlite> PRAGMA cipher_kdf_algorithm = PBKDF2_HMAC_SHA1;
sqlite> ATTACH DATABASE 'sqlcipher-4.db' AS sqlcipher4 KEY 'testkey';
sqlite> SELECT sqlcipher_export('sqlcipher4');
sqlite> DETACH DATABASE sqlcipher4;

Example 4: Changing Cipher Settings

$ ./sqlcipher encrypted.db
sqlite> PRAGMA key = 'testkey';
sqlite> ATTACH DATABASE 'newdb.db' AS newdb KEY 'newkey';
sqlite> PRAGMA newdb.cipher_page_size = 4096;
sqlite> PRAGMA newdb.cipher = 'aes-256-cfb';
sqlite> PRAGMA newdb.kdf_iter = 10000;
sqlite> SELECT sqlcipher_export('newdb');
sqlite> DETACH DATABASE newdb;

Example 5: Copying an attached plaintext database to a new empty encrypted main database

$ ./sqlcipher encrypted.db
sqlite> PRAGMA key = 'testkey';
sqlite> ATTACH DATABASE 'plain.db' AS plain KEY '';
sqlite> SELECT sqlcipher_export('main', 'plain');
sqlite> DETACH DATABASE plain;