You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+41-12Lines changed: 41 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,13 @@
1
1
## SQLCipher
2
2
3
-
SQLCipher extends the [SQLite](https://www.sqlite.org) database library to add security enhancements that make it more suitable for encrypted local data storage such as on-the-fly encryption, tamper evidence, and key derivation. Based on SQLite, SQLCipher closely tracks SQLite and periodically integrates stable SQLite release features.
3
+
SQLCipher extends the [SQLite](https://www.sqlite.org) database library to add security enhancements that make it more suitable for encrypted local data storage like:
4
+
5
+
- on-the-fly encryption
6
+
- tamper detection
7
+
- memory sanitization
8
+
- strong key derivation
9
+
10
+
SQLCipher is based on SQLite and stable upstream release features are periodically integrated.
4
11
5
12
SQLCipher is maintained by Zetetic, LLC, and additional information and documentation is available on the official [SQLCipher site](https://www.zetetic.net/sqlcipher/).
6
13
@@ -21,33 +28,51 @@ SQLCipher is also compatible with standard SQLite databases. When a key is not p
21
28
22
29
## Contributions
23
30
24
-
The SQLCipher team welcomes contributions to the core library. All contributions including pull requests and patches should be based on the `prerelease` branch, and must be accompanied by a [contributor agreement](https://www.zetetic.net/contributions/). For large changes we strongly encourage [discussion](https://discuss.zetetic.net/c/sqlcipher) of the proposed change prior to development and submission.
31
+
The SQLCipher team welcomes contributions to the core library. All contributions including pull requests and patches should be based on the `prerelease` branch, and must be accompanied by a [contributor agreement](https://www.zetetic.net/contributions/). We strongly encourage [discussion](https://discuss.zetetic.net/c/sqlcipher) of the proposed change prior to development and submission.
25
32
26
33
## Compiling
27
34
28
-
Building SQLCipher is almost the same as compiling a regular version of
29
-
SQLite with two small exceptions:
35
+
Building SQLCipher is similar to compiling a regular version of SQLite from source a couple small exceptions:
30
36
31
-
1. You *must* define `SQLITE_HAS_CODEC` and `SQLITE_TEMP_STORE=2`when building sqlcipher.
32
-
2.If compiling against the default OpenSSL crypto provider, you will need to link libcrypto
37
+
1. You *must* define `SQLITE_HAS_CODEC` and either `SQLITE_TEMP_STORE=2`or SQLITE_TEMP_STORE=3`
38
+
2.You will need to link against a support cryptograpic provider (OpenSSL, LibTomCrypt, CommonCrypto/Security.framework, or NSS)
33
39
34
-
Example Static linking (replace /opt/local/lib with the path to libcrypto.a). Note in this
40
+
The following examples demonstrate linking against OpenSSL, which is a readily available provider on most Unix-like systems.
41
+
42
+
Example 1. Static linking (replace /opt/local/lib with the path to libcrypto.a). Note in this
35
43
example, `--enable-tempstore=yes` is setting `SQLITE_TEMP_STORE=2` for the build.
The full SQLite test suite will not complete successfully when using SQLCipher. In some cases encryption interferes with low-level tests that require access to database file data or features which are unsupported by SQLCipher. Those tests that are intended to support encryption are intended for non-SQLCipher implementations. In addition, because SQLite tests are not always isolated, if one test fails it can trigger a domino effect with other failures in later steps.
62
+
63
+
As a result, the SQLCipher package includes it's own independent tests that exercise and verify the core functionality of the SQLCipher extensions. This test suite is intended to provide an abbreviated verification of SQLCipher's internal logic; it does not perform an exhaustive test of the SQLite database system as a whole or verify functionality on specific platforms. Because SQLCipher is based on stable upstream builds of SQLite, it is consider a basic assumption that the core SQLite library code is operating properly (the SQLite core is almost untouched in SQLCipher). Thus, the additional SQLCipher-specific test provide the requisite verification that the library is operating as expected with SQLCipher's security features enabled.
64
+
65
+
To run SQLCipher specific tests, configure as described above and run the following to execute the tests and recieve a report of the results:
66
+
67
+
```
68
+
$ make testfixture
69
+
$ ./testfixture test/sqlcipher.test
70
+
```
46
71
47
72
## Encrypting a database
48
73
49
74
To specify an encryption passphrase for the database via the SQL interface you
50
-
use a pragma. The passphrase you enter is passed through PBKDF2 key derivation to
75
+
use a PRAGMA. The passphrase you enter is passed through PBKDF2 key derivation to
51
76
obtain the encryption key for the database
52
77
53
78
PRAGMA key = 'passphrase';
@@ -69,7 +94,7 @@ same rules as `PRAGMA key`.
69
94
70
95
## Changing a database key
71
96
72
-
To change the encryption passphrase for an existing database you may use the rekey pragma
97
+
To change the encryption passphrase for an existing database you may use the rekey PRAGMA
73
98
after you've supplied the correct database password;
74
99
75
100
PRAGMA key = 'passphrase'; -- start with the existing database passphrase
@@ -85,6 +110,10 @@ This can be accomplished programmatically by using sqlite3_rekey;
85
110
86
111
## Support
87
112
113
+
The primary source for complete documentation (desing, API, platforms, usage) is the SQLCipher website:
114
+
115
+
https://www.zetetic.net/sqlcipher/documentation
116
+
88
117
The primary avenue for support and discussions is the SQLCipher discuss site:
89
118
90
119
https://discuss.zetetic.net/c/sqlcipher
@@ -100,9 +129,9 @@ posts about SQLCipher as we do not monitor them frequently.
100
129
If you are using SQLCipher in your own software please let us know at
0 commit comments