[libgda] SqlCipher: improved doc and made password mandatory

[Vivien Malerba <vivien src gnome org>]

commit 3b69a5f0008541202ee41c179917873650932d12
Author: Vivien Malerba <malerba gnome-db org>
Date:   Sat May 5 20:49:10 2012 +0200

    SqlCipher: improved doc and made password mandatory

 doc/C/prov-notes.xml                            |   32 ++++++++++++++++------
 providers/sqlcipher/sqlcipher_specs_auth.xml.in |    2 +-
 2 files changed, 24 insertions(+), 10 deletions(-)
---
diff --git a/doc/C/prov-notes.xml b/doc/C/prov-notes.xml
index 27eb5a0..dfca6c7 100644
--- a/doc/C/prov-notes.xml
+++ b/doc/C/prov-notes.xml
@@ -213,7 +213,7 @@
     The SQLCipher database provider allows one to connect to a database encrypted using the
     <ulink url="http://www.zetetic.net/code/sqlcipher";>SQLCipher</ulink> adaptations to the SQLite
     database. This section deals about how to manage the passphrase associated with a database file, please
-    also consult the information <ulink url="http://www.zetetic.net/code/sqlcipher";>provided by SQLCipher</ulink>
+    also consult the information <ulink url="http://sqlcipher.net/sqlcipher-api/";>provided by SQLCipher</ulink>
     before attempting to use this database provider.
   </para>
   <para>
@@ -226,8 +226,8 @@
     <para>
       To create an encrypted database, you can use the <application>gda-sql</application> and when prompted
       enter the requested passphrase, as:
-      <programlisting><![CDATA[prompt> gda-sql-4.0 "SQLCipher://DB_NAME=testcrypt"
-Welcome to the GDA SQL console, version 4.1.11
+      <programlisting><![CDATA[prompt> gda-sql-5.0 "SQLCipher://DB_NAME=testcrypt"
+Welcome to the GDA SQL console, version 5.1.0
 
 Type: .copyright to show usage and distribution terms
       .? for help with internal commands
@@ -240,15 +240,17 @@ Opening connection 'c0' for: SQLCipher://DB_NAME=testcrypt
     </para>
   </sect2>
   <sect2>
-    <title>How to encrypt an existing database</title>
+    <title>How to encrypt an existing plaintext database to an encrypted database file</title>
     <para>
-      To encrypt an existing database, connect to the database using the SQLCipher provider and execute the
-      following SQL command (replace the passphrase with the requested passphrase):
-      <programlisting>PRAGMA key = 'passphrase';</programlisting>
-      setting the requested passphrase which will be later required to reopen the database. This step
-      prevents opening the database file by the "standard" SQLite provider.
+      To encrypt an existing (SQLite) database, connect to the plaintext database using the SQLCipher provider and execute the
+      following SQL commands (replace the passphrase with the requested passphrase):
+      <programlisting>ATTACH DATABASE 'encrypted.db' AS encrypted KEY 'passphrase';
+SELECT sqlcipher_export('encrypted');
+DETACH DATABASE encrypted; </programlisting>
+      This step prevents opening the database file by the "standard" SQLite provider.
     </para>
   </sect2>
+
   <sect2>
     <title>How to change the passphrase of an encrypted database</title>
     <para>
@@ -258,6 +260,18 @@ Opening connection 'c0' for: SQLCipher://DB_NAME=testcrypt
     </para>
   </sect2>
 
+  <sect2>
+    <title>How to decrypt an existing database to a plaintext database</title>
+    <para>
+      To decrypt an existing encrypted database, connect to the database using the SQLCipher provider and execute the
+      following SQL commands (replace the passphrase with the requested passphrase):
+      <programlisting>ATTACH DATABASE 'plaintext.db' AS plaintext KEY '';
+SELECT sqlcipher_export('plaintext');
+DETACH DATABASE plaintext; </programlisting>
+      This step allows opening the database file by the "standard" SQLite provider.
+    </para>
+  </sect2>
+
   <para>
     Also refer to the <link linkend="provider_notes_sqlite">SQLite's provider's notes</link>,
     and <link linkend="limitations_sqlcipher">SQLCipher provider's limitations</link>.
diff --git a/providers/sqlcipher/sqlcipher_specs_auth.xml.in b/providers/sqlcipher/sqlcipher_specs_auth.xml.in
index bd7df0f..6d9cfd6 100644
--- a/providers/sqlcipher/sqlcipher_specs_auth.xml.in
+++ b/providers/sqlcipher/sqlcipher_specs_auth.xml.in
@@ -1,6 +1,6 @@
 <?xml version="1.0"?>
 <data-set-spec>
   <parameters>
-    <parameter id="PASSWORD" _name="Passphrase" _descr="Encryption passphrase" gdatype="gchararray" nullok="TRUE" plugin="string:HIDDEN=true"/>
+    <parameter id="PASSWORD" _name="Passphrase" _descr="Encryption passphrase" gdatype="gchararray" nullok="FALSE" plugin="string:HIDDEN=true"/>
   </parameters>
 </data-set-spec>