You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-commits@db.apache.org by ch...@apache.org on 2012/10/17 22:31:09 UTC
svn commit: r1399419 - in /db/derby/docs/trunk/src:
devguide/cdevcsecuredecryptdb.dita devguide/derbydev.ditamap
ref/refderby.ditamap ref/rrefattrib15290.dita ref/rrefattribdecryptdb.dita
Author: chaase3
Date: Wed Oct 17 20:31:08 2012
New Revision: 1399419
URL: http://svn.apache.org/viewvc?rev=1399419&view=rev
Log:
DERBY-5939 Document URL attribute for database decryption
Added 1 Developer's Guide and 1 Reference Manual topic, modified the map files,
and added a sentence to another Reference Manual topic.
Patch: DERBY-5939.diff
Added:
db/derby/docs/trunk/src/devguide/cdevcsecuredecryptdb.dita (with props)
db/derby/docs/trunk/src/ref/rrefattribdecryptdb.dita (with props)
Modified:
db/derby/docs/trunk/src/devguide/derbydev.ditamap
db/derby/docs/trunk/src/ref/refderby.ditamap
db/derby/docs/trunk/src/ref/rrefattrib15290.dita
Added: db/derby/docs/trunk/src/devguide/cdevcsecuredecryptdb.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevcsecuredecryptdb.dita?rev=1399419&view=auto
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevcsecuredecryptdb.dita (added)
+++ db/derby/docs/trunk/src/devguide/cdevcsecuredecryptdb.dita Wed Oct 17 20:31:08 2012
@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
+ "../dtd/concept.dtd">
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<concept id="cdevcsecuredecryptdb" xml:lang="en-us">
+<title>Decrypting an encrypted database</title>
+<shortdesc>You can return an encrypted database to an unencrypted state by
+specifying attributes on the connection URL.</shortdesc>
+<prolog><metadata>
+<keywords><indexterm>encrypted databases<indexterm>decrypting</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<conbody>
+<p>To decrypt an encrypted database, specify the <i>decryptDatabase=true</i>
+attribute in conjunction with either the <i>bootPassword=key</i> attribute or
+the <i>encryptionKey=key</i> attribute.</p>
+<p>See the <ph conref="../conrefs.dita#pub/citref"></ph> for details on the
+connection URL attributes.</p>
+<note othertype="Recommendation" type="other">Ensure
+that you have enough free disk space before you decrypt a database. In addition
+to the disk space required for the unencrypted size of the database, temporary
+disk space is required to store the encrypted version of the data to restore the
+database to its encrypted state if the decryption is interrupted or returns
+errors. All of the temporary disk space is released back to the operating
+system after the database is decrypted.</note>
+<p>You must shut down the database before you decrypt it. An attempt to decrypt
+a booted database has no effect.</p>
+<p>If the database is configured with log archival, you must disable log
+archival in addition to shutting down the database before you can decrypt the
+database. You should also create a new backup of the database before you decrypt
+it, and create another after you decrypt it. For more information, see the
+section "Backing up and restoring databases" in the
+<ph conref="../conrefs.dita#pub/citadmin"></ph>, particularly "Roll-forward
+recovery".</p>
+<p>If any global transactions are in the prepared state after recovery, the
+database cannot be decrypted.</p>
+<p>If <xref href="cdevcsecure36127.dita#cdevcsecure36127">authentication</xref>
+and <xref href="cdevcsecure36595.dita#cdevcsecure36595">SQL authorization</xref>
+are both enabled, the credentials of the
+<xref href="cdevcsecureDbOwner.dita#cdevcsecureDbOwner">database owner</xref>
+must be supplied as well, since decryption is a restricted operation.</p>
+</conbody>
+</concept>
Propchange: db/derby/docs/trunk/src/devguide/cdevcsecuredecryptdb.dita
------------------------------------------------------------------------------
svn:eol-style = native
Modified: db/derby/docs/trunk/src/devguide/derbydev.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/derbydev.ditamap?rev=1399419&r1=1399418&r2=1399419&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/derbydev.ditamap (original)
+++ db/derby/docs/trunk/src/devguide/derbydev.ditamap Wed Oct 17 20:31:08 2012
@@ -1380,12 +1380,14 @@ limitations under the License.
<relcell>
<topicref href="cdevcsecure866716.dita" navtitle="Creating a boot password">
</topicref>
-<topicref href="cdevcsecure60146.dita" navtitle="Booting an encrypted database">
-</topicref>
<topicref href="cdevcsecure31493.dita" navtitle="Specifying an alternate encryption provider">
</topicref>
<topicref href="cdevcsecure67151.dita" navtitle="Specifying an alternate encryption algorithm">
</topicref>
+<topicref href="cdevcsecure60146.dita" navtitle="Booting an encrypted database">
+</topicref>
+<topicref href="cdevcsecuredecryptdb.dita" navtitle="Decrypting an encrypted database">
+</topicref>
</relcell>
</relrow>
<relrow>
@@ -1398,11 +1400,13 @@ limitations under the License.
</topicref>
<topicref href="cdevcsecure96815.dita" navtitle="Requirements for Derby encryption">
</topicref>
+<topicref href="cdevcsecuredecryptdb.dita" navtitle="Decrypting an encrypted database">
+</topicref>
</relcell>
</relrow>
<relrow>
<relcell>
-<topicref href="cdevcsecure866716.dita" navtitle="Creating the boot password">
+<topicref href="cdevcsecure866716.dita" navtitle="Creating a boot password">
</topicref>
</relcell>
<relcell>
@@ -1478,6 +1482,16 @@ limitations under the License.
<relcell>
<topicref href="cdevcsecure97760.dita" navtitle="Working with encryption">
</topicref>
+<topicref href="cdevcsecure88690.dita" navtitle="Encrypting databases on creation">
+</topicref>
+</relcell>
+</relrow>
+<relrow>
+<relcell>
+<topicref href="cdevcsecuredecryptdb.dita" navtitle="Decrypting an encrypted database">
+</topicref>
+</relcell>
+<relcell>
</relcell>
</relrow>
<relrow>
@@ -2058,6 +2072,8 @@ with updatable result sets"></topicref>
</topicref>
<topicref href="cdevcsecure60146.dita" navtitle="Booting an encrypted database">
</topicref>
+<topicref href="cdevcsecuredecryptdb.dita" navtitle="Decrypting an encrypted database">
+</topicref>
</topicref>
</topicref>
<topicref href="cdevcsecure90988.dita" navtitle="Signed jar files"></topicref>
Modified: db/derby/docs/trunk/src/ref/refderby.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/refderby.ditamap?rev=1399419&r1=1399418&r2=1399419&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/refderby.ditamap (original)
+++ db/derby/docs/trunk/src/ref/refderby.ditamap Wed Oct 17 20:31:08 2012
@@ -1126,6 +1126,8 @@ URL syntax"></topicref>
</topicref>
<topicref href="rrefattrib15290.dita" navtitle="dataEncryption=true attribute">
</topicref>
+<topicref href="rrefattribdecryptdb.dita" navtitle="decryptDatabase=true attribute">
+</topicref>
<topicref href="rrefattribderegister.dita" navtitle="deregister=false attribute">
</topicref>
<topicref href="rrefattribdrop.dita" navtitle="drop=true attribute">
Modified: db/derby/docs/trunk/src/ref/rrefattrib15290.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefattrib15290.dita?rev=1399419&r1=1399418&r2=1399419&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefattrib15290.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefattrib15290.dita Wed Oct 17 20:31:08 2012
@@ -30,7 +30,12 @@ data encryption</indexterm></indexterm><
<section><title>Function</title><p>Specifies data encryption on disk for a
new database or to configure an existing unencrypted database for encryption.
For information about data encryption, see "Encrypting databases on disk"
-in the <cite><ph conref="../conrefs.dita#pub/citdevelop"></ph></cite>.</p> </section>
+in the <cite><ph conref="../conrefs.dita#pub/citdevelop"></ph></cite>.</p>
+<p>After you encrypt a database, you can return it to the unencrypted
+state by specifying the
+<i><xref href="rrefattribdecryptdb.dita#rrefattribdecryptdb">decryptDatabase=true</xref></i>
+attribute.</p>
+</section>
<section><title>Combining with other attributes</title>
<p>The <i>dataEncryption=true</i> attribute must be combined with either the
<i><xref href="rrefattrib42100.dita#rrefattrib42100">bootPassword=key</xref></i>
Added: db/derby/docs/trunk/src/ref/rrefattribdecryptdb.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefattribdecryptdb.dita?rev=1399419&view=auto
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefattribdecryptdb.dita (added)
+++ db/derby/docs/trunk/src/ref/rrefattribdecryptdb.dita Wed Oct 17 20:31:08 2012
@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
+ "../dtd/reference.dtd">
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<reference id="rrefattribdecryptdb" xml:lang="en-us">
+<title>decryptDatabase=true attribute</title>
+<prolog><metadata>
+<keywords><indexterm>decryptDatabase=true attribute</indexterm>
+<indexterm>encrypting databases<indexterm>database decryption</indexterm></indexterm>
+<indexterm>databases<indexterm>attributes, data decryption</indexterm></indexterm>
+<indexterm>attributes<indexterm>decryptDatabase</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<refbody>
+<section><title>Function</title>
+<p>Returns an encrypted database to an unencrypted state. For information about
+data encryption, see "Encrypting databases on disk" in the
+<cite><ph conref="../conrefs.dita#pub/citdevelop"></ph></cite>.</p>
+<p>You must shut down the database before you decrypt it. An attempt to decrypt
+a booted database has no effect.</p>
+<p>Specifying this attribute for an unencrypted database has no effect.</p>
+</section>
+<section><title>Combining with other attributes</title>
+<p>The <i>decryptDatabase=true</i> attribute must be combined with either the
+<i><xref href="rrefattrib42100.dita#rrefattrib42100">bootPassword=key</xref></i>
+attribute or the
+<i><xref href="rrefattribencryptkey.dita#rrefattribencryptkey">encryptionKey=key</xref></i>
+attribute.</p>
+<p>
+For an existing, encrypted database for which authentication and SQL
+authorization are both enabled, only the
+<xref href="rrefattrib26867.dita#rrefattrib26867">database owner</xref> can
+perform decryption. See also "Enabling user authentication" and
+"Setting the SQL standard authorization mode" in the
+<ph conref="../conrefs.dita#pub/citdevelop"></ph> for more information.</p>
+</section>
+<example><title>Examples</title>
+<codeblock><b><ph>-- decrypt a database</ph>
+jdbc:derby:encryptedDB;decryptDatabase=true;bootPassword=cLo4u922sc23aPe
+<ph>-- decrypt a database with authentication and SQL authorization enabled</ph>
+jdbc:derby:salesdb;decryptDatabase=true;user=user1;password=mypass;
+ bootPassword=cLo4u922sc23aPe
+</b></codeblock>
+</example>
+</refbody>
+</reference>
+
Propchange: db/derby/docs/trunk/src/ref/rrefattribdecryptdb.dita
------------------------------------------------------------------------------
svn:eol-style = native