sqlite3易语言支持库和模块，相对于1.0的更新

# wxSQLite3 encryption extension for SQLite3 This document describes the SQLite3 encryption extension provided by wxSQLite3. The document is work in progress and still incomplete. ## Table of contents - [Installation](#installation) - [General](#general) - [wxMSW](#wxmsw) - [wxGTK](#wxgtk) - [Supported ciphers](#ciphers) - [wxSQLite3: AES 128 Bit CBC - No HMAC](#cipher_aes128cbc) - [wxSQLite3: AES 256 Bit CBC - No HMAC](#cipher_aes256cbc) - [sqleet: ChaCha20 - Poly1305 HMAC](#cipher_chacha20) - [SQLCipher: AES 256 Bit CBC - SHA1/SHA256/SHA512 HMAC](#cipher_sqlcipher) - [Legacy cipher modes](#legacy) - [Encryption API](#encryptionapi) - [Overview](#encryption_overview) - [`sqlite3_key()` and `sqlite3_key_v2()`](#encryption_key) - [`sqlite3_rekey()` and `sqlite3_rekey_v2()`](#encryption_rekey) - [`wxsqlite3_config()`](#encryption_config) - [`wxsqlite3_config_cipher()`](#encryption_config_cipher) - [`wxsqlite3_codec_data()`](#encryption_codec_data) - [SQL interface](#encryption_sql) - [URI parameters](#encryption_uri) - [SQLite3 Backup API](#backupapi) ## <a name="installation" />Installation The build system is based on [Premake5](http://premake.github.io/). Premake 5.0-alpha14 or higher is recommended. Ready to use project files are provided for Visual C++ 2010, 2012, 2013, 2015, 2017, and 2019. Additionally, GNU Makefiles are provided supporting for example TDM-GCC MinGW. For Visual Studio 2010+ solutions it is possible to customize the build by creating a `wx_local.props` file in the build directory which is used, if it exists, by the projects. The settings in that file override the default values for the properties. The typical way to make the file is to copy `wx_setup.props` to `wx_local.props` and then edit locally. For GNU Makefiles the file `config.gcc` serves the same purpose as the file wx_setup.props for Visual C++ projects. The customization files `wx_setup.props` resp. `config.gcc` allow to customize certain settings like for example the version number and the root directory of the wxWidgets library. ### <a name="general" />General This implementation of the SQLite encryption support uses internally an adjusted version of the SQLite function `sqlite3RunVacuum` when rekeying a database. New versions of SQLite may change the implementation of this function. Therefore it is strongly recommended to regenerate the source file `rekeyvacuum.c` containing the adjusted implementation, whenever the SQLite version is updated. For this purposes the script `rekeyvacuum.sh` can be used. This script has been adopted from [sqleet](https://github.com/resilar/sqleet). Simply run `../rekeyvacuum.sh sqlite3.c >rekeyvacuum.c` from directory `sqlite3secure/src`. On Windows platforms one can use for example the __Git Bash__ coming with [Git for Windows](https://gitforwindows.org). Occasionally, the signature of function `sqlite3RunVaccum` changes. If that should be the case the code invoking the adjusted function needs to be adjusted as well. ### <a name="wxmsw" />wxMSW When building on Win32 or Win64, you can use the makefiles or one of the Microsoft Visual Studio solution files in the `build` folder. For Visual C++ the debugging properties are set up in such a way that debugging the sample applications should work right out of the box. For release builds you may need to copy the wxSQLite3 DLL or add the `lib` folder path to the Windows search path (PATH environment variable). The SQLite3 library is now compiled as an integrated part of wxSQLite3. The advantage is that SQLite3 and wxSQLite3 are always compiled with matching configuration options. Additionally, the SQLite3 encryption extension is automatically enabled, too. A precompiled SQLite shell program supporting encrypted databases is provided as a separate download. Use ``` PRAGMA KEY="encryption key"; ``` to create or open an encrypted database. Use ``` ATTACH DATABASE x AS y KEY z; ``` to attach an encrypted database. ### <a name="wxgtk" />wxGTK When building on an autoconf-based system (like Linux/GNU-based systems), the first setup is to recreate the configure script doing: ``` autoreconf ``` Thereafter you should create a build directory ``` mkdir build-gtk [or any other suitable name] cd build-gtk ../configure [here you should use the same flags you used to configure wxWidgets] make ``` Type `../configure --help` for more info. The autoconf-based system also supports a `make install` target which builds the library and then copies the headers of the component to `/usr/local/include` and the lib to `/usr/local/lib`. ## <a name="ciphers" />Supported ciphers The following ciphers are currently supported by **wxSQLite3**: - [AES 128 Bit CBC - No HMAC (wxSQLite3)](#cipher_aes128cbc) - [AES 256 Bit CBC - No HMAC (wxSQLite3)](#cipher_aes256cbc) - [ChaCha20 - Poly1305 HMAC (sqleet)](#cipher_chacha20) - [AES 256 Bit CBC - SHA1/SHA256/SHA512 HMAC (SQLCipher)](#cipher_sqlcipher) Definition of abbreviations: - 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 - SHA256 = Secure Hash Algorithm 2 (256 bit hash) - SHA512 = Secure Hash Algorithm 2 (512 bit hash) ### <a name="cipher_aes128cbc"/>wxSQLite3: AES 128 Bit CBC - No HMAC This cipher was added to **wxSQLite3** in 2007 as the first supported encryption scheme. It is a 128 bit AES encryption in CBC mode. The encryption key is derived from the passphrase according to the algorithm described in the PDF specification (using the MD5 hash function and the RC4 algorithm). The initial vector for the encryption of each database page is derived from the page number. The cipher does not use a HMAC, and requires therefore no reserved bytes per database page. The following table lists all parameters related to this cipher that can be set before activating database encryption. | Parameter | Default | Min | Max | Description | | :--- | :---: | :---: | :---: | :--- | | `legacy` | 0 | 0 | 1 | Boolean flag whether the legacy mode should be used | | `legacy_page_size` | 0 | 0 | 65536 | Page size to use in legacy mode, 0 = default SQLite page size | **Note**: It is not recommended to use _legacy_ mode for encrypting new databases. It is supported for compatibility reasons only, so that databases that were encrypted in _legacy_ mode can be accessed. ### <a name="cipher_aes256cbc"/>wxSQLite3: AES 256 Bit CBC - No HMAC This cipher was added to **wxSQLite3** in 2010. It is a 256 bit AES encryption in CBC mode. The encryption key is derived from the passphrase using an SHA256 hash function. The initial vector for the encryption of each database page is derived from the page number. The cipher does not use a Hash Message Authentication Code (HMAC), and requires therefore no reserved bytes per database page. The following table lists all parameters related to this cipher that can be set before activating database encryption. | Parameter | Default | Min | Max | Description | | :--- | :---: | :---: | :---: | :--- | | `kdf_iter` | 4001 | 1 | | Number of iterations for the key derivation function | `legacy` | 0 | 0 | 1 | Boolean flag whether the legacy mode should be used | | `legacy_page_size` | 0 | 0 | 65536 | Page size to use in legacy mode, 0 = default SQLite page size | **Note**: It is not recommended to use _legacy_ mode for encrypting new databases. It is supported for compatibility reasons only, so that databases that were encrypted in _legacy_ mode can be accessed. ### <a name="cipher_chacha20"/>sqleet: ChaCha20 - Poly1305 HMAC This cipher was introduced for SQLite database encryption by the project [sqleet](https://github.com/resilar/sqleet) in 2017. The Internet Engineering Task Force (IETF) officially standardized