带有加密功能的 SQLite Qt 插件（v1.0）

4.4K

QtCipherSqlitePlugin 最近升级到 1.0 版。这是一个比较大的升级，增加了一些新功能。感兴趣的童鞋可以升级试用下。

与之前的版本一样，QtCipherSqlitePlugin 还是基于 wxSQLite3 提供的 sqlite3secure 这个库。1.0 版的 QtCipherSqlitePlugin 插件将依赖的 wxSQLite3 升级到 4.0.4，sqlite 的版本是 3.24.0。

最新的 1.0 版代码可以使用 git 从 github 或者 gitee 获取：

git clone https://github.com/devbean/QtCipherSqlitePlugin.git
// OR
// git clone https://gitee.com/devbean/QtCipherSqlitePlugin.git
cd QtCipherSqlitePlugin
git checkout 1.0

全新的插件项目结构

前面几个版本的插件与 Qt 私有类紧密耦合，导致插件的代码会随着 Qt 的更新出现无法编译的情况。当初提到的解决方案是，将 Qt 的某些私有类的实现代码直接添加到插件代码树中，除去 Qt 私有类的依赖。这样，针对以后 Qt 的更新，插件只选择对性能有影响的部分进行跟进。这种实现固然能够减小插件代码的修改，但带来的问题是可能与未来的 Qt 版本不兼容，并且移植插件代码时可能会有一些问题。例如，虽然在外部使用时，插件的接口没有任何变化，但实际内部有了翻天覆地的变化。

为了解决这一问题，豆子重新调整了插件的项目结构。在 sqlitecipher 文件夹下的 sqlitecipher.pro 中增加了 Qt 私有文件的导入：

QT_FOR_CONFIG += sqldrivers-private
...
QT = core core-private sql-private

现在，我们的插件已经能够使用 Qt 私有类，而且编译插件也不需要做任何修改。目前豆子只使用 Qt 5.11 进行了测试，如果有其它版本的 Qt 不能正常使用，请及时联系豆子。

本次更新我们还是使用了 SQLITECIPHER 作为插件的名字。如果需要修改这个名字，Qt4 需要修改 smain.cpp 中的 DriverName 定义，Qt5 需要修改 SqliteCipherDriverPlugin.json 中的 SQLITECIPHER 一行。

编译插件

插件的编译可以通过 Qt Creator 或者直接使用命令。

使用 Qt Creator  编译，将 clone 下来的代码切换到 tag 1.0，然后打开整个项目，编译完毕之后将编译之后得到的 sqlitecipher(d).dll 复制到 Qt 的插件目录 plugins/sqldrivers 即可。

或者可以依次使用下面的命令：

git clone https://github.com/devbean/QtCipherSqlitePlugin.git
# OR https://gitee.com/devbean/QtCipherSqlitePlugin.git
cd QtCipherSqlitePlugin
git checkout 1.0
cd sqlitecipher
mkdir -p build && cd build qmake ../sqlitecipher.pro
make
make install # 可能需要提升权限

检查 QtCipherSqlitePlugin 是否成功加载

我们使用下面的代码检查 QtCipherSqlitePlugin 是否成功加载：

qDebug() << QSqlDatabase::drivers();

如果输出中有 SQLITECIPHER 的名字，说明插件是正常的。

为没有加密的数据库增加密码

Qt 默认提供的 SQLite 插件是没有加密功能的。新版本的 QtCipherSqlitePlugin 支持为原本没有加密的数据库增加密码，使用方法如下：

QSqlDatabase dbconn = QSqlDatabase::addDatabase("SQLITECIPHER");
dbconn.setDatabaseName("test.db");
dbconn.setPassword("test");
dbconn.setConnectOptions("QSQLITE_CREATE_KEY");
if (!dbconn.open()) {
    qDebug() << "Can not open connection: " << dbconn.lastError().driverText();
    exit(CONNECTION_FAILED);
}

上面的代码，我们使用 test.db 数据库，将密码设置为 test，同时指定连接选项为QSQLITE_CREATE_KEY。此时，调用open()函数之后，QtCipherSqlitePlugin 将使用改密码为这个数据库进行加密。

删除数据库密码

QtCipherSqlitePlugin 可以删除数据库密码，此时需要提供原密码，并使用连接选项QSQLITE_REMOVE_KEY，如下：

QSqlDatabase dbconn = QSqlDatabase::addDatabase("SQLITECIPHER");
dbconn.setDatabaseName("test.db");
dbconn.setPassword("test");
dbconn.setConnectOptions("QSQLITE_REMOVE_KEY");
if (!dbconn.open()) {
    qDebug() << "Can not open connection: " << dbconn.lastError().driverText();
    exit(CONNECTION_FAILED);
}

更新数据库密码

QtCipherSqlitePlugin 可以更新数据库原有密码，需要设置原密码，并且使用连接选项QSQLITE_UPDATE_KEY设置新密码，具体代码如下：

QSqlDatabase dbconn = QSqlDatabase::addDatabase("SQLITECIPHER");
dbconn.setDatabaseName("test.db");
dbconn.setPassword("test");
dbconn.setConnectOptions("QSQLITE_UPDATE_KEY=newtest");
if (!dbconn.open()) {
    qDebug() << "Can not open connection: " << dbconn.lastError().driverText();
    exit(CONNECTION_FAILED);
}

如果原密码不正确，QtCipherSqlitePlugin 会直接返回错误。

如果新密码设置为空，例如QSQLITE_UPDATE_KEY=，则作用等同于删除密码。

设置加密算法

QtCipherSqlitePlugin 支持四种加密算法：

• AES 128 Bit CBC - No HMAC (wxSQLite3)
• AES 256 Bit CBC - No HMAC (wxSQLite3)
• ChaCha20 - Poly1305 HMAC (sqleet)
• AES 256 Bit CBC - SHA1 HMAC (SQLCipher)

其中使用到的术语定义如下：

• AES = Advanced Encryption Standard (Rijndael algorithm)
• CBC = Cipher Block Chaining mode
• HMAC = Hash Message Authentication Code
• ChaCha20 = symmetric stream cipher developed by Daniel J. Bernstein
• Poly1305 = cryptographic message authentication code (MAC) developed by Daniel J. Bernstein
• SHA1 = Secure Hash Algorithm 1

默认加密算法在编译时设置。可以修改 sqlitecipher/sqlite3/sqlite3.pri 文件中的DEFINES += ...一行，找到CODEC_TYPE=CODEC_TYPE_CHACHA20一句，修改CODEC_TYPE的值即可。可选值为：

• CODEC_TYPE_AES128
• CODEC_TYPE_AES256
• CODEC_TYPE_CHACHA20（默认）
• CODEC_TYPE_SQLCIPHER

运行时修改加密算法，则可以通过连接参数QSQLITE_USE_CIPHER。例如下面的代码：

QSqlDatabase dbconn = QSqlDatabase::addDatabase("SQLITECIPHER");
dbconn.setDatabaseName("test.db");
dbconn.setPassword("test");
dbconn.setConnectOptions("QSQLITE_USE_CIPHER=sqlcipher");

QSQLITE_USE_CIPHER的可选值分别为：

• aes128cbc
• aes256cbc
• chacha20
• sqlcipher

使用连接参数还可以设置这些加密算法的详细参数值。

wxSQLite3: AES 128 Bit CBC - No HMAC

参数名	默认值	最小值	最大值	说明
AES128CBC_LEGACY	0	0	1	布尔类型，是否使用 LEGACY 模式

wxSQLite3: AES 256 Bit CBC - No HMAC

参数名	默认值	最小值	最大值	说明
AES256CBC_KDF_ITER	4001	1		密钥导出函数（Key derivation function）的迭代次数
AES256CBC_LEGACY	0	0	1	布尔类型，是否使用 LEGACY 模式

sqleet: ChaCha20 - Poly1305 HMAC

参数名	默认值	sqleet	最小值	最大值	说明
CHACHA20_KDF_ITER	64007	12345	1		密钥导出函数（Key derivation function）的迭代次数
CHACHA20_LEGACY	0	1	0	1	布尔类型，是否使用 LEGACY 模式

SQLCipher: AES 256 Bit CBC - SHA1 HMAC

参数名	默认值	v3	v2	v1	最小值	最大值	说明
SQLCIPHER_KDF_ITER	64000	64000	4000	4000	1		密钥导出函数（Key derivation function）的迭代次数
SQLCIPHER_FAST_KDF_ITER	2	2	2	2	1		HMAC 密钥导出函数（HMAC Key derivation function）的迭代次数
SQLCIPHER_HMAC_USE	1	1	1	0	0	1	布尔类型，是否使用 HMAC
SQLCIPHER_HMAC_PGNO	1	1	1	N/A	0	2	HMAC 存储页类型：0 = native, 1 = little endian, 2 = big endian
SQLCIPHER_HMAC_SALT_MASK	0x3a	0x3a	0x3a	N/A	0	255	HMAC 盐的掩码字节
SQLCIPHER_LEGACY	0	1	1	1	0	1	布尔类型，是否使用 LEGACY 模式

详细说明可以参考：https://github.com/devbean/QtCipherSqlitePlugin/wiki/Guide-for-1.0#ciphers

Legacy 模式

所有支持的加密算法都有一个 legacy 模式（遗留模式）。在这个模式下，数据库文件的头信息 16 ~ 23 字节也会被加密。这种行为与 SQLite Encryption Extension (SEE) 官方描述相悖。在官方描述中，数据库文件的 16 ~ 23 字节包含头信息，这个头信息不应该被加密。这一点很重要，因为这些字节会在加密扩展解密数据库头部时，被 SQLite 代码读取并解释。如果数据库头部的 16 ~ 23 字节被加密，SQLite 就不能正确确定数据库文件的页大小。因此，加密扩展或者用户就必须显式设置正确的页大小，否则 SQLite 就可能无法访问加密后的数据库。

从 wxSQLite3 3.1.0 开始（也就是 QtCipherSqlitePlugin 0.3+），wxSQLite3 本身提供的加密算法（AES 128 Bit 和 AES 256 Bit）可能会造成这一问题的代码才被修正。但是，并非所有之前的代码都会出现这个问题，出现问题的概率很低，大约是 1/8192。好消息是，使用新版本打开旧的数据库时，这一问题会被自动修正。但是，这种修正是单向的：修正之后的数据库就不能被旧的插件打开了。对于 sqleet （ChaCha20）和 SQLCipher 这两种加密算法，wxSQLite3 提供的加密结果本身会遵循 SQLite 的要求，但是，这会导致与使用 sqleet 以及 SQLCipher (Zetetic LLC)的原始方法加密而来的数据库不兼容。这是因为后两者的原始加密算法就没有提供 16 ~ 23 字节不加密的结果（未来版本可能会提供类似结果），因此，如果需要兼容使用二者原始算法加密而来的数据库，则需要设置 Lagacy 模式。