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 fu...@apache.org on 2006/08/19 01:29:42 UTC
svn commit: r432775 - in /db/derby/docs/trunk/src:
devguide/cdevcsecure60146.dita devguide/derbydev.ditamap
devguide/tdevdvlp40140.dita ref/refderby.ditamap
ref/rrefattribencryptkey.dita
Author: fuzzylogic
Date: Fri Aug 18 16:29:41 2006
New Revision: 432775
URL: http://svn.apache.org/viewvc?rev=432775&view=rev
Log:
DERBY-1622: Add documentation for encrypting databases using encryptionKey
connection attribute.
Committed for Laura Stewart <sc...@gmail.com>
Added:
db/derby/docs/trunk/src/ref/rrefattribencryptkey.dita (with props)
Modified:
db/derby/docs/trunk/src/devguide/cdevcsecure60146.dita
db/derby/docs/trunk/src/devguide/derbydev.ditamap
db/derby/docs/trunk/src/devguide/tdevdvlp40140.dita
db/derby/docs/trunk/src/ref/refderby.ditamap
Modified: db/derby/docs/trunk/src/devguide/cdevcsecure60146.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevcsecure60146.dita?rev=432775&r1=432774&r2=432775&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevcsecure60146.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevcsecure60146.dita Fri Aug 18 16:29:41 2006
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
-
+
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
"../dtd/concept.dtd">
<!--
@@ -20,35 +20,46 @@
-->
<concept id="cdevcsecure60146" xml:lang="en-us">
<title>Booting an encrypted database</title>
-<shortdesc>Once you have created an encrypted database, you must supply the
-boot password to reboot it.</shortdesc>
+<shortdesc>If you create an encrypted database using the <i>bootPassword</i> attribute,
+you must specify the boot password to reboot the database. If you create an
+encrypted database using the <i>encryptionKey</i> attribute, you must specify
+the <i>encryptionKey</i> to reboot the database.</shortdesc>
<prolog><metadata>
-<keywords><indexterm>Encrypted databases<indexterm>booting</indexterm></indexterm>
+<keywords><indexterm>encrypted databases<indexterm>booting</indexterm></indexterm>
</keywords>
</metadata></prolog>
<conbody>
<p>Encrypted databases cannot be booted automatically along with all other
system databases on system startup (see <i>"derby.system.bootAll" </i> in <cite><ph
conref="devconrefs.dita#pub/cittuning"></ph></cite>). Instead, you boot encrypted
-databases when you first connect to them.</p>
-<p>For example, to access an encrypted database called <i>wombat,</i> created
-with the boot password clo760uds2caPe<i>,</i> you would use the following
-connection URL:</p>
-<codeblock>jdbc:derby:wombat;bootPassword=clo760uds2caPe</codeblock>
-<p>Once the database is booted, all connections can access the database without
+databases when you first connect to the database.</p>
+<p><dl><dlentry>
+<dt>Booting a database with the <i>bootPassword</i> attribute</dt>
+<dd>To access an encrypted database called <codeph>wombat</codeph> that was
+created with the boot password <codeph>clo760uds2caPe</codeph>, use the following
+connection URL:<codeblock>jdbc:derby:wombat;bootPassword=clo760uds2caPe</codeblock></dd>
+</dlentry><dlentry>
+<dt>Booting a database with the <i>encryptionKey</i> attribute</dt>
+<dd>To access an encrypted database called <codeph>flintstone</codeph> that
+was created with the <codeph>encryptionKey=c566bab9ee8b62a5ddb4d9229224c678</codeph> and
+with the <codeph>encryptionAlgorithm=AES/CBC/NoPadding</codeph>, use the following
+connection URL: <codeblock>jdbc:derby:flintstone;encryptionAlgorithm=AES/CBC/NoPadding;encryptionKey=c566bab9ee8b62a5ddb4d9229224c678 </codeblock
+></dd>
+</dlentry></dl></p>
+<p>After the database is booted, all connections can access the database without
the boot password. Only a connection that boots the database requires the
key.</p>
-<p>For example, the following connections would boot the database and thus
-require the boot password:</p>
-<ul>
+<p>For example, the following connections would boot the database and require
+the boot password or encryption key,depending on what mechanism was used to
+encrypt the database originally:<ul>
<li>The first connection to the database in the JVM session</li>
<li>The first connection to the database after the database has been explicitly
shut down</li>
<li>The first connection to the database after the system has been shut down
and then rebooted</li>
-</ul>
-<note>The boot password is not meant to prevent unauthorized connections to
-the database once it has been booted. To protect a database once it has been
-booted, turn on user authentication (see <xref href="cdevcsecure42374.dita#cdevcsecure42374"></xref>).</note>
+</ul></p>
+<note>The boot password and the encryption key are not meant to prevent unauthorized
+connections to the database after the database is booted. To protect a database
+after it has been booted, turn on user authentication (see <xref href="cdevcsecure42374.dita#cdevcsecure42374"></xref>).</note>
</conbody>
</concept>
Modified: db/derby/docs/trunk/src/devguide/derbydev.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/derbydev.ditamap?rev=432775&r1=432774&r2=432775&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/derbydev.ditamap (original)
+++ db/derby/docs/trunk/src/devguide/derbydev.ditamap Fri Aug 18 16:29:41 2006
@@ -1,4 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
+
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN"
"map.dtd">
<!--
@@ -329,6 +330,18 @@
</relrow>
<relrow>
<relcell>
+<topicref href="tdevdvlpcreateencryptdbextkey.dita" navtitle="Creating an encrypted database with an external key">
+</topicref>
+</relcell>
+<relcell>
+<topicref href="tdevdvlp40140.dita" navtitle="Booting an encrypted database">
+</topicref>
+<topicref href="tdevdvlp14496.dita" navtitle="Encrypting a database when you create it">
+</topicref>
+</relcell>
+</relrow>
+<relrow>
+<relcell>
<topicref href="tdevdvlp40140.dita" navtitle="Booting an encrypted database">
</topicref>
</relcell>
@@ -2056,6 +2069,8 @@
<topicref href="tdevdvlp12233.dita" navtitle="Providing a user name and password">
</topicref>
<topicref href="tdevdvlp14496.dita" navtitle="Encrypting a database when you create it">
+</topicref>
+<topicref href="tdevdvlpcreateencryptdbextkey.dita" navtitle="Creating an encrypted database with an external key">
</topicref>
<topicref href="tdevdvlp40140.dita" navtitle="Booting an encrypted database">
</topicref>
Modified: db/derby/docs/trunk/src/devguide/tdevdvlp40140.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/tdevdvlp40140.dita?rev=432775&r1=432774&r2=432775&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/tdevdvlp40140.dita (original)
+++ db/derby/docs/trunk/src/devguide/tdevdvlp40140.dita Fri Aug 18 16:29:41 2006
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
-
+
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN"
"../dtd/task.dtd">
<!--
@@ -20,14 +20,30 @@
-->
<task id="tdevdvlp40140" xml:lang="en-us">
<title>Booting an encrypted database</title>
-<shortdesc>You must specify the encryption key with the <i>bootPassword=key</i> attribute
-for an encrypted database when you boot it (which is the first time you connect
-to it within a JVM session or after shutting it down within the same JVM session).</shortdesc>
+<shortdesc>You must specify several attributes in the URL when you boot an
+encrypted database. You must specify these attributes the first time that
+you connect to the database within a JVM session, or after you shut the database
+down within the same JVM session.</shortdesc>
<prolog><metadata>
-<keywords><indexterm>Encrypted databases<indexterm>booting</indexterm></indexterm>
+<keywords><indexterm>encrypted databases<indexterm>booting</indexterm></indexterm>
</keywords>
</metadata></prolog>
<taskbody>
-<context> <codeblock>jdbc:derby:encryptedDB;bootPassword=DBpassword</codeblock></context>
+<context><p>To boot an existing encrypted database: </p></context>
+<steps>
+<step><cmd>The attribute that you specify depends on how the database was
+originally encrypted: </cmd>
+<choices>
+<choice>If the database was encrypted using the bootPassword mechanism, specify
+the <i>bootPassword</i> attribute. For example:<codeblock>jdbc:derby:wombat;bootPassword=clo760uds2caPe </codeblock></choice>
+<choice>If the database was encrypted using an external key, specify the <i>encryptionKey</i> attribute.
+For example: <codeblock>jdbc:derby:flintstone;encryptionAlgorithm=AES/CBC/NoPadding;encryptionKey=c566bab9ee8b62a5ddb4d9229224c678 </codeblock></choice>
+</choices>
+</step>
+</steps>
+<postreq>If the algorithm that was used when the database was created is not
+the default algorithm, you must also specify the <i>encryptionAlgorithm</i> attribute.
+The default encryption algorithm used by <ph conref="devconrefs.dita#prod/productshortname"></ph> is
+DES/CBC/NoPadding.</postreq>
</taskbody>
</task>
Modified: db/derby/docs/trunk/src/ref/refderby.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/refderby.ditamap?rev=432775&r1=432774&r2=432775&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/refderby.ditamap (original)
+++ db/derby/docs/trunk/src/ref/refderby.ditamap Fri Aug 18 16:29:41 2006
@@ -49,6 +49,10 @@
<topicref href="rrefsqljgrant.dita" navtitle="GRANT statement "></topicref>
</relcell>
</relrow>
+<relrow>
+<relcell></relcell>
+<relcell></relcell>
+</relrow>
</reltable>
<topicref href="rrefcopyright.dita" navtitle="Copyright"></topicref>
<topicref collection-type="family" href="crefmpref1002477.dita" navtitle="About this guide">
@@ -500,6 +504,7 @@
<topicref href="rrefattrib17246.dita" navtitle="databaseName=nameofDatabase">
</topicref>
<topicref href="rrefattrib15290.dita" navtitle="dataEncryption=true"></topicref>
+<topicref href="rrefattribencryptkey.dita" navtitle="encryptionKey=key"></topicref>
<topicref href="rrefattrib88843.dita" navtitle="encryptionProvider=providerName">
</topicref>
<topicref href="rrefattrib60346.dita" navtitle="encryptionAlgorithm=algorithm">
Added: db/derby/docs/trunk/src/ref/rrefattribencryptkey.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefattribencryptkey.dita?rev=432775&view=auto
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefattribencryptkey.dita (added)
+++ db/derby/docs/trunk/src/ref/rrefattribencryptkey.dita Fri Aug 18 16:29:41 2006
@@ -0,0 +1,52 @@
+<?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="rrefattribencryptkey" xml:lang="en-us">
+<title>encryptionKey=<key></title>
+<prolog><metadata>
+<keywords><indexterm>encryptionKey= <key></indexterm><indexterm>encrypting
+databases<indexterm>encryption key</indexterm></indexterm><indexterm>databases<indexterm>attributes,
+encryption key</indexterm></indexterm><indexterm>attributes<indexterm>encryptionKey</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<refbody>
+<section><title>Function</title><p>Specifies the external key to use to: <ul>
+<li>Encrypt a new database</li>
+<li>Configure an existing database for encryption</li>
+<li>Boot an existing encrypted database</li>
+</ul>Your application must provide the encryption key.</p></section>
+<section><title>Combining with other attributes</title><p>When creating a
+new database, you must combine the <i>encryptionKey</i> attribute with the <i>create=true</i> and <i>dataEncryption=true</i> attributes. </p><p>When
+you configure an existing database for encryption, the <i>encryptionKey</i> attribute
+must be combined with the <i>dataEncryption=true</i> attribute. If the algorithm
+that was used when the database was created is not the default algorithm,
+you must also specify the <i>encryptionAlgorithm</i> attribute.</p><p>When
+booting an existing encrypted database, you must also specify the <i>encryptionAlgorithm</i> attribute
+if the algorithm that was used when the database was created is not the default
+algorithm. </p><p>The default encryption algorithm used by <ph conref="refconrefs.dita#prod/productshortname"></ph> is
+DES/CBC/NoPadding.</p> </section>
+<example><title>Examples</title><codeblock><b><ph>-- create a new encrypted database</ph>
+ jdbc:derby:newDB;create=true;dataEncryption=true;encryptionAlgorithm=DES/CBC/NoPadding;encryptionKey=6162636465666768
+<ph>-- configure an existing database for encryption</ph>
+ jdbc:derby:salesdb;dataEncryption=true;encryptionKey=6162636465666768
+<ph>-- boot an encrypted database</ph>
+ jdbc:derby:encryptedDB;encryptionKey=6162636465666768</b></codeblock> </example>
+</refbody>
+</reference>
Propchange: db/derby/docs/trunk/src/ref/rrefattribencryptkey.dita
------------------------------------------------------------------------------
svn:eol-style = native