Add sqlcipher_export

Author: jberkel

CHANGELOG.md

@@ -5,6 +5,7 @@
 * Support `WITH` clause ([#1139][])
 * Add `Value` conformance for `NSURL` ([#1110][], [#1141][])
 * Add decoding for `UUID` ([#1137][])
+* SQLCipher: improve documentation ([#1098][]), add `sqlcipher_export`
 * Fix `insertMany([Encodable])` ([#1130][], [#1138][])
 * Fix incorrect spelling of `remove_diacritics` ([#1128][])
 * Fix project build order ([#1131][])
@@ -162,6 +163,7 @@
 [#1077]: https://github.com/stephencelis/SQLite.swift/issues/1077
 [#1094]: https://github.com/stephencelis/SQLite.swift/pull/1094
 [#1095]: https://github.com/stephencelis/SQLite.swift/pull/1095
+[#1098]: https://github.com/stephencelis/SQLite.swift/issues/1098
 [#1100]: https://github.com/stephencelis/SQLite.swift/pull/1100
 [#1105]: https://github.com/stephencelis/SQLite.swift/pull/1105
 [#1109]: https://github.com/stephencelis/SQLite.swift/issues/1109

Documentation/Index.md

@@ -184,9 +184,16 @@ extend `Connection` with methods to change the database key:
 ```swift
 import SQLite
 
-let db = try Connection("path/to/db.sqlite3")
+let db = try Connection("path/to/encrypted.sqlite3")
 try db.key("secret")
-try db.rekey("another secret")
+try db.rekey("new secret") // changes encryption key on already encrypted db
+```
+
+To encrypt an existing database:
+
+```swift
+let db = try Connection("path/to/unencrypted.sqlite3")
+try db.sqlcipher_export(.uri("encrypted.sqlite3"), key: "secret")
 ```
 
 [CocoaPods]: https://cocoapods.org

Sources/SQLite/Core/Connection+Attach.swift

@@ -10,11 +10,21 @@ import SQLite3
 #endif
 
 extension Connection {
-
+    #if SQLITE_SWIFT_SQLCIPHER
+    /// See https://www.zetetic.net/sqlcipher/sqlcipher-api/#attach
+    public func attach(_ location: Location, as schemaName: String, key: String? = nil) throws {
+        if let key = key {
+            try run("ATTACH DATABASE ? AS ? KEY ?", location.description, schemaName, key)
+        } else {
+            try run("ATTACH DATABASE ? AS ?", location.description, schemaName)
+        }
+    }
+    #else
     /// See  https://www3.sqlite.org/lang_attach.html
     public func attach(_ location: Location, as schemaName: String) throws {
         try run("ATTACH DATABASE ? AS ?", location.description, schemaName)
     }
+    #endif
 
     /// See https://www3.sqlite.org/lang_detach.html
     public func detach(_ schemaName: String) throws {

Sources/SQLite/Extensions/Cipher.swift

@@ -6,6 +6,8 @@ import SQLCipher
 extension Connection {
 
     /// - Returns: the SQLCipher version
+    ///
+    /// See https://www.zetetic.net/sqlcipher/sqlcipher-api/#cipher_version
     public var cipherVersion: String? {
         (try? scalar("PRAGMA cipher_version")) as? String
     }
@@ -23,6 +25,8 @@ extension Connection {
     ///            of key data.
     ///            e.g. x'2DD29CA851E7B56E4697B0E1F08507293D761A05CE4D1B628663F411A8086D99'
     /// @param db name of the database, defaults to 'main'
+    ///
+    /// See https://www.zetetic.net/sqlcipher/sqlcipher-api/#sqlite3_key
     public func key(_ key: String, db: String = "main") throws {
         try _key_v2(db: db, keyPointer: key, keySize: key.utf8.count)
     }
@@ -39,6 +43,7 @@ extension Connection {
     /// As "PRAGMA cipher_migrate;" is time-consuming, it is recommended to use this function
     /// only after failure of `key(_ key: String, db: String = "main")`, if older versions of
     /// your app may ise older version of SQLCipher
+    ///
     /// See https://www.zetetic.net/sqlcipher/sqlcipher-api/#cipher_migrate
     /// and https://discuss.zetetic.net/t/upgrading-to-sqlcipher-4/3283
     /// for more details regarding SQLCipher upgrade
@@ -51,11 +56,13 @@ extension Connection {
         try _key_v2(db: db, keyPointer: key.bytes, keySize: key.bytes.count, migrate: true)
     }
 
-    /// Change the key on an open database.  If the current database is not encrypted, this routine
-    /// will encrypt it.
+    /// Change the key on an open database. NB: only works if the database is already encrypted.
+    ///
     /// To change the key on an existing encrypted database, it must first be unlocked with the
     /// current encryption key. Once the database is readable and writeable, rekey can be used
     /// to re-encrypt every page in the database with a new key.
+    ///
+    /// See https://www.zetetic.net/sqlcipher/sqlcipher-api/#sqlite3_rekey
     public func rekey(_ key: String, db: String = "main") throws {
         try _rekey_v2(db: db, keyPointer: key, keySize: key.utf8.count)
     }
@@ -64,6 +71,17 @@ extension Connection {
         try _rekey_v2(db: db, keyPointer: key.bytes, keySize: key.bytes.count)
     }
 
+    /// Converts a non-encrypted database to an encrypted one.
+    ///
+    /// See https://www.zetetic.net/sqlcipher/sqlcipher-api/#sqlcipher_export
+    public func sqlcipher_export(_ location: Location, key: String) throws {
+        let schemaName = "cipher_export"
+
+        try attach(location, as: schemaName, key: key)
+        try run("SELECT sqlcipher_export(?)", schemaName)
+        try detach(schemaName)
+    }
+
     // MARK: - private
     private func _key_v2(db: String,
                          keyPointer: UnsafePointer<UInt8>,

Tests/SQLiteTests/CipherTests.swift

@@ -99,6 +99,15 @@ class CipherTests: XCTestCase {
         XCTAssertEqual(1, try conn.scalar("SELECT count(*) FROM foo") as? Int64)
     }
 
+    func test_export() throws {
+        let tmp = temporaryFile()
+        try db1.sqlcipher_export(.uri(tmp), key: "mykey")
+
+        let conn = try Connection(tmp)
+        try conn.key("mykey")
+        XCTAssertEqual(1, try conn.scalar("SELECT count(*) FROM foo") as? Int64)
+    }
+
     private func keyData(length: Int = 64) -> NSMutableData {
         let keyData = NSMutableData(length: length)!
         let result  = SecRandomCopyBytes(kSecRandomDefault, length,

Tests/SQLiteTests/Fixtures.swift

@@ -16,3 +16,7 @@ func fixture(_ name: String, withExtension: String?) -> String {
     }
     fatalError("Cannot find \(name).\(withExtension ?? "")")
 }
+
+func temporaryFile() -> String {
+    URL(fileURLWithPath: NSTemporaryDirectory()).appendingPathComponent(UUID().uuidString).path
+}