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 2013/11/11 21:47:05 UTC
svn commit: r1540840 - in /db/derby/docs/branches/10.10/src/adminguide:
cadminssladmin.dita cadminsslclient.dita cadminsslkeys.dita
cadminsslserver.dita radmindrdakeepalive.dita
Author: chaase3
Date: Mon Nov 11 20:47:05 2013
New Revision: 1540840
URL: http://svn.apache.org/r1540840
Log:
DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element
Merged DERBY-6379-adminleftovers.diff to 10.10 doc branch from trunk revision 1540836.
Modified:
db/derby/docs/branches/10.10/src/adminguide/cadminssladmin.dita
db/derby/docs/branches/10.10/src/adminguide/cadminsslclient.dita
db/derby/docs/branches/10.10/src/adminguide/cadminsslkeys.dita
db/derby/docs/branches/10.10/src/adminguide/cadminsslserver.dita
db/derby/docs/branches/10.10/src/adminguide/radmindrdakeepalive.dita
Modified: db/derby/docs/branches/10.10/src/adminguide/cadminssladmin.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.10/src/adminguide/cadminssladmin.dita?rev=1540840&r1=1540839&r2=1540840&view=diff
==============================================================================
--- db/derby/docs/branches/10.10/src/adminguide/cadminssladmin.dita (original)
+++ db/derby/docs/branches/10.10/src/adminguide/cadminssladmin.dita Mon Nov 11 20:47:05 2013
@@ -19,38 +19,32 @@ limitations under the License.
-->
<concept id="cadminssladmin" xml:lang="en-us">
<title>Other server commands</title>
+<shortdesc>The other server commands (<codeph>shutdown</codeph>,
+<codeph>ping</codeph>, <codeph>sysinfo</codeph>, <codeph>runtimeinfo</codeph>,
+<codeph>logconnections</codeph>, <codeph>maxthreads</codeph>,
+<codeph>timeslice</codeph>, <codeph>trace</codeph>, and
+<codeph>tracedirectory</codeph>) are implemented as clients, and they behave
+exactly as clients with regards to SSL.</shortdesc>
<prolog><metadata>
<keywords><indexterm>Network Server<indexterm>SSL</indexterm></indexterm><indexterm>Network Server<indexterm>TLS</indexterm></indexterm><indexterm>SSL</indexterm><indexterm>TLS</indexterm></keywords>
</metadata></prolog>
-
<conbody>
<section>
-<p>The other server commands (<codeph>shutdown</codeph>,
-<codeph>ping</codeph>, <codeph>sysinfo</codeph>,
-<codeph>runtimeinfo</codeph>, <codeph>logconnections</codeph>,
-<codeph>maxthreads</codeph>, <codeph>timeslice</codeph>,
-<codeph>trace</codeph>, <codeph>tracedirectory</codeph>) are
-implemented as <xref
-href="cadminsslclient.dita#cadminsslclient">clients</xref>, and they
-behave exactly as clients with regards to SSL. The SSL mode is set
-with the property <codeph>derby.drda.sslMode</codeph> or the server
-command option <codeph>-ssl</codeph>.
-</p>
+<p>See <xref href="cadminsslclient.dita#cadminsslclient"></xref> for more
+information.</p>
+<p>The SSL mode is set with the property <codeph>derby.drda.sslMode</codeph> or
+the server command option <codeph>-ssl</codeph>.</p>
</section>
-
<example><title>Examples</title>
-<codeblock>java -jar derbyrun.jar server shutdown -ssl basic</codeblock>
-<p>will shut down an SSL-enabled server. </p>
-<p>
-Similarly, if you have <codeph>peerAuthentication</codeph> on both sides, use the
-following command:
-</p>
-<codeblock>java -Djavax.net.ssl.keyStore=clientKeyStore.key \
+<p>The following command will shut down an SSL-enabled server:</p>
+<codeblock><b>java -jar derbyrun.jar server shutdown -ssl basic</b></codeblock>
+<p>Similarly, if you have <codeph>peerAuthentication</codeph> on both sides, use
+the following command:</p>
+<codeblock><b>java -Djavax.net.ssl.keyStore=clientKeyStore.key \
-Djavax.net.ssl.keyStorePassword=qwerty \
-Djavax.net.ssl.trustStore=clientTrustStore.key \
-Djavax.net.ssl.trustStorePassword=qwerty \
- -jar derbyrun.jar server shutdown -ssl peerAuthentication</codeblock>
+ -jar derbyrun.jar server shutdown -ssl peerAuthentication</b></codeblock>
</example>
-
</conbody>
-</concept>
\ No newline at end of file
+</concept>
Modified: db/derby/docs/branches/10.10/src/adminguide/cadminsslclient.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.10/src/adminguide/cadminsslclient.dita?rev=1540840&r1=1540839&r2=1540840&view=diff
==============================================================================
--- db/derby/docs/branches/10.10/src/adminguide/cadminsslclient.dita (original)
+++ db/derby/docs/branches/10.10/src/adminguide/cadminsslclient.dita Mon Nov 11 20:47:05 2013
@@ -19,29 +19,26 @@ limitations under the License.
-->
<concept id="cadminsslclient" xml:lang="en-us">
<title>Running the client with SSL/TLS</title>
+<shortdesc>Basic SSL encryption on the client is enabled either by the URL
+attribute <codeph>ssl</codeph>, the property <codeph>ssl</codeph>, or the
+datasource attribute <codeph>ssl</codeph> set to
+<codeph>basic</codeph>.</shortdesc>
<prolog><metadata>
<keywords><indexterm>Network Client<indexterm>SSL</indexterm></indexterm><indexterm>Network Client<indexterm>TLS</indexterm></indexterm><indexterm>SSL</indexterm><indexterm>TLS</indexterm></keywords>
</metadata></prolog>
<conbody>
-<p>Basic SSL encryption on the client is enabled either by the URL attribute
-<codeph>ssl</codeph>, the property <codeph>ssl</codeph> or the
-datasource attribute <codeph>ssl</codeph> set to <codeph>basic</codeph>.</p>
-
<example><title>Example</title>
<codeblock>Connection c =
getConnection("jdbc:derby://myhost:1527/db;ssl=basic");</codeblock>
</example>
-
-<section>
-<title>Running a client which authenticates the server</title>
+<section><title>Running a client which authenticates the server</title>
<p>If the client wants to authenticate the server, then the client's
<i>trust store</i> must contain the server's certificate. See <xref
href="cadminsslkeys.dita#cadminsslkeys"></xref>.</p>
-
-<p>Client SSL with server authentication is enabled by the URL
-attribute <codeph>ssl</codeph> or the property <codeph>ssl</codeph>
-set to <codeph>peerAuthentication</codeph>. In addition, the system
-properties <codeph>javax.net.ssl.trustStore</codeph> and
+<p>Client SSL with server authentication is enabled by the URL attribute
+<codeph>ssl</codeph> or the property <codeph>ssl</codeph> set to
+<codeph>peerAuthentication</codeph>. In addition, the system properties
+<codeph>javax.net.ssl.trustStore</codeph> and
<codeph>javax.net.ssl.trustStorePassword</codeph> need to be set.</p>
</section>
<example><title>Example</title>
@@ -50,30 +47,24 @@ properties <codeph>javax.net.ssl.trustSt
Connection c =
getConnection("jdbc:derby://myhost:1527/db;ssl=peerAuthentication");</codeblock>
</example>
-
-<section>
-<title>Running the client when the server does client authentication</title>
-<p>If the server does client authentication, the client will need a key
-pair and a client certificate which is installed in the server's
-<i>trust store</i>, See <xref
-href="cadminsslkeys.dita#cadminsslkeys"></xref>.</p>
+<section><title>Running the client when the server does client
+authentication</title>
+<p>If the server does client authentication, the client will need a key pair and
+a client certificate which is installed in the server's <i>trust store</i>. See
+<xref href="cadminsslkeys.dita#cadminsslkeys"></xref>.</p>
<p>The client needs to set <codeph>javax.net.ssl.keyStore</codeph> and
<codeph>javax.net.ssl.keyStorePassword</codeph>.</p>
</section>
-
<example><title>Example</title>
<codeblock> System.setProperty("javax.net.ssl.keyStore","clientKeyStore.key");
System.setProperty("javax.net.ssl.keyStorePassword","qwerty");
Connection c =
getConnection("jdbc:derby://myhost:1527/db;ssl=basic");</codeblock>
</example>
-
-<section>
-<title>Running the client when both parties do peer
+<section><title>Running the client when both parties do peer
authentication</title>
<p>This is a combination of the two last variants.</p>
</section>
-
<example><title>Example</title>
<codeblock> System.setProperty("javax.net.ssl.keyStore","clientKeyStore.key");
System.setProperty("javax.net.ssl.keyStorePassword","qwerty");
@@ -82,7 +73,5 @@ authentication</title>
Connection c =
getConnection("jdbc:derby://myhost:1527/db;ssl=peerAuthentication");</codeblock>
</example>
-
</conbody>
</concept>
-
Modified: db/derby/docs/branches/10.10/src/adminguide/cadminsslkeys.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.10/src/adminguide/cadminsslkeys.dita?rev=1540840&r1=1540839&r2=1540840&view=diff
==============================================================================
--- db/derby/docs/branches/10.10/src/adminguide/cadminsslkeys.dita (original)
+++ db/derby/docs/branches/10.10/src/adminguide/cadminsslkeys.dita Mon Nov 11 20:47:05 2013
@@ -19,82 +19,64 @@ limitations under the License.
-->
<concept id="cadminsslkeys" xml:lang="en-us">
<title>Key and certificate handling</title>
+<shortdesc>For SSL operation, the server always needs a key pair. If the server
+runs in peer authentication mode (the server authenticates the clients),
+each client needs its own key pair. In general, if one end of the communication
+wants to authenticate its partner, the first end needs to install a certificate
+generated by the partner.</shortdesc>
<prolog><metadata>
<keywords><indexterm>Network Server<indexterm>SSL</indexterm></indexterm><indexterm>Network Server<indexterm>TLS</indexterm></indexterm><indexterm>SSL<indexterm>key</indexterm><indexterm>certificate</indexterm></indexterm><indexterm>TLS</indexterm></keywords>
</metadata></prolog>
-
<conbody>
-<p>
-For SSL operation, the server always needs a key pair. If the server
-runs in peer authentication mode (the server authenticates the
-clients), then each client needs its own key pair. In general, if one
-end of the communication wants to authenticate its partner, then the
-first end needs to install a certificate generated by the partner.
-</p>
-<p>
-The key pair is located in a file which is called a <i>key store</i>
-and the JDK's SSL provider needs the system properties
+<p>The key pair is located in a file which is called a <i>key store</i>, and the
+JDK's SSL provider needs the system properties
<codeph>javax.net.ssl.keyStore</codeph> and
-<codeph>javax.net.ssl.keyStorePassword</codeph> to access the key
-store.
-</p>
-<p>
-The certificates of trusted parties are installed in a file called a
+<codeph>javax.net.ssl.keyStorePassword</codeph> to access the keystore.</p>
+<p>The certificates of trusted parties are installed in a file called a
<i>trust store</i>. The JDK's SSL provider needs the system properties
<codeph>javax.net.ssl.trustStore</codeph> and
<codeph>javax.net.ssl.trustStorePassword</codeph> to access the trust
-store.
-</p>
-
-<section>
-<title>Key pair generation</title>
+store.</p>
+<section><title>Key pair generation</title>
<p>Key pairs are generated with <codeph>keytool -genkey</codeph>. The
simplest way to generate a key pair is to do the following:</p>
-<codeblock>keytool -genkey <alias> -keystore <keystore></codeblock>
-<p><codeph>keytool</codeph> will prompt for needed information like
-identity details and passwords. </p>
-<p>
-Consult the JDK documentation for more information on
-<codeph>keytool</codeph>.
-</p>
+<codeblock><b>keytool -genkey <i>alias</i> -keystore <i>keystore</i></b></codeblock>
+<p><codeph>keytool</codeph> will prompt for needed information, such as
+identity details and passwords.</p>
+<p>Consult the JDK documentation for more information on
+<codeph>keytool</codeph>.</p>
</section>
-
-<section>
-<title>Certificate generation</title>
+<section><title>Certificate generation</title>
<p>Certificates are generated with <codeph>keytool -export</codeph>
as follows:</p>
-<codeblock>keytool -export -alias <alias> -keystore <keystore> \
- -rfc -file <certificate file></codeblock>
+<codeblock><b>keytool -export -alias <i>alias</i> -keystore <i>keystore</i> \
+ -rfc -file <i>certificate-file</i></b></codeblock>
<p>The certificate file may then be distributed to the relevant parties.</p>
</section>
-
<section>
<title>Certificate installation</title>
<p>Installation of a certificate in a trust store is done with
<codeph>keytool -import</codeph> as follows:</p>
-<codeblock>keytool -import -alias <alias> -file <certificate file> \
- -keystore <trust store></codeblock>
+<codeblock><b>keytool -import -alias <i>alias</i> -file <i>certificate-file</i> \
+ -keystore <i>truststore</i></b></codeblock>
</section>
-
-<example>
-<title>Examples</title>
+<example><title>Examples</title>
<p>Generate the server key pair:</p>
-<codeblock>keytool -genkey -alias myDerbyServer -keystore serverKeyStore.key</codeblock>
+<codeblock><b>>keytool -genkey -alias myDerbyServer -keystore serverKeyStore.key</b></codeblock>
<p>Generate a server certificate:</p>
-<codeblock>keytool -export -alias myDerbyServer -keystore serverKeyStore.key \
- -rfc -file myServer.cert</codeblock>
+<codeblock><b>keytool -export -alias myDerbyServer -keystore serverKeyStore.key \
+ -rfc -file myServer.cert</b></codeblock>
<p>Generate a client key pair:</p>
-<codeblock>keytool -genkey -alias aDerbyClient -keystore clientKeyStore.key</codeblock>
+<codeblock><b>keytool -genkey -alias aDerbyClient -keystore clientKeyStore.key</b></codeblock>
<p>Generate a client certficate:</p>
-<codeblock>keytool -export -alias aDerbyClient -keystore clientKeyStore.key \
- -rfc -file aClient.cert</codeblock>
+<codeblock><b>keytool -export -alias aDerbyClient -keystore clientKeyStore.key \
+ -rfc -file aClient.cert</b></codeblock>
<p>Install a client certificate in the server's trust store:</p>
-<codeblock>keytool -import -alias aDerbyClient -file aClient.cert
- -keystore serverTrustStore.key</codeblock>
+<codeblock><b>keytool -import -alias aDerbyClient -file aClient.cert
+ -keystore serverTrustStore.key</b></codeblock>
<p>Install the server certificate in a client's trust store:</p>
-<codeblock>keytool -import -alias myDerbyServer -file myServer.cert
- -keystore clientTrustStore.key</codeblock>
+<codeblock><b>keytool -import -alias myDerbyServer -file myServer.cert
+ -keystore clientTrustStore.key</b></codeblock>
</example>
-
</conbody>
-</concept>
\ No newline at end of file
+</concept>
Modified: db/derby/docs/branches/10.10/src/adminguide/cadminsslserver.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.10/src/adminguide/cadminsslserver.dita?rev=1540840&r1=1540839&r2=1540840&view=diff
==============================================================================
--- db/derby/docs/branches/10.10/src/adminguide/cadminsslserver.dita (original)
+++ db/derby/docs/branches/10.10/src/adminguide/cadminsslserver.dita Mon Nov 11 20:47:05 2013
@@ -19,59 +19,47 @@ limitations under the License.
-->
<concept id="cadminsslserver" xml:lang="en-us">
<title>Starting the server with SSL/TLS</title>
+<shortdesc>For server SSL/TLS, a server key pair needs to be generated. If the
+server is going to do client authentication, the client certificates need to be
+installed in the trust store.</shortdesc>
<prolog><metadata>
<keywords><indexterm>Network Server<indexterm>SSL</indexterm></indexterm><indexterm>Network Server<indexterm>TLS</indexterm></indexterm><indexterm>SSL</indexterm><indexterm>TLS</indexterm></keywords>
</metadata></prolog>
-
<conbody>
-<p>
-For server SSL/TLS, a server key pair needs to be generated. If the
-server is going to do client authentication, the client sertificates
-need to be installed in the trust store. These operations are
-described in <xref href="cadminsslkeys.dita#cadminsslkeys"></xref>.
-</p>
+<p>These operations are described in
+<xref href="cadminsslkeys.dita#cadminsslkeys"></xref>.</p>
<p>SSL at the server side is activated with the property
<codeph>derby.drda.sslMode</codeph> (default off) or the
-<codeph>-ssl</codeph> option for the server start command.
-</p>
-
-<section>
-<title>Starting the server with basic SSL encryption</title>
+<codeph>-ssl</codeph> option for the server start command.</p>
+<section><title>Starting the server with basic SSL encryption</title>
<p>When the SSL mode is set to <codeph>basic</codeph>, the server will
only accept SSL encrypted connections.</p>
-
<p>The properties <codeph>javax.net.ssl.keyStore</codeph> and
<codeph>javax.net.ssl.keyStorePassword</codeph> need to be set with
the proper values.</p>
</section>
<example><title>Example</title>
-<codeblock>java -Djavax.net.ssl.keyStore=serverKeyStore.key \
+<codeblock><b>java -Djavax.net.ssl.keyStore=serverKeyStore.key \
-Djavax.net.ssl.keyStorePassword=qwerty \
- -jar derbyrun.jar server start -ssl basic</codeblock>
+ -jar derbyrun.jar server start -ssl basic</b></codeblock>
</example>
-
-<section>
-<title>Starting a server which authenticates clients</title>
-
-<p>When the server's SSL mode is set to
-<codeph>peerAuthentication</codeph>, then the server authenticates its
-clients' identity in addition to encrypting network traffic. In this
-situation, the server's <i>trust store</i> must contain a certificate for
-each client which will connect.
-</p>
+<section><title>Starting a server which authenticates clients</title>
+<p>When the server's SSL mode is set to <codeph>peerAuthentication</codeph>,
+the server authenticates its clients' identity in addition to encrypting network
+traffic. In this situation, the server's <i>trust store</i> must contain a
+certificate for each client which will connect.</p>
<p>The <codeph>javax.net.ssl.trustStore</codeph> and
-<codeph>javax.net.ssl.trustStorePassword</codeph> need to be set in
-addition to the properties above.</p>
+<codeph>javax.net.ssl.trustStorePassword</codeph> need to be set in addition to
+the properties above.</p>
<p>See <xref href="cadminsslclient.dita#cadminsslclient"></xref> for
client settings when the server does client authentication.</p>
</section>
<example><title>Example</title>
-<codeblock>java -Djavax.net.ssl.keyStore=serverKeyStore.key \
+<codeblock><b>java -Djavax.net.ssl.keyStore=serverKeyStore.key \
-Djavax.net.ssl.keyStorePassword=qwerty \
-Djavax.net.ssl.trustStore=serverTrustStore.key \
-Djavax.net.ssl.trustStorePassword=qwerty \
- -jar derbyrun.jar server start -ssl peerAuthentication</codeblock>
+ -jar derbyrun.jar server start -ssl peerAuthentication</b></codeblock>
</example>
-
</conbody>
-</concept>
\ No newline at end of file
+</concept>
Modified: db/derby/docs/branches/10.10/src/adminguide/radmindrdakeepalive.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.10/src/adminguide/radmindrdakeepalive.dita?rev=1540840&r1=1540839&r2=1540840&view=diff
==============================================================================
--- db/derby/docs/branches/10.10/src/adminguide/radmindrdakeepalive.dita (original)
+++ db/derby/docs/branches/10.10/src/adminguide/radmindrdakeepalive.dita Mon Nov 11 20:47:05 2013
@@ -43,7 +43,7 @@ connections, set this property to <codep
<p>True.</p>
</section>
<example><title>Example</title>
-<codeblock>derby.drdra.keepAlive=false </codeblock>
+<codeblock><b>derby.drdra.keepAlive=false</b></codeblock>
</example>
<section><title>Static or dynamic</title>
<p>Static. You must restart the Network Server for changes to take effect.</p>