From 12ed2a3228c63885dbf84f090c8da41afbbccd59 Mon Sep 17 00:00:00 2001 From: Stephen Lombardo Date: Wed, 28 Dec 2011 11:39:50 -0500 Subject: [PATCH] long overdue updates to the README file --- README | 87 ++++++++++++++++++++++++++++++++++------------------------ 1 file changed, 51 insertions(+), 36 deletions(-) diff --git a/README b/README index d964a72..1b0a461 100644 --- a/README +++ b/README @@ -1,58 +1,63 @@ -== SQLite Cipher == +== SQLCipher == -SQLite Cipher is an SQLite extension that provides transparent 256 bit AES encryption of database files. -Pages are encrypted before being written to disk and are decrypted when read back. +SQLCipher is an SQLite extension that provides transparent 256-bit AES encryption of +database files. Pages are encrypted before being written to disk and are decrypted +when read back. Due to the small footprint and great performance it’s ideal for +protecting embedded application databases and is well suited for mobile development. -Encryption is provided by the OpenSSL crypto library. +The official SQLCipher software site is http://sqlcipher.net -SQLite Cipher was initially developed by Stephen Lombardo at Zetetic LLC (sjlombardo@zetetic.net) to provide -the encrypted database layer for Strip, an iPhone data vault and password manager ( http://www.zetetic.net/products/strip ). +SQLCipher was initially developed by Stephen Lombardo at Zetetic LLC +(sjlombardo@zetetic.net) as the encrypted database layer for Strip, +an iPhone data vault and password manager (http://getstrip.com). -The official SQLCipher software site can be found at http://www.zetetic.net/software/sqlcipher +[Features] -Issues or support questions on using SQLCipher should be entered into the GitHub Issue tracker: - -http://github.com/sjlombardo/sqlcipher/issues - -Please DO NOT post issues, support questions, or other problems to blog posts about SQLCipher as we do not monitor them frequently. - -If you are using SQLCipher in your own software please let us know at support@zetetic.net! +- Fast performance with as little as 5-15% overhead for encryption on many operations +- 100% of data in the database file is encrypted +- Good security practices (CBC mode, key derivation) +- Zero-configuration and application level cryptography +- Algorithms provided by the peer reviewed OpenSSL crypto library. [Compiling] -Building SQLite Cipher is almost the same as compiling a regular version of SQLite with three small exceptions: +Building SQLCipher is almost the same as compiling a regular version of +SQLite with two small exceptions: - 1. building via 'amalgamation' isn't supported (where all sqlite source is merged into one file) - 2. you must define SQLITE_HAS_CODEC and SQLITE_TEMP_STORE=2 in your application when including SQLCipher - 3. You need to link against a OpenSSL's libcrypto with sha256 support compiled in + 1. You must define SQLITE_HAS_CODEC and SQLITE_TEMP_STORE=2 when building sqlcipher + 2. You need to link against a OpenSSL's libcrypto Example Static linking (replace /opt/local/lib with the path to libcrypto.a) - ./configure --enable-tempstore=yes CFLAGS="-DSQLITE_HAS_CODEC" LDFLAGS="/opt/local/lib/libcrypto.a" - make + $ ./configure --enable-tempstore=yes CFLAGS="-DSQLITE_HAS_CODEC" \ + LDFLAGS="/opt/local/lib/libcrypto.a" + $ make Example Dynamic linking - ./configure --enable-tempstore=yes CFLAGS="-DSQLITE_HAS_CODEC" LDFLAGS="-lcrypto" - make + $ ./configure --enable-tempstore=yes CFLAGS="-DSQLITE_HAS_CODEC" \ + LDFLAGS="-lcrypto" + $ make [Encrypting a database] -To specify an encryption passphrase for the database you can use a pragma. The passphrase -you enter is hashed using sha256 and the result is used as the encryption key for the -database. +To specify an encryption passphrase for the database via the SQL interface you +use a pragma. The passphrase you enter is passed through PBKDF2 key derivation to +obtain the encryption key for the database PRAGMA key = 'passphrase'; Alternately, you can specify an exact byte sequence using a blob literal. If you use this method it is your responsibility to ensure that the data you provide a 64 character hex string, which will be converted directly to 32 bytes (256 bits) of -key data. +key data without key derivation. PRAGMA key = "x'2DD29CA851E7B56E4697B0E1F08507293D761A05CE4D1B628663F411A8086D99'"; -To encrypt a database programatically you can use the sqlite3_key function. The data provided -in pKey is converted to an encryption key according to the same rules as PRAGMA key. +To encrypt a database programatically you can use the sqlite3_key function. +The data provided in pKey is converted to an encryption key according to the +same rules as PRAGMA key. + int sqlite3_key(sqlite3 *db, const void *pKey, int nKey); @@ -60,11 +65,11 @@ PRAGMA key or sqlite3_key should be called as the first operation when a databas [Changing a database key] -To change the encryption passphrase for an existing database you should use the rekey pragma +To change the encryption passphrase for an existing database you may use the rekey pragma after you've supplied the correct database password; PRAGMA key = 'passphrase'; -- start with the existing database passphrase - PRAGMA rekey = 'new-passphrase'; -- rekey will reencrypt the database with the new passphrase + PRAGMA rekey = 'new-passphrase'; -- rekey will reencrypt with the new passphrase The hexrekey pragma may be used to rekey to a specific binary value @@ -74,12 +79,22 @@ This can be accomplished programtically by using sqlite3_rekey; sqlite3_rekey(sqlite3 *db, const void *pKey, int nKey) -[Encrypting a standard database] +[Support] -Encrypting a standard, plaintext SQLite database is not supported at this time. We are currently -working on a resolution to the problem. In the mean time it is easiest to start out with an -encrypted database if possible. Alternately it should be possible to open a standard database, -ATTACH an encrypted DB, and then copy your tables and data between the two. +The primary avenue for support and discussions is the SQLCipher users mailing list: + +http://groups.google.com/group/sqlcipher + +Issues or support questions on using SQLCipher should be entered into the +GitHub Issue tracker: + +http://github.com/sjlombardo/sqlcipher/issues + +Please DO NOT post issues, support questions, or other problems to blog +posts about SQLCipher as we do not monitor them frequently. + +If you are using SQLCipher in your own software please let us know at +support@zetetic.net! [License] @@ -108,7 +123,7 @@ 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. -== End SQLite Cipher == +== End SQLCipher == This directory contains source code to