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 2014/05/19 22:09:36 UTC
svn commit: r1596037 [8/13] - in /db/derby/docs/trunk: ./ src/security/
Propchange: db/derby/docs/trunk/src/security/csecputstart.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/security/csecputstop.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/csecputstop.dita?rev=1596037&view=auto
==============================================================================
--- db/derby/docs/trunk/src/security/csecputstop.dita (added)
+++ db/derby/docs/trunk/src/security/csecputstop.dita Mon May 19 20:09:33 2014
@@ -0,0 +1,33 @@
+<?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="csecputstop" xml:lang="en-us">
+<title>Stopping the secured Network Server</title>
+<shortdesc>Now you can bring down the secured server.</shortdesc>
+<conbody>
+<codeblock><b>java -Djavax.net.ssl.trustStore=/Users/me/vault/ClientTrustStore \
+-Djavax.net.ssl.trustStorePassword=secretClientTrustStorePassword \
+-Djavax.net.ssl.keyStore=/Users/me/vault/ClientKeyStore \
+-Djavax.net.ssl.keyStorePassword=secretClientPassword \
+org.apache.derby.drda.NetworkServerControl shutdown -p 8246 \
+-user mchrysta -password mchrysta \
+-ssl peerAuthentication</b></codeblock>
+</conbody>
+</concept>
Propchange: db/derby/docs/trunk/src/security/csecputstop.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/security/csecputtogether.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/csecputtogether.dita?rev=1596037&view=auto
==============================================================================
--- db/derby/docs/trunk/src/security/csecputtogether.dita (added)
+++ db/derby/docs/trunk/src/security/csecputtogether.dita Mon May 19 20:09:33 2014
@@ -0,0 +1,29 @@
+<?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="csecputtogether" xml:lang="en-us">
+<title>Putting it all together</title>
+<shortdesc>This section shows how to enable all available
+<ph conref="../conrefs.dita#prod/productshortname"></ph> defenses.</shortdesc>
+<conbody>
+<p>This example uses Java security, SSL encryption, NATIVE authentication, and both
+coarse-grained and fine-grained authorization.</p>
+</conbody>
+</concept>
Propchange: db/derby/docs/trunk/src/security/csecputtogether.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/security/csecrunpolicy.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/csecrunpolicy.dita?rev=1596037&view=auto
==============================================================================
--- db/derby/docs/trunk/src/security/csecrunpolicy.dita (added)
+++ db/derby/docs/trunk/src/security/csecrunpolicy.dita Mon May 19 20:09:33 2014
@@ -0,0 +1,51 @@
+<?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="csecrunpolicy" xml:lang="en-us">
+<title>Using a Java security policy file</title>
+<shortdesc>You can bring up the Network Server with a security manager and a
+customized policy file.</shortdesc>
+<prolog><metadata>
+<keywords>
+<indexterm>Java security<indexterm>using policy file</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<conbody>
+<section>
+<p>The following command line starts the Network Server with the policy file
+created in <xref href="rsecpolicysample.dita#rsecpolicysample"></xref>. It tells
+the server to authenticate users with the NATIVE credentials stored in the
+<codeph>testdb</codeph> database created in
+<xref href="cseccsecurenativeauth.dita"/>.</p>
+<codeblock><b>java -Djava.security.manager \
+-Djava.security.policy=/Users/me/myServer.policy \
+-Dderby.authentication.provider=NATIVE:testdb \
+org.apache.derby.drda.NetworkServerControl start -p 8246</b></codeblock>
+<p>If you start the Network Server without specifying a security manager, the
+Network Server will install a default Java security manager that enforces a
+Basic policy.</p>
+<p>To shut down the Network Server, use the following command:</p>
+<codeblock><b>java org.apache.derby.drda.NetworkServerControl shutdown \
+-p 8246 -user tquist -password tquist</b></codeblock>
+<p>You will need to shut down the server before using the examples in
+<xref href="csecputtogether.dita"/>.</p>
+</section>
+</conbody>
+</concept>
Propchange: db/derby/docs/trunk/src/security/csecrunpolicy.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/security/csecssl.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/csecssl.dita?rev=1596037&view=auto
==============================================================================
--- db/derby/docs/trunk/src/security/csecssl.dita (added)
+++ db/derby/docs/trunk/src/security/csecssl.dita Mon May 19 20:09:33 2014
@@ -0,0 +1,101 @@
+<?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="csecssl" xml:lang="en-us">
+<title>Configuring SSL/TLS</title>
+<shortdesc>By default, network traffic travels in cleartext between
+<ph conref="../conrefs.dita#prod/productshortname"></ph> clients and
+servers.</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>By using a man-in-the-middle ploy, a clever attacker can read all of the
+string data shipped to and from the server. By knowing the
+<ph conref="../conrefs.dita#prod/productshortname"></ph> wire protocol, a clever
+attacker can read numeric data too. Even worse, the man-in-the-middle can change
+the data while it is traveling between the client and the server.</p>
+<p>Fortunately, <ph conref="../conrefs.dita#prod/productshortname"></ph> can
+encrypt network traffic using the SSL/TLS (Secure Socket Layer/Transport Layer
+Security) logic supplied with the virtual machine. As a side effect, SSL/TLS
+raises an extra authentication hurdle too, involving
+<i>peer authentication</i>.</p>
+<p>The term <i>peer</i> is used for the other part of the server-client
+communication: the server's peer is the client, and the client's peer is the
+server.</p>
+<p>SSL/TLS for <ph conref="../conrefs.dita#prod/productshortname"></ph> (both
+for client and for server) operates in three possible modes:</p>
+<dl>
+<dlentry>
+<dt>off</dt>
+<dd>The default, no SSL/TLS encryption</dd>
+</dlentry>
+<dlentry>
+<dt>basic</dt>
+<dd>SSL/TLS encryption, no peer authentication</dd>
+</dlentry>
+<dlentry>
+<dt>peerAuthentication</dt>
+<dd>SSL/TLS encryption and peer authentication</dd>
+</dlentry>
+</dl>
+<p>Peer authentication may be set on the server, on the client, or on both. Peer
+authentication means that the other side of the SSL/TLS connection is
+authenticated based on a trusted certificate installed locally.</p>
+<p>Before using this encryption technology, you will want to familiarize
+yourself with SSL/TLS concepts such as key pairs and certificates, and with the
+JDK's <codeph>keytool</codeph> application. You can find useful overviews of
+SSL/TLS at Apache and Wikipedia
+(<xref format="html" href="http://httpd.apache.org/docs/2.0/ssl/ssl_intro.html"
+scope="external"/> and
+<xref format="html" href="http://en.wikipedia.org/wiki/Secure_Sockets_Layer"
+scope="external"/>, respectively). You can find <codeph>keytool</codeph>
+documentation for Unix and for Windows at <xref format="html"
+href="http://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html"
+scope="external"/> and <xref format="html"
+href="http://docs.oracle.com/javase/8/docs/technotes/tools/windows/keytool.html"
+scope="external"/>, respectively.</p>
+<p>Network encryption requires the following setup steps:</p>
+<ol>
+<li><b>Client certificates:</b> Each client must generate a client key pair and
+certificate. The client certificates must be loaded into the server's trust
+store.</li>
+<li><b>Server certificate:</b> The server must generate a server key pair and
+certificate. All of the clients must load the server's certificate into their
+respective trust stores.</li>
+<li><b>Server startup:</b> The server must be booted with system properties and a
+startup option that turn on SSL/TLS encryption.</li>
+<li><b>Client startup:</b> The client must be started with system properties that turn
+on SSL/TLS encryption. In addition, an extra attribute is added to the JDBC
+connection URL.</li>
+</ol>
+<p>To use SSL/TLS to encrypt
+<ph conref="../conrefs.dita#prod/productshortname"></ph>'s network traffic, the
+client must have a key store for holding its own public/private key pair. The
+client must also have a trust store for holding the server's certificate. If the
+key store and trust store do not already exist, the <codeph>keytool</codeph>
+program will create them. Suppose that the client stores its public/private key
+pair in <codeph>~/vault/ClientKeyStore</codeph>, and suppose that the client
+stores certificates from other systems in
+<codeph>~/vault/ClientTrustStore</codeph>.</p>
+</conbody>
+</concept>
Propchange: db/derby/docs/trunk/src/security/csecssl.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/security/csecssladmin.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/csecssladmin.dita?rev=1596037&view=auto
==============================================================================
--- db/derby/docs/trunk/src/security/csecssladmin.dita (added)
+++ db/derby/docs/trunk/src/security/csecssladmin.dita Mon May 19 20:09:33 2014
@@ -0,0 +1,49 @@
+<?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="csecssladmin" 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>See <xref href="csecsslclient.dita"/> 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>
+<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</b></codeblock>
+</example>
+</conbody>
+</concept>
Propchange: db/derby/docs/trunk/src/security/csecssladmin.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/security/csecsslbootconn.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/csecsslbootconn.dita?rev=1596037&view=auto
==============================================================================
--- db/derby/docs/trunk/src/security/csecsslbootconn.dita (added)
+++ db/derby/docs/trunk/src/security/csecsslbootconn.dita Mon May 19 20:09:33 2014
@@ -0,0 +1,86 @@
+<?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="csecsslbootconn" xml:lang="en-us">
+<title>Booting the server and connecting to it</title>
+<shortdesc>Finally, boot the server and start the client.</shortdesc>
+<prolog></prolog>
+<conbody>
+<p>The previous three topics covered the first two setup steps described in
+<xref href="csecssl.dita"/>, creating client certificates and creating a server
+certificate, then importing the certificates. This topic describes the remaining
+two steps, server startup and client startup.</p>
+<p>Every time that we bring up the server, we must remember to turn on network
+encryption. We must set four VM properties that declare the locations
+and passwords for the server's key store and trust store:</p>
+<ul>
+<li><codeph>javax.net.ssl.keyStore</codeph></li>
+<li><codeph>javax.net.ssl.keyStorePassword</codeph></li>
+<li><codeph>javax.net.ssl.trustStore</codeph></li>
+<li><codeph>javax.net.ssl.trustStorePassword</codeph></li>
+</ul>
+<p>In addition, we specify the <codeph>-ssl peerAuthentication</codeph> startup
+option. The command to start the server, therefore, looks something like
+this:</p>
+<codeblock><b>java -Djavax.net.ssl.keyStore=/Users/me/vault/ServerKeyStore \
+-Djavax.net.ssl.keyStorePassword=secretServerPassword \
+-Djavax.net.ssl.trustStore=/Users/me/vault/ServerTrustStore \
+-Djavax.net.ssl.trustStorePassword=secretServerTrustStorePassword \
+org.apache.derby.drda.NetworkServerControl start -p 8246 \
+-ssl peerAuthentication</b></codeblock>
+<p>The <codeph>-p 8246</codeph> option starts the server on a nondefault port
+(rather than the default port of 1527).</p>
+<p>The final step is to bring up a client. As with server startup, we must tell
+the VM the locations and passwords of the local key store and trust store. This
+example is a simple <codeph>ij</codeph> script. Notice the extra
+<codeph>ssl</codeph> attribute on the connection URL. That attribute tells the
+client to authenticate the server's identity using a certificate, and it tells
+the client that the network traffic must be encrypted:</p>
+<codeblock><b>java -Djavax.net.ssl.trustStore=/Users/me/vault/ClientTrustStore \
+-Djavax.net.ssl.trustStorePassword=secretClientTrustStorePassword \
+-Djavax.net.ssl.keyStore=/Users/me/vault/ClientKeyStore \
+-Djavax.net.ssl.keyStorePassword=secretClientPassword \
+org.apache.derby.tools.ij</b>
+ij version 10.11
+ij> <b>connect 'jdbc:derby://localhost:8246/testdb;create=true;ssl=peerAuthentication';</b>
+ij> <b>select schemaName, authorizationID from sys.sysschemas;</b></codeblock>
+<p>You will get errors from <codeph>ij</codeph> if you do not specify the extra
+VM properties and/or if you do not specify the <codeph>ssl</codeph> attribute on
+the connection URL. Here, for instance, is the output from running
+<codeph>ij</codeph> without the VM properties and <codeph>ssl</codeph>
+attribute:</p>
+<codeblock><b>java org.apache.derby.tools.ij</b>
+ij version 10.11
+ij> <b>connect 'jdbc:derby://localhost:8246/testdb;create=true';</b>
+ERROR 08006: A network protocol error was encountered and the connection has been
+terminated: A PROTOCOL Data Stream Syntax Error was detected. Reason: 0x3.
+Plaintext connection attempt to an SSL enabled server?</codeblock>
+<p>When you want to administer the server (for instance, to bring it down), you
+will need to specify the locations and passwords of a valid key store and trust
+store as well as the extra <codeph>ssl</codeph> option on the server command
+line:</p>
+<codeblock><b>java -Djavax.net.ssl.trustStore=/Users/me/vault/ClientTrustStore \
+-Djavax.net.ssl.trustStorePassword=secretClientTrustStorePassword \
+-Djavax.net.ssl.keyStore=/Users/me/vault/ClientKeyStore \
+-Djavax.net.ssl.keyStorePassword=secretClientPassword \
+org.apache.derby.drda.NetworkServerControl shutdown -p 8246 \
+-ssl peerAuthentication</b></codeblock>
+</conbody>
+</concept>
Propchange: db/derby/docs/trunk/src/security/csecsslbootconn.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/security/csecsslclient.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/csecsslclient.dita?rev=1596037&view=auto
==============================================================================
--- db/derby/docs/trunk/src/security/csecsslclient.dita (added)
+++ db/derby/docs/trunk/src/security/csecsslclient.dita Mon May 19 20:09:33 2014
@@ -0,0 +1,75 @@
+<?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="csecsslclient" 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>
+<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>
+<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="csecsslkeys.dita"/>.</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
+<codeph>javax.net.ssl.trustStorePassword</codeph> need to be set.</p>
+</section>
+<example><title>Example</title>
+<codeblock>System.setProperty("javax.net.ssl.trustStore","clientTrustStore.key");
+System.setProperty("javax.net.ssl.trustStorePassword","qwerty");
+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="csecsslkeys.dita"/>.</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
+authentication</title>
+<p>This is a combination of the last two variants.</p>
+</section>
+<example><title>Example</title>
+<codeblock>System.setProperty("javax.net.ssl.keyStore","clientKeyStore.key");
+System.setProperty("javax.net.ssl.keyStorePassword","qwerty");
+System.setProperty("javax.net.ssl.trustStore","clientTrustStore.key");
+System.setProperty("javax.net.ssl.trustStorePassword","qwerty");
+Connection c =
+ getConnection("jdbc:derby://myhost:1527/db;ssl=peerAuthentication");</codeblock>
+</example>
+</conbody>
+</concept>
Propchange: db/derby/docs/trunk/src/security/csecsslclient.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/security/csecsslkeys.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/csecsslkeys.dita?rev=1596037&view=auto
==============================================================================
--- db/derby/docs/trunk/src/security/csecsslkeys.dita (added)
+++ db/derby/docs/trunk/src/security/csecsslkeys.dita Mon May 19 20:09:33 2014
@@ -0,0 +1,81 @@
+<?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="csecsslkeys" 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>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 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>
+<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><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>
+<p>Certificates are generated with <codeph>keytool -export</codeph>
+as follows:</p>
+<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><b>keytool -import -alias <i>alias</i> -file <i>certificate-file</i> -keystore <i>truststore</i></b></codeblock>
+</section>
+<example><title>Examples</title>
+<p>Generate the server key pair:</p>
+<codeblock><b>keytool -genkey -alias myDerbyServer -keystore serverKeyStore.key</b></codeblock>
+<p>Generate a server certificate:</p>
+<codeblock><b>keytool -export -alias myDerbyServer -keystore serverKeyStore.key -rfc \
+-file myServer.cert</b></codeblock>
+<p>Generate a client key pair:</p>
+<codeblock><b>keytool -genkey -alias aDerbyClient -keystore clientKeyStore.key</b></codeblock>
+<p>Generate a client certficate:</p>
+<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><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><b>keytool -import -alias myDerbyServer -file myServer.cert \
+-keystore clientTrustStore.key</b></codeblock>
+</example>
+</conbody>
+</concept>
Propchange: db/derby/docs/trunk/src/security/csecsslkeys.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/security/csecsslserver.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/csecsslserver.dita?rev=1596037&view=auto
==============================================================================
--- db/derby/docs/trunk/src/security/csecsslserver.dita (added)
+++ db/derby/docs/trunk/src/security/csecsslserver.dita Mon May 19 20:09:33 2014
@@ -0,0 +1,64 @@
+<?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="csecsslserver" 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>These operations are described in <xref href="csecsslkeys.dita"/>.</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>
+<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><b>java -Djavax.net.ssl.keyStore=serverKeyStore.key \
+-Djavax.net.ssl.keyStorePassword=qwerty \
+-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>,
+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>
+<p>See <xref href="csecsslclient.dita"/> for client settings when the server
+does client authentication.</p>
+</section>
+<example><title>Example</title>
+<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</b></codeblock>
+</example>
+</conbody>
+</concept>
Propchange: db/derby/docs/trunk/src/security/csecsslserver.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/security/csecterms.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/csecterms.dita?rev=1596037&view=auto
==============================================================================
--- db/derby/docs/trunk/src/security/csecterms.dita (added)
+++ db/derby/docs/trunk/src/security/csecterms.dita Mon May 19 20:09:33 2014
@@ -0,0 +1,80 @@
+<?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="csecterms" xml:lang="en-us">
+<title>Security terminology</title>
+<shortdesc>In discussing
+<ph conref="../conrefs.dita#prod/productshortname"></ph> defenses, the following
+terms are useful.</shortdesc>
+<prolog></prolog>
+<conbody>
+<dl>
+<dlentry>
+<dt>attacker</dt>
+<dd>A person or organization that seeks to compromise the security of a
+system.</dd>
+</dlentry>
+<dlentry>
+<dt>damages</dt>
+<dd>The harm done to a system by an attacker. Includes denial-of-service, theft
+of secrets, and corruption of data.</dd>
+</dlentry>
+<dlentry>
+<dt><xref href="cseccsecuredbowner.dita">Database Owner</xref></dt>
+<dd>The person who creates a database and configures its security.</dd>
+</dlentry>
+<dlentry>
+<dt>insider</dt>
+<dd>An attacker, such as a disgruntled co-worker, who operates inside the
+firewall and enjoys the presumption of friendliness.</dd>
+</dlentry>
+<dlentry>
+<dt>malware</dt>
+<dd>A program that compromises security, such as a virus, worm, or spider.</dd>
+</dlentry>
+<dlentry>
+<dt>outsider</dt>
+<dd>An attacker who operates outside the firewall.</dd>
+</dlentry>
+<dlentry>
+<dt>System Administrator</dt>
+<dd>The account that launches
+<ph conref="../conrefs.dita#prod/productshortname"></ph> and is responsible for
+configuring the security of the
+<ph conref="../conrefs.dita#prod/productshortname"></ph> system.</dd>
+</dlentry>
+<dlentry>
+<dt>technique</dt>
+<dd>A mechanism for compromising the security of a system, such as
+man-in-the-middle or SQL injection.</dd>
+</dlentry>
+<dlentry>
+<dt>user</dt>
+<dd>A person authorized to use a
+<ph conref="../conrefs.dita#prod/productshortname"></ph> application.</dd>
+</dlentry>
+<dlentry>
+<dt>vulnerability</dt>
+<dd>A feature of <ph conref="../conrefs.dita#prod/productshortname"></ph> that
+attackers can exploit in order to cause damage.</dd>
+</dlentry>
+</dl>
+</conbody>
+</concept>
Propchange: db/derby/docs/trunk/src/security/csecterms.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/security/rseccopyright.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/rseccopyright.dita?rev=1596037&view=auto
==============================================================================
--- db/derby/docs/trunk/src/security/rseccopyright.dita (added)
+++ db/derby/docs/trunk/src/security/rseccopyright.dita Mon May 19 20:09:33 2014
@@ -0,0 +1,36 @@
+<?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="rseccopyright" xml:lang="en-us">
+<title>Copyright</title>
+<refbody>
+<section> <p><image href="../images/logowithtext.jpg"><alt>Logo for Apache
+Derby</alt></image></p>
+<p>Copyright 2004-@COPYRIGHT_YEAR@ The Apache Software Foundation</p>
+<p>Licensed 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 <xref format="html"
+href="http://www.apache.org/licenses/LICENSE-2.0" scope="external"/>.</p>
+</section>
+<section><title>Related information</title>
+<p><xref href="rseclicense.dita"/></p>
+</section>
+</refbody>
+</reference>
Propchange: db/derby/docs/trunk/src/security/rseccopyright.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/security/rseccsecure190.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/rseccsecure190.dita?rev=1596037&view=auto
==============================================================================
--- db/derby/docs/trunk/src/security/rseccsecure190.dita (added)
+++ db/derby/docs/trunk/src/security/rseccsecure190.dita Mon May 19 20:09:33 2014
@@ -0,0 +1,88 @@
+<?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="rseccsecure190" xml:lang="en-us">
+<title>Read-only and full access permissions</title>
+<shortdesc>The actions that users can perform on a
+<ph conref="../conrefs.dita#prod/productshortname"></ph> database with
+coarse-grained authorization are determined by the type of access that users
+have to the database objects.</shortdesc>
+<prolog><metadata>
+<keywords><indexterm>permissions<indexterm>read-only access</indexterm></indexterm>
+<indexterm>permissions<indexterm>full access</indexterm></indexterm></keywords>
+</metadata></prolog>
+<refbody>
+<section>The following table lists the actions that users can perform based
+on the type of access that a user is granted on a database.</section>
+<table frame="all">
+<title>Actions that are authorized by type of access</title>
+<desc>This table shows whether various actions are permitted with read-only and with full access to a database.</desc>
+<tgroup cols="3" colsep="1" rowsep="1">
+<colspec colname="1" colnum="1" colwidth="50*"/>
+<colspec colname="2" colnum="2" colwidth="25*"/>
+<colspec colname="3" colnum="3" colwidth="25*"/>
+<thead>
+<row valign="bottom">
+<entry colname="1">Action</entry>
+<entry colname="2">Read-only access</entry>
+<entry colname="3">Full access </entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry colname="1">Executing SELECT statements</entry>
+<entry colname="2">Yes</entry>
+<entry colname="3">Yes</entry>
+</row>
+<row>
+<entry colname="1">Reading database properties</entry>
+<entry colname="2">Yes</entry>
+<entry colname="3">Yes</entry>
+</row>
+<row>
+<entry colname="1">Loading database classes from jar files</entry>
+<entry colname="2">Yes</entry>
+<entry colname="3">Yes</entry>
+</row>
+<row>
+<entry colname="1">Executing INSERT, UPDATE, or DELETE statements</entry>
+<entry colname="2">No</entry>
+<entry colname="3">Yes</entry>
+</row>
+<row>
+<entry colname="1">Executing DDL statements</entry>
+<entry colname="2">No</entry>
+<entry colname="3">Yes</entry>
+</row>
+<row>
+<entry colname="1">Adding or replacing jar files</entry>
+<entry colname="2">No</entry>
+<entry colname="3">Yes</entry>
+</row>
+<row>
+<entry colname="1">Setting database properties</entry>
+<entry colname="2">No</entry>
+<entry colname="3">Yes</entry>
+</row>
+</tbody>
+</tgroup>
+</table>
+</refbody>
+</reference>
Propchange: db/derby/docs/trunk/src/security/rseccsecure190.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/security/rseccsecure305.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/rseccsecure305.dita?rev=1596037&view=auto
==============================================================================
--- db/derby/docs/trunk/src/security/rseccsecure305.dita (added)
+++ db/derby/docs/trunk/src/security/rseccsecure305.dita Mon May 19 20:09:33 2014
@@ -0,0 +1,29 @@
+<?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="rseccsecure305" xml:lang="en-us">
+<title>Login failure exceptions with user authentication</title>
+<shortdesc>If user authentication is turned on and a valid user name and password
+are not provided, <i>SQLException</i> 08004 is raised.</shortdesc>
+<prolog></prolog>
+<refbody>
+<example> <codeblock>ERROR 08004: Connection refused : Invalid authentication.</codeblock></example>
+</refbody>
+</reference>
Propchange: db/derby/docs/trunk/src/security/rseccsecure305.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/security/rseccsecure379.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/rseccsecure379.dita?rev=1596037&view=auto
==============================================================================
--- db/derby/docs/trunk/src/security/rseccsecure379.dita (added)
+++ db/derby/docs/trunk/src/security/rseccsecure379.dita Mon May 19 20:09:33 2014
@@ -0,0 +1,39 @@
+<?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="rseccsecure379" xml:lang="en-us">
+<title>User authorization exceptions</title>
+<shortdesc>SQL exceptions are returned when errors occur with coarse-grained
+user authorizations.</shortdesc>
+<prolog><metadata>
+<keywords><indexterm>SQL exceptions<indexterm>user authorizations</indexterm></indexterm>
+<indexterm>user authorizations<indexterm>SQL exceptions</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<refbody>
+<section><p><ph conref="../conrefs.dita#prod/productshortname"></ph> validates
+the database properties when you set the properties. An exception is returned if
+you specify an invalid value when you set these properties. </p>
+<p>If a user attempts to connect to a database but is not authorized to connect
+to that database, the <codeph>SQLException</codeph> 04501 is returned.</p>
+<p>If a user with read-only access attempts to write to a database, the
+<codeph>SQLException</codeph> 08004 (connection refused) is returned.</p>
+</section>
+</refbody>
+</reference>
Propchange: db/derby/docs/trunk/src/security/rseccsecure379.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/security/rseccsecure557.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/rseccsecure557.dita?rev=1596037&view=auto
==============================================================================
--- db/derby/docs/trunk/src/security/rseccsecure557.dita (added)
+++ db/derby/docs/trunk/src/security/rseccsecure557.dita Mon May 19 20:09:33 2014
@@ -0,0 +1,113 @@
+<?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="rseccsecure557" xml:lang="en-us">
+<title>List of user authentication properties</title>
+<shortdesc>The following table summarizes the
+<ph conref="../conrefs.dita#prod/productshortname"></ph> properties related to
+user authentication.</shortdesc>
+<prolog><metadata>
+<keywords><indexterm><indexterm>user authentication</indexterm>properties,
+list of</indexterm></keywords>
+</metadata></prolog>
+<refbody>
+<section>
+<p>For details on these properties, see the
+<ph conref="../conrefs.dita#pub/citref"></ph>.</p>
+</section>
+<table frame="all">
+<title>User authentication properties</title>
+<desc>This table lists and describes the <ph conref="../conrefs.dita#prod/productshortname"></ph> properties related to user authentication.</desc>
+<tgroup cols="2" colsep="1" rowsep="1">
+<colspec colname="1" colnum="1" colwidth="53*"/>
+<colspec colname="2" colnum="2" colwidth="45*"/>
+<thead>
+<row valign="bottom">
+<entry colname="1">Property Name</entry>
+<entry colname="2">Use</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry colname="1"><codeph>derby.authentication.provider</codeph></entry>
+<entry colname="2">Specifies the kind of user authentication to use.</entry>
+</row>
+<row>
+<entry colname="1"><codeph>derby.authentication.builtin.algorithm</codeph></entry>
+<entry colname="2">Specifies the message digest algorithm to use to protect the
+passwords that are stored in the database when using NATIVE
+authentication.</entry>
+</row>
+<row>
+<entry colname="1"><codeph>derby.authentication.builtin.iterations</codeph></entry>
+<entry colname="2">Specifies the number of times to apply the hash function
+specified by the message digest algorithm.</entry>
+</row>
+<row>
+<entry colname="1"><codeph>derby.authentication.builtin.saltLength</codeph></entry>
+<entry colname="2">Specifies the number of bytes of random salt that will be
+added to users' credentials before hashing them.</entry>
+</row>
+<row>
+<entry colname="1"><codeph>derby.authentication.native.passwordLifetimeMillis</codeph></entry>
+<entry colname="2">Specifies the number of milliseconds that a password used for
+NATIVE authentication remans valid.</entry>
+</row>
+<row>
+<entry colname="1"><codeph>derby.authentication.native.passwordLifetimeThreshold</codeph></entry>
+<entry colname="2">Specifies the threshold that triggers a password-expiration
+warning for NATIVE authentication.</entry>
+</row>
+<row>
+<entry colname="1"><codeph>derby.connection.requireAuthentication</codeph></entry>
+<entry colname="2">Turns on user authentication. If NATIVE authentication is
+used, <ph conref="../conrefs.dita#prod/productshortname"></ph> behaves as if
+this property is set to TRUE.</entry>
+</row>
+<row>
+<entry colname="1"><codeph>derby.authentication.server</codeph></entry>
+<entry colname="2">For LDAP user authentication, specifies the location of
+the server.</entry>
+</row>
+<row>
+<entry colname="1"><codeph>derby.authentication.ldap.searchAuthDN</codeph>,
+<codeph>derby.authentication.ldap.searchAuthPW</codeph>,
+<codeph>derby.authentication.ldap.searchFilter</codeph>, and
+<codeph>derby.authentication.ldap.searchBase</codeph></entry>
+<entry colname="2">Configures the way that DN searches are performed.</entry>
+</row>
+<row>
+<entry colname="1"><codeph>derby.user.UserName</codeph></entry>
+<entry colname="2">Caches user DNs locally for LDAP authentication when
+<codeph>derby.authentication.ldap.searchFilter</codeph> is set to
+<codeph>derby.user</codeph>.</entry>
+</row>
+<row>
+<entry colname="1"><codeph>java.naming.*</codeph></entry>
+<entry colname="2">JNDI properties. See Appendix A in the JNDI API reference
+(<xref format="html"
+href="http://docs.oracle.com/javase/1.5.0/docs/guide/jndi/spec/jndi/properties.html"
+scope="external"/>) for more information about these properties.</entry>
+</row>
+</tbody>
+</tgroup>
+</table>
+</refbody>
+</reference>
Propchange: db/derby/docs/trunk/src/security/rseccsecure557.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/security/rseccsecure622.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/rseccsecure622.dita?rev=1596037&view=auto
==============================================================================
--- db/derby/docs/trunk/src/security/rseccsecure622.dita (added)
+++ db/derby/docs/trunk/src/security/rseccsecure622.dita Mon May 19 20:09:33 2014
@@ -0,0 +1,28 @@
+<?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="rseccsecure622" xml:lang="en-us">
+<title>Exceptions when using authorization identifiers</title>
+<shortdesc>Specifying an invalid authorization identifier in a database user
+authorization property raises an exception. Specifying an invalid authorization
+identifier in a connection request raises an exception.</shortdesc>
+<prolog></prolog>
+<refbody></refbody>
+</reference>
Propchange: db/derby/docs/trunk/src/security/rseccsecure622.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/security/rseccsecurenativeauthex.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/rseccsecurenativeauthex.dita?rev=1596037&view=auto
==============================================================================
--- db/derby/docs/trunk/src/security/rseccsecurenativeauthex.dita (added)
+++ db/derby/docs/trunk/src/security/rseccsecurenativeauthex.dita Mon May 19 20:09:33 2014
@@ -0,0 +1,735 @@
+<?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="rseccsecurenativeauthex" xml:lang="en-us">
+<title>NATIVE authentication and SQL authorization example</title>
+<shortdesc>This example consists of the program
+<codeph>NativeAuthenticationExample.java</codeph>, which shows how to use
+<ph conref="../conrefs.dita#prod/productshortname"></ph>'s NATIVE user
+authentication and SQL authorization with either the embedded or the client
+driver.</shortdesc>
+<prolog></prolog>
+<refbody>
+<section>
+<p>See <xref href="cseccsecurenativeauth.dita"/> for information on NATIVE
+authentication. See the other topics under
+<xref href="csecauthorization.dita#csecauthorization"></xref> for more
+information on using SQL authorization.</p>
+<p>The program does the following:</p>
+<ol>
+<li>Uses a system property to set the authentication provider to
+<codeph>NATIVE:nativeAuthDB:LOCAL</codeph>, meaning that
+<codeph>nativeAuthDB</codeph> is the credentials database and that all user
+credentials are stored there.</li>
+<li>If you are running the program using the client driver, starts the Network
+Server.</li>
+<li>Creates a database named <codeph>nativeAuthDB</codeph> as the user
+<codeph>sysadm</codeph>, who is therefore the
+<xref href="cseccsecuredbowner.dita">Database Owner</xref>. Only the Database
+Owner has the right to set and read database properties.</li>
+<li>Calls the <codeph>SYSCS_UTIL.SYSCS_CREATE_USER</codeph> system procedure
+to create several users: <codeph>noacc</codeph>, <codeph>guest</codeph>, and
+<codeph>sqlsam</codeph>. The user <codeph>sysadm</codeph> has already been
+created automatically.</li>
+<li>Creates the roles <codeph>adder</codeph> and <codeph>viewer</codeph>.</li>
+<li>Grants the role <codeph>adder</codeph> to <codeph>sqlsam</codeph>, and
+grants the role <codeph>viewer</codeph> to <codeph>guest</codeph>.</li>
+<li>Creates a table, <codeph>accessibletbl</codeph>, and inserts a value into
+it.</li>
+<li>Grants SELECT and INSERT privileges on <codeph>accessibletbl</codeph> to
+<codeph>adder</codeph>.</li>
+<li>Tries to connect to the database without supplying credentials, and fails,
+as expected.</li>
+<li>Connects to the database as a user who has not been granted any
+privileges. The connection succeeds, but the user does not attempt to perform
+any operations, since no operations would be permitted.</li>
+<li>Connects to the database as <codeph>guest</codeph>, who has the role
+<codeph>viewer</codeph>.</li>
+<li>Sets the current role to <codeph>viewer</codeph>; the user succeeds in
+executing a SELECT statement on the table, but cannot execute an INSERT
+statement.</li>
+<li>Connects to the database as <codeph>sqlsam</codeph>, who has the role
+<codeph>adder</codeph>.</li>
+<li>Sets the current role to <codeph>adder</codeph>; the user succeeds in
+executing both a SELECT and an INSERT statement, but is unable to execute a
+DELETE statement.</li>
+<li>Using the connection of the Database Owner <codeph>sysadm</codeph>, deletes
+the table, the two roles, and the three users created previously.</li>
+<li>If you are running the program using the client driver, shuts down the
+Network Server.</li>
+<li>Closes the connection and shuts down
+<ph conref="../conrefs.dita#prod/productshortname"></ph>, using the Database
+Owner's credentials.</li>
+</ol>
+<p>The instructions for compiling and running the program are in the comment
+at the beginning of the program. <codeph>DERBY_LIB</codeph> is the directory
+that contains the <ph conref="../conrefs.dita#prod/productshortname"></ph> jar
+files, typically <codeph>DERBY_HOME/lib</codeph>.</p>
+</section>
+<example><title>Source code for <codeph>NativeAuthenticationExample.java</codeph></title>
+<codeblock>// does not use derby.properties
+
+import java.io.PrintWriter;
+import java.sql.*;
+
+import org.apache.derby.drda.NetworkServerControl;
+
+/*
+ * <p>
+ * This program showcases how SQL authorization is automatically turned
+ * on when you run with NATIVE authentication. You can run this program
+ * either embedded or client server.
+ * </p>
+ *
+ * <p>
+ * Here's how you compile the program:
+ * </p>
+ *
+ * <pre>
+ * javac -cp ${DERBY_LIB}/derbynet.jar NativeAuthenticationExample.java
+ * </pre>
+ *
+ * <p>
+ * Here's how you run the program embedded:
+ * </p>
+ *
+ * <pre>
+ * java -cp ${DERBY_LIB}/derby.jar:. NativeAuthenticationExample embedded
+ * </pre>
+ *
+ * <p>
+ * Here's how you run the program client/server:
+ * </p>
+ *
+ * <pre>
+ * java -cp \
+ * ${DERBY_LIB}/derby.jar:${DERBY_LIB}/derbynet.jar:${DERBY_LIB}/derbyclient.jar:. \
+ * NativeAuthenticationExample client
+ * </pre>
+ */
+public class NativeAuthenticationExample
+{
+ /////////////////////////////////////////////////////////////////////
+ //
+ // CONSTANTS
+ //
+ /////////////////////////////////////////////////////////////////////
+
+ private static final String DB_NAME="nativeAuthDB";
+
+ // stored as SYSADM
+ private static final String DB_OWNER="sysadm";
+ private static final String DB_OWNER_PASSWORD="shh123ihtybb87m";
+
+ private static final String USER_WITHOUT_ROLE="NOACC";
+ private static final String USER_WITHOUT_ROLE_PASSWORD="ajaxj3x9";
+
+ private static final String READER="GUEST";
+ private static final String READER_PASSWORD="java5w6x";
+
+ private static final String WRITER="SQLSAM";
+ private static final String WRITER_PASSWORD="light8q9bulb";
+
+ private static final String EMBEDDED = "embedded";
+ private static final String CLIENT = "client";
+
+ /////////////////////////////////////////////////////////////////////
+ //
+ // STATE
+ //
+ /////////////////////////////////////////////////////////////////////
+
+ private boolean _runningEmbedded;
+ private NetworkServerControl _server;
+
+ /////////////////////////////////////////////////////////////////////
+ //
+ // ENTRY POINT
+ //
+ /////////////////////////////////////////////////////////////////////
+
+ public static void main( String... args )
+ {
+ NativeAuthenticationExample demo = parseArgs( args );
+
+ if ( demo != null )
+ {
+ demo.execute();
+ }
+ else
+ {
+ println( "Bad command line args." );
+ }
+ }
+
+ private static NativeAuthenticationExample parseArgs(
+ String... args )
+ {
+ if ( (args == null) || (args.length != 1) )
+ {
+ return null;
+ }
+
+ String mode = args[ 0 ];
+
+ if ( EMBEDDED.equals( mode ) )
+ {
+ return new NativeAuthenticationExample( true );
+ }
+ else if ( CLIENT.equals( mode ) )
+ {
+ return new NativeAuthenticationExample( false );
+ }
+ else
+ {
+ return null;
+ }
+ }
+
+ /////////////////////////////////////////////////////////////////////
+ //
+ // CONSTRUCTOR
+ //
+ /////////////////////////////////////////////////////////////////////
+
+ private NativeAuthenticationExample( boolean runningEmbedded )
+ {
+ _runningEmbedded = runningEmbedded;
+ }
+
+ /////////////////////////////////////////////////////////////////////
+ //
+ // FEATURE SHOWCASE
+ //
+ /////////////////////////////////////////////////////////////////////
+
+ /**
+ * Run all of the experiments
+ */
+ private void execute()
+ {
+ try
+ {
+ String authenticationProvider =
+ "NATIVE:" + DB_NAME + ":LOCAL";
+
+ // this turns on NATIVE authentication as well as
+ // SQL authorization
+ println( "Setting authentication provider to " +
+ authenticationProvider );
+ System.setProperty( "derby.authentication.provider",
+ authenticationProvider );
+
+ if ( !_runningEmbedded )
+ {
+ startServer();
+ }
+
+ Connection dboConn = createDatabase();
+
+ createUsers( dboConn );
+ createRoles( dboConn );
+ createTable( dboConn );
+
+ tryToConnectWithoutCredentials(); //should fail
+
+ // a valid user can connect even if they haven't been
+ // assigned any roles
+ getConnection( USER_WITHOUT_ROLE,
+ USER_WITHOUT_ROLE_PASSWORD );
+
+ verifyReaderPrivileges();
+ verifyWriterPrivileges();
+
+ println( "Using Database Owner connection again" );
+
+ dropTable( dboConn );
+ dropRoles( dboConn );
+ dropUsers( dboConn );
+
+ cleanUpAndShutDown();
+
+ } catch (Exception e)
+ {
+ errorPrintAndExit( e );
+ }
+ }
+
+ /**
+ * Create more users. Note that the credentials for the Database
+ * Owner were stored in the database automatically when the
+ * database was created.
+ */
+ public void createUsers( Connection conn )
+ throws SQLException
+ {
+ println( "Storing some sample users in the database." );
+
+ PreparedStatement ps = prepare
+ ( conn, "call syscs_util.syscs_create_user( ?, ? )" );
+
+ createUser( ps, USER_WITHOUT_ROLE, USER_WITHOUT_ROLE_PASSWORD );
+ createUser( ps, READER, READER_PASSWORD );
+ createUser( ps, WRITER, WRITER_PASSWORD );
+
+ ps.close();
+ }
+
+ private void createUser( PreparedStatement ps, String userName,
+ String password )
+ throws SQLException
+ {
+ println( "Creating user " + userName );
+ ps.setString( 1, userName );
+ ps.setString( 2, password );
+ ps.execute();
+ }
+
+ /**
+ * Create roles and grant them privileges.
+ */
+ private void createRoles( Connection conn )
+ throws SQLException
+ {
+ println( "Creating roles and granting privileges to them..." );
+
+ execute( conn, "CREATE ROLE adder" );
+ execute( conn, "CREATE ROLE viewer" );
+
+ execute( conn, "GRANT adder TO " + WRITER );
+ execute( conn, "GRANT viewer TO " + READER );
+ }
+
+ /**
+ * Create and populate a table and grant privileges related to it.
+ */
+ private void createTable( Connection conn )
+ throws SQLException
+ {
+ println("Creating table accessibletbl...");
+ execute( conn,
+ "CREATE TABLE accessibletbl(textcol VARCHAR(6))" );
+ execute( conn, "INSERT INTO accessibletbl VALUES('hello')" );
+
+ println( "Granting select/insert privileges to adder..." );
+ execute( conn,
+ "GRANT SELECT, INSERT ON accessibletbl TO adder" );
+
+ println( "Granting select privileges to viewer" );
+ execute( conn, "GRANT SELECT ON accessibletbl TO viewer" );
+ }
+
+ /**
+ * Drop users except for Database Owner.
+ */
+ public void dropUsers( Connection conn )
+ throws SQLException
+ {
+ println( "Dropping sample users from the database..." );
+
+ PreparedStatement ps = prepare
+ ( conn, "call syscs_util.syscs_drop_user( ? )" );
+
+ dropUser( ps, USER_WITHOUT_ROLE );
+ dropUser( ps, READER );
+ dropUser( ps, WRITER );
+
+ ps.close();
+ }
+
+ private void dropUser( PreparedStatement ps, String userName )
+ throws SQLException
+ {
+ println( "Dropping user " + userName );
+ ps.setString( 1, userName );
+ ps.execute();
+ }
+
+ /**
+ * Drop roles.
+ */
+ private void dropRoles( Connection conn )
+ throws SQLException
+ {
+ println( "Dropping roles..." );
+
+ execute( conn, "DROP ROLE adder" );
+ execute( conn, "DROP ROLE viewer" );
+ }
+
+ /**
+ * Drop the table.
+ */
+ private void dropTable( Connection conn )
+ throws SQLException
+ {
+ execute( conn, "DROP TABLE accessibletbl" );
+ }
+
+ /**
+ * Try to connect without supplying credentials
+ */
+ private void tryToConnectWithoutCredentials()
+ throws Exception
+ {
+ println( "Trying to connect without supplying credentials..." );
+
+ try {
+ getConnection( null, null );
+ println( "ERROR: Unexpectedly connected to database " +
+ DB_NAME );
+ cleanUpAndShutDown();
+ } catch (SQLException e)
+ {
+ if ( e.getSQLState().equals("08004") )
+ {
+ println
+ (
+ "As expected, could not get a connection without " +
+ "supplying credentials."
+ );
+ } else
+ {
+ errorPrintAndExit( e );
+ }
+ }
+ }
+
+ /**
+ * Verify that the READER user can select but not insert
+ */
+ private void verifyReaderPrivileges()
+ throws Exception
+ {
+ Connection readerConn = getConnection( READER,
+ READER_PASSWORD );
+
+ println( "Setting role to VIEWER" );
+ execute( readerConn, "SET ROLE VIEWER" );
+
+ readRow( readerConn ); // should succeed
+
+ try {
+ writeRow( readerConn );
+ println( "ERROR: Unexpectedly allowed to insert into table" );
+ cleanUpAndShutDown();
+ } catch (SQLException e)
+ {
+ if ( e.getSQLState().equals("42500") )
+ {
+ println( "As expected, failed to insert row." );
+ }
+ else
+ {
+ errorPrintAndExit(e);
+ }
+ }
+
+ readerConn.close();
+ }
+
+ /**
+ * Verify that the WRITER can read and write but not delete
+ */
+ private void verifyWriterPrivileges()
+ throws Exception
+ {
+ Connection writerConn = getConnection( WRITER,
+ WRITER_PASSWORD );
+
+ // set role to ADDER
+ println( "Setting role to ADDER" );
+ execute( writerConn, "SET ROLE ADDER" );
+
+ // should succeed
+ readRow( writerConn );
+ writeRow( writerConn );
+
+ try {
+ deleteRow( writerConn ); // should fail
+
+ println( "ERROR: Unexpectedly allowed to DELETE." );
+ cleanUpAndShutDown();
+ } catch (SQLException e)
+ {
+ if ( e.getSQLState().equals("42500") )
+ {
+ println( "As expected, failed to delete rows." );
+ }
+ else
+ {
+ errorPrintAndExit(e);
+ }
+ }
+
+ writerConn.close();
+ }
+
+ private void readRow( Connection conn ) throws SQLException
+ {
+ PreparedStatement ps = prepare
+ ( conn, "SELECT * FROM sysadm.accessibletbl" );
+ ResultSet rs = ps.executeQuery();
+ while( rs.next() )
+ {
+ println
+ ( "Value of sysadm.accessibletbl/textcol = " +
+ rs.getString( 1 ) );
+ }
+ rs.close();
+ ps.close();
+ }
+
+ private void writeRow( Connection conn ) throws SQLException
+ {
+ execute( conn,
+ "INSERT INTO sysadm.accessibletbl VALUES('guest')" );
+ }
+
+ private void deleteRow( Connection conn ) throws SQLException
+ {
+ execute( conn, "DELETE FROM sysadm.accessibletbl" );
+ }
+
+ /////////////////////////////////////////////////////////////////////
+ //
+ // SQL HELPERS
+ //
+ /////////////////////////////////////////////////////////////////////
+
+ /**
+ * Execute a statement
+ */
+ private void execute( Connection conn, String text )
+ throws SQLException
+ {
+ PreparedStatement ps = prepare( conn, text );
+
+ ps.execute();
+ ps.close();
+ }
+
+ /**
+ * Prepare a statement
+ */
+ private PreparedStatement prepare( Connection conn, String text )
+ throws SQLException
+ {
+ println( " Preparing: " + text );
+ return conn.prepareStatement( text );
+ }
+
+ /////////////////////////////////////////////////////////////////////
+ //
+ // CONNECTION MANAGEMENT
+ //
+ /////////////////////////////////////////////////////////////////////
+
+ /**
+ * Create the database
+ */
+ private Connection createDatabase()
+ throws SQLException
+ {
+ String connectionURL = getConnectionURL
+ ( DB_NAME, DB_OWNER, DB_OWNER_PASSWORD, true, false );
+
+ println( "Creating database via this URL: " + connectionURL );
+
+ return DriverManager.getConnection( connectionURL );
+ }
+
+ /**
+ * Shut down the engine and exit.
+ */
+ private void cleanUpAndShutDown()
+ throws Exception
+ {
+ // Shut down the server before the engine. this is so that
+ // we can authenticate the shutdown credentials in the
+ // booted database.
+ if ( _server != null )
+ {
+ stopServer();
+ }
+
+ // the engine should only be brought down locally
+ _runningEmbedded = true;
+ shutdownEngine();
+
+ System.exit(1);
+ }
+
+ private void shutdownEngine()
+ {
+ String shutdownURL = getConnectionURL
+ ( null, DB_OWNER, DB_OWNER_PASSWORD, false, true );
+
+ try
+ {
+ println( "Shutting down engine via this URL: " +
+ shutdownURL );
+ DriverManager.getConnection( shutdownURL );
+ } catch (SQLException se)
+ {
+ if ( se.getSQLState().equals("XJ015") )
+ {
+ println( "Derby engine shut down normally" );
+ }
+ else
+ {
+ printSQLException( se );
+ }
+ }
+ }
+
+ /**
+ * Get a connection to the database
+ */
+ private Connection getConnection( String userName, String password )
+ throws SQLException
+ {
+ String connectionURL = getConnectionURL
+ ( DB_NAME, userName, password, false, false );
+
+ println( "Getting connection via this URL: " + connectionURL );
+
+ return DriverManager.getConnection( connectionURL );
+ }
+
+ private String getConnectionURL( String dbName, String userName,
+ String password, boolean createDB, boolean shutdownDB )
+ {
+ String connectionURL = _runningEmbedded ?
+ "jdbc:derby:" :
+ "jdbc:derby://localhost:1527/";
+
+ if ( dbName != null )
+ {
+ connectionURL = connectionURL + DB_NAME;
+ }
+ if ( userName != null )
+ {
+ connectionURL = connectionURL + ";user=" + userName;
+ }
+ if ( password != null)
+ {
+ connectionURL = connectionURL + ";password=" + password;
+ }
+ if ( createDB )
+ {
+ connectionURL = connectionURL + ";create=true";
+ }
+ if ( shutdownDB )
+ {
+ connectionURL = connectionURL + ";shutdown=true";
+ }
+
+ return connectionURL;
+ }
+
+ /////////////////////////////////////////////////////////////////////
+ //
+ // SERVER MANAGEMENT
+ //
+ /////////////////////////////////////////////////////////////////////
+
+ /**
+ * Start the Derby server
+ */
+ private void startServer()
+ throws Exception
+ {
+ _server = new NetworkServerControl( DB_OWNER,
+ DB_OWNER_PASSWORD );
+
+ println( "Starting the Derby server..." );
+ _server.start( new PrintWriter( System.out ) );
+
+ // pause to let the server come up
+ Thread.sleep( 5000L );
+ }
+
+ /**
+ * Shut down the Derby server
+ */
+ private void stopServer()
+ throws Exception
+ {
+ println( "Stopping the Derby server..." );
+ _server.shutdown();
+
+ // pause to let the server come down
+ Thread.sleep( 5000L );
+ }
+
+ /////////////////////////////////////////////////////////////////////
+ //
+ // DIAGNOSTIC PRINTING
+ //
+ /////////////////////////////////////////////////////////////////////
+
+ /**
+ * Report exceptions and exit.
+ */
+ private void errorPrintAndExit( Throwable e )
+ {
+ if ( e instanceof SQLException )
+ {
+ printSQLException((SQLException) e);
+ }
+ else
+ {
+ println("A non-SQL error occurred.");
+ e.printStackTrace();
+ }
+
+ System.exit(1);
+ }
+
+ /**
+ * Print a list of SQLExceptions.
+ */
+ private void printSQLException( SQLException sqle )
+ {
+ while (sqle != null)
+ {
+ println("\n---SQLException Caught---\n");
+ println(" SQLState: " + (sqle).getSQLState());
+ println(" Severity: " + (sqle).getErrorCode());
+ println(" Message: " + (sqle).getMessage());
+
+ sqle.printStackTrace();
+
+ sqle = sqle.getNextException();
+ }
+ }
+
+ /**
+ * Print a diagnostic line to the console
+ */
+ private static void println( String text )
+ {
+ System.out.println( text );
+ }
+}</codeblock>
+</example>
+</refbody>
+</reference>
Propchange: db/derby/docs/trunk/src/security/rseccsecurenativeauthex.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/security/rseccsecuresqlauthexceptions.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/rseccsecuresqlauthexceptions.dita?rev=1596037&view=auto
==============================================================================
--- db/derby/docs/trunk/src/security/rseccsecuresqlauthexceptions.dita (added)
+++ db/derby/docs/trunk/src/security/rseccsecuresqlauthexceptions.dita Mon May 19 20:09:33 2014
@@ -0,0 +1,95 @@
+<?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="rseccsecuresqlauthexceptions" xml:lang="en-us">
+<title>SQL standard authorization exceptions</title>
+<shortdesc>SQL exceptions are returned when errors occur with SQL
+authorization.</shortdesc>
+<prolog><metadata>
+<keywords>
+<indexterm>SQL exceptions<indexterm>SQL authorization</indexterm></indexterm>
+<indexterm>SQL authorization<indexterm>SQL exceptions</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<refbody>
+<section>
+<p>The following errors can result from the CREATE ROLE statement:</p>
+<ul>
+<li>You cannot create a role if you are not the
+<xref href="cseccsecuredbowner.dita">Database Owner</xref>. An attempt to do so
+raises the <codeph>SQLException</codeph> 4251A.</li>
+<li>You cannot create a role if a role with that name already exists. An attempt
+to do so raises the <codeph>SQLException</codeph> X0Y68.</li>
+<li>You cannot create a role name if there is a user by that name. An attempt to
+create a role name that conflicts with an existing user name raises the
+<codeph>SQLException</codeph> X0Y68.</li>
+<li>A role name cannot start with the prefix SYS (after case normalization). Use
+of the prefix SYS raises the <codeph>SQLException</codeph> 4293A.</li>
+<li>You cannot create a role with the name PUBLIC (after case normalization).
+PUBLIC is a reserved authorization identifier. An attempt to create a role with
+the name PUBLIC raises <codeph>SQLException</codeph> 4251B.</li>
+</ul>
+<p>The following errors can result from the DROP ROLE statement:</p>
+<ul>
+<li>You cannot drop a role if you are not the Database Owner. An attempt to do
+so raises the <codeph>SQLException</codeph> 4251A.</li>
+<li>You cannot drop a role that does not exist. An attempt to do so raises the
+<codeph>SQLException</codeph> 0P000.</li>
+</ul>
+<p>The following errors can result from the SET ROLE statement:</p>
+<ul>
+<li>You cannot set a role if you are not the Database Owner. An attempt to do so
+raises the <codeph>SQLException</codeph> 4251A.</li>
+<li>You cannot set a role that does not exist. An attempt to do so raises the
+<codeph>SQLException</codeph> 0P000.</li>
+<li>You cannot set a role when a transaction is in progress. An attempt to do so
+raises the <codeph>SQLException</codeph> 25001.</li>
+<li>You cannot use NONE or a malformed identifier as a string or
+<codeph>?</codeph> argument to SET ROLE. An attempt to do so raises the
+<codeph>SQLException</codeph> XCXA0.</li>
+</ul>
+<p>The following errors can result from the GRANT statement:</p>
+<ul>
+<li>You cannot grant a role if you are not the Database Owner. An attempt to do
+so raises the <codeph>SQLException</codeph> 4251A.</li>
+<li>You cannot grant a role that does not exist. An attempt to do so raises the
+<codeph>SQLException</codeph> 0P000.</li>
+<li>You cannot grant the role "PUBLIC". An attempt to do so raises the
+<codeph>SQLException</codeph> 4251B.</li>
+<li>You cannot grant a role if doing so would create a circularity by granting
+a container role to a contained role. An attempt to do so raises the
+<codeph>SQLException</codeph> 4251C.</li>
+</ul>
+<p>The following errors can result from the REVOKE statement:</p>
+<ul>
+<li>You cannot revoke a role if you are not the Database Owner. An attempt to do
+so raises the <codeph>SQLException</codeph> 4251A.</li>
+<li>You cannot revoke a role that does not exist. An attempt to do so raises the
+<codeph>SQLException</codeph> 0P000.</li>
+<li>You cannot revoke the role "PUBLIC". An attempt to do so raises the
+<codeph>SQLException</codeph> 4251B.</li>
+</ul>
+<p>For all statements, an attempt to specify an identifier argument more than
+128 characters long raises the <codeph>SQLException</codeph> 42622.</p>
+<p>For more information about exceptions, see "SQL error messages and
+exceptions" in the <ph conref="../conrefs.dita#pub/citref"></ph>.</p>
+</section>
+</refbody>
+</reference>
Propchange: db/derby/docs/trunk/src/security/rseccsecuresqlauthexceptions.dita
------------------------------------------------------------------------------
svn:eol-style = native