db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chaa...@apache.org
Subject svn commit: r1304566 [1/2] - /db/derby/docs/trunk/src/devguide/
Date Fri, 23 Mar 2012 19:19:27 GMT
Author: chaase3
Date: Fri Mar 23 19:19:26 2012
New Revision: 1304566

URL: http://svn.apache.org/viewvc?rev=1304566&view=rev
Log:
DERBY-5522  Document the NATIVE authentication scheme.

In Developer's Guide, added two new topics, removed 6 obsolete ones, and modified 18.

Patch: DERBY-5522-devguide-3.diff

Added:
    db/derby/docs/trunk/src/devguide/cdevcsecurenativeauth.dita   (with props)
    db/derby/docs/trunk/src/devguide/rdevcsecurenativeauthex.dita   (with props)
Removed:
    db/derby/docs/trunk/src/devguide/rdevcsecure13713.dita
    db/derby/docs/trunk/src/devguide/rdevcsecure26537.dita
    db/derby/docs/trunk/src/devguide/rdevcsecureclientexample.dita
    db/derby/docs/trunk/src/devguide/rdevcsecuresqlauthclientex.dita
    db/derby/docs/trunk/src/devguide/rdevcsecuresqlauthembeddedex.dita
    db/derby/docs/trunk/src/devguide/rdevcsecuresqlauthexs.dita
Modified:
    db/derby/docs/trunk/src/devguide/cdevcsecure21547.dita
    db/derby/docs/trunk/src/devguide/cdevcsecure24458.dita
    db/derby/docs/trunk/src/devguide/cdevcsecure36127.dita
    db/derby/docs/trunk/src/devguide/cdevcsecure36595.dita
    db/derby/docs/trunk/src/devguide/cdevcsecure37817.dita
    db/derby/docs/trunk/src/devguide/cdevcsecure42374.dita
    db/derby/docs/trunk/src/devguide/cdevcsecure51876.dita
    db/derby/docs/trunk/src/devguide/cdevcsecure865818.dita
    db/derby/docs/trunk/src/devguide/cdevcsecure865880.dita
    db/derby/docs/trunk/src/devguide/cdevcsecure866060.dita
    db/derby/docs/trunk/src/devguide/cdevcsecureDbOwner.dita
    db/derby/docs/trunk/src/devguide/cdevsetprop824451.dita
    db/derby/docs/trunk/src/devguide/derbydev.ditamap
    db/derby/docs/trunk/src/devguide/rdevcsecure125.dita
    db/derby/docs/trunk/src/devguide/rdevcsecure557.dita
    db/derby/docs/trunk/src/devguide/rdevcsecure766.dita
    db/derby/docs/trunk/src/devguide/tdevcsecure81850.dita
    db/derby/docs/trunk/src/devguide/tdevcsecure82556.dita

Modified: db/derby/docs/trunk/src/devguide/cdevcsecure21547.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevcsecure21547.dita?rev=1304566&r1=1304565&r2=1304566&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevcsecure21547.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevcsecure21547.dita Fri Mar 23 19:19:26 2012
@@ -19,28 +19,31 @@ See the License for the specific languag
 limitations under the License.
 -->
 <concept id="cdevcsecure21547" xml:lang="en-us">
-<title>Built-in Derby users</title>
+<title>BUILTIN Derby users</title>
 <shortdesc><ph conref="../conrefs.dita#prod/productshortname"></ph> provides
-a simple, built-in repository of user names and passwords.</shortdesc>
+a simple repository of user names and passwords using the BUILTIN
+authentication mechanism.</shortdesc>
 <prolog><metadata>
-<keywords><indexterm>users<indexterm>built-in repository</indexterm></indexterm>
-<indexterm>passwords<indexterm>built-in repository</indexterm></indexterm>
+<keywords><indexterm>users<indexterm>BUILTIN repository</indexterm></indexterm>
+<indexterm>passwords<indexterm>BUILTIN repository</indexterm></indexterm>
 </keywords>
 </metadata></prolog>
 <conbody>
 <note type="important"><ph conref="../conrefs.dita#prod/productshortname"></ph>'s
-built-in authentication mechanism is suitable only for development and testing
-purposes. It is strongly recommended that production systems rely on LDAP or a
-user-defined class for authentication. It is also strongly recommended that
-production systems protect network connections with SSL/TLS.</note>
-<p>To use the built-in repository, set <i>derby.authentication.provider</i> to <i>BUILTIN</i>.
-Using built-in users is an alternative to using an external directory service
-such as LDAP.</p>
+BUILTIN authentication mechanism is suitable only for development and testing
+purposes, and it will no longer be documented in future releases. It is strongly
+recommended that production systems rely on NATIVE authentication, an
+external directory service such as LDAP, or a user-defined class for
+authentication. It is also strongly recommended that production systems protect
+network connections with SSL/TLS.</note>
+<p>To use the BUILTIN repository, set
+<codeph>derby.authentication.provider</codeph> to <codeph>BUILTIN</codeph>.</p>
 <codeblock>derby.authentication.provider=BUILTIN</codeblock>
 <p>You can create user names and passwords for <ph conref="../conrefs.dita#prod/productshortname"></ph> users
-by specifying them with the <i>derby.user.UserName</i> property.</p>
+by specifying them with the <codeph>derby.user.UserName</codeph> property.</p>
 <note>These user names are case-sensitive for user authentication. User names
-are <i>SQL92Identifiers</i>. Delimited identifiers are allowed:   <codeblock>derby.user."FRed"=java</codeblock></note>
+are <i>SQL92Identifiers</i>. Delimited identifiers are allowed:
+<codeblock>derby.user."FRed"=java</codeblock></note>
 <note>For passwords, it is a good idea not to use words that would be easily
 guessed, such as a login name or simple words or numbers. A password should
 be a mix of numbers and upper- and lowercase letters.</note>

Modified: db/derby/docs/trunk/src/devguide/cdevcsecure24458.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevcsecure24458.dita?rev=1304566&r1=1304565&r2=1304566&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevcsecure24458.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevcsecure24458.dita Fri Mar 23 19:19:26 2012
@@ -39,10 +39,12 @@ type his name that way.   <codeblock>Con
 <li>Within the <ph conref="../conrefs.dita#prod/productshortname"></ph> user
 authorization system, Fred becomes a case-insensitive authorization identifier.
 Fred is known as <i>FRED</i>.</li>
-<li>When specifying which users are authorized to access the accounting database,
-you must list Fred's authorization identifier, <i>FRED</i> (which you can
-type as <i>FRED</i>, <i>FREd</i>, or <i>fred</i>, since the system automatically
-converts it to all-uppercase).   <codeblock><b>derby.fullAccessUsers=sa,FRED,mary</b></codeblock></li>
+<li>When you use the <codeph>SYSCS_UTIL.SYSCS_CREATE_USER</codeph> system
+procedure to create the NATIVE authentication user Fred, you specify his name
+in uppercase to match the way it is stored in the database:
+<codeblock><b>CALL SYSCS_UTIL.SYSCS_CREATE_USER('FRED', 'flintstone');
+</b></codeblock>
+</li>
 </ul>
 <p>Let's take a second example, where Fred has a slightly different name within
 the user authentication system.</p>
@@ -56,9 +58,12 @@ the double quotes when passing the name 
 <li>Within the <ph conref="../conrefs.dita#prod/productshortname"></ph> user
 authorization system, <i>Fred</i> becomes a case-sensitive authorization identifier.
 Fred is known as <i>Fred!</i>.</li>
-<li>When specifying which users are authorized to access the accounting database,
-you must list Fred's authorization identifier, <i>"Fred!"</i> (which you must
-always delimit with double quotation marks).   <codeblock>derby.fullAccessUsers=sa,"Fred!",manager</codeblock></li>
+<li>When you use the <codeph>SYSCS_UTIL.SYSCS_CREATE_USER</codeph> system
+procedure to create the NATIVE authentication user Fred!, you specify his name
+exactly as it is stored in the database:
+<codeblock><b>CALL SYSCS_UTIL.SYSCS_CREATE_USER('Fred!', 'flintstone');
+</b></codeblock>
+</li>
 </ul>
 <p>As shown in the first example, your external authentication system may
 be case-sensitive, whereas the authorization identifier within <ph conref="../conrefs.dita#prod/productshortname"></ph> may

Modified: db/derby/docs/trunk/src/devguide/cdevcsecure36127.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevcsecure36127.dita?rev=1304566&r1=1304565&r2=1304566&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevcsecure36127.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevcsecure36127.dita Fri Mar 23 19:19:26 2012
@@ -20,18 +20,24 @@ limitations under the License.
 -->
 <concept id="cdevcsecure36127" xml:lang="en-us">
 <title>Enabling user authentication</title>
-<shortdesc>To enable user authentication, set the <i>derby.connection.requireAuthentication</i> property
-to true. Otherwise, <ph conref="../conrefs.dita#prod/productshortname"></ph> does
-not require a user name and password. You can set this property as a system-wide
-property or as a database-wide property.</shortdesc>
+<shortdesc>
+If you use NATIVE authentication, you do not need to set the
+<codeph>derby.connection.requireAuthentication</codeph> property. When you
+create a database with NATIVE authentication, simply specify a username and
+password, and that user becomes the database owner.</shortdesc>
 <prolog><metadata>
 <keywords><indexterm>User authentication<indexterm>enabling</indexterm></indexterm>
 </keywords>
 </metadata></prolog>
 <conbody>
-<p>For a multi-user product, you would typically set it for the system in
-the <i>derby.properties</i> file for your server, since it is in a trusted
-environment.</p>
+<p>If you do not use NATIVE authentication, you must set the
+<codeph>derby.connection.requireAuthentication</codeph> property to true to
+enable user authentication; if you do not set this property,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> does
+not require a user name and password. You can set this property as a system-wide
+property or as a database-wide property. For a multi-user product, you would
+typically set it for the system in the <codeph>derby.properties</codeph> file
+for your server, since it is in a trusted environment.</p>
 <note>If you start a <ph conref="../conrefs.dita#prod/productshortname"></ph> system
 with user authentication enabled but without defining at least one user, you
 will not be able to shut down the system gracefully. When <ph conref="../conrefs.dita#prod/productshortname"></ph> is

Modified: db/derby/docs/trunk/src/devguide/cdevcsecure36595.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevcsecure36595.dita?rev=1304566&r1=1304565&r2=1304566&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevcsecure36595.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevcsecure36595.dita Fri Mar 23 19:19:26 2012
@@ -34,29 +34,32 @@ property<indexterm>description</indexter
 properties</indexterm></indexterm></keywords>
 </metadata></prolog>
 <conbody>
-<p>There are two types of user authorization in <ph conref="../conrefs.dita#prod/productshortname"></ph>,
-connection authorization and SQL authorization. <term>Connection authorization</term> specifies
-the access that users have to connect to a system or database. <term>SQL authorization</term> controls
-the permissions that users have on database objects or for SQL actions. You
-can set the user authorization properties in <ph conref="../conrefs.dita#prod/productshortname"></ph> as
-system-level properties or database-level properties.</p>
+<p>There are two types of user authorization in
+<ph conref="../conrefs.dita#prod/productshortname"></ph>, connection
+authorization and SQL authorization:</p>
+<ul>
+<li><term>Connection authorization</term> specifies the coarse-grained access
+that users have to connect to a system or database.</li>
+<li><term>SQL authorization</term> controls the fine-grained permissions that
+users have on database objects or for SQL actions.</li>
+</ul>
+<p>You can set the user authorization properties in
+<ph conref="../conrefs.dita#prod/productshortname"></ph> as system-level
+properties or database-level properties.</p>
 <p>Set system-level user authorizations when you are developing applications,
 or when you want to specify a secure default authorization for all users to
 connect to all of the databases in the system.</p>
+<note type="attention">If you use NATIVE authentication, fine-grained SQL
+authorization is automatically enabled, and by default, all users enjoy full
+coarse-grained access to the database. In this situation, fine-grained SQL
+authorization cannot be turned off. However, you can still adjust coarse-grained
+access to the database.</note>
+<section><title>User authorization properties</title>
 <p>There are several properties that you can set to control database-level
-user authorizations. Some of the properties are general properties that set
-the access mode for all users. Other properties are user specific properties
-that set the type of access for specific user IDs.</p>
-<p>The properties that affect authorization are:<ul>
-<li> The <codeph>derby.database.defaultConnectionMode</codeph> property controls
-the default access mode. Use the <codeph>derby.database.defaultConnectionMode</codeph> property
-to specify the default connection access that users have when they connect
-to the database. If you do not explicitly set the <codeph>derby.database.defaultConnectionMode</codeph> property,
-the default user authorization for a database is <varname>fullAccess</varname>,
-which is read-write access.</li>
-<li>The <codeph>derby.database.fullAccessUsers</codeph> and <codeph>derby.database.readOnlyAccessUsers</codeph> properties
-are user specific properties. Use these properties to specify the user IDs
-that have read-write access and read-only access to a database.</li>
+user authorizations. Some of the properties are general properties that set the
+access mode for all users. Other properties are user specific properties that
+set the type of access for specific user IDs.</p>
+<p>The following properties affect authorization:<ul>
 <li>The <codeph>derby.database.sqlAuthorization</codeph> property enables
 SQL standard authorization. Use the <codeph>derby.database.sqlAuthorization</codeph> property
 to specify if object owners can grant and revoke permission for users to perform
@@ -64,41 +67,59 @@ SQL actions on database objects. The def
 is <varname>FALSE</varname>. When the <codeph>derby.database.sqlAuthorization</codeph> property
 is set to <varname>TRUE</varname>, object owners can use the GRANT and REVOKE
 SQL statements to set the user permissions for specific database objects or
-for specific SQL actions. </li>
+for specific SQL actions.</li>
+<li>The <codeph>derby.database.defaultConnectionMode</codeph> property controls
+the default coarse-grained access mode. This property specifies the
+default connection access that users have when they connect to the database. If
+you do not explicitly set the
+<codeph>derby.database.defaultConnectionMode</codeph> property, the default
+coarse-grained connection authorization for a database is
+<varname>fullAccess</varname>, which is read-write access.</li>
+<li>The <codeph>derby.database.fullAccessUsers</codeph> and
+<codeph>derby.database.readOnlyAccessUsers</codeph> properties
+are additional coarse-grained access properties. These properties can be used to
+specify the user IDs that have read-write access and read-only access to a
+database.</li>
 </ul></p>
-<p>If you do not specify the user authorizations for a specific user ID, the
-user ID inherits whatever authorization is set as the default user authorization
-for the database.</p>
+<p>If you do not specify the coarse-grained user authorizations for a specific
+user ID, that user ID inherits the database's default coarse-grained connection
+authorization.</p>
 <note type="tip">If you set the <codeph>derby.database.defaultConnectionMode</codeph> property
 to <varname>noAccess</varname> or <varname>readOnlyAccess</varname>, you should
 allow at least one user read-write access. Otherwise, depending on the default
 connection authorization you specify, you will configure the database so that
 it cannot be accessed or changed.</note>
-<section><title>How user authorization properties work together</title><p>The <codeph>derby.database.defaultConnectionMode</codeph> property
+</section>
+<section><title>How user authorization properties work together</title>
+<p>The <codeph>derby.database.defaultConnectionMode</codeph> property
 and the <codeph>derby.database.sqlAuthorization</codeph> property work together.
 The default settings for these properties allow anyone to access and drop
 the database objects that you create. You can change the default access mode
 by specifying different settings for these properties.<ul>
-<li>When the <codeph>derby.database.sqlAuthorization</codeph> property is <varname>FALSE</varname>,
+<li>When the <codeph>derby.database.sqlAuthorization</codeph> property is
+<varname>FALSE</varname>,
 the ability to read from or write to database objects is determined by the
 setting for the <codeph>derby.database.defaultConnectionMode</codeph> property.
 If the <codeph>derby.database.defaultConnectionMode</codeph> property is set
 to <varname>readOnlyAccess</varname>, users can access all of the database
 objects but they cannot update or drop the objects. </li>
-<li>When the <codeph>derby.database.sqlAuthorization</codeph> property is <varname>TRUE</varname>,
+<li>When the <codeph>derby.database.sqlAuthorization</codeph> property is 
+<varname>TRUE</varname>,
 the ability to read from or write to database objects is further restricted
 to the owner of the database objects. The owner must grant permission for
 others to access the database objects. No one but the owner of an object or
 the
 <xref href="cdevcsecureDbOwner.dita#cdevcsecureDbOwner">database owner</xref>
 can drop the object. </li>
-<li>The access mode specified for the <codeph>derby.database.defaultConnectionMode</codeph> property
-overrides the permissions that are granted by the owner of a database object.
+<li>The coarse-grained access mode specified for the
+<codeph>derby.database.defaultConnectionMode</codeph> property
+supplements the permissions that are granted by the owner of a database object.
 For example, if a user is granted INSERT privileges on a table but the user
 only has read-only connection authorization, the user cannot insert data into
 the table.</li>
 </ul></p></section>
-<section><title>Changes to connection authorization settings</title><p>Connection
+<section><title>Changes to connection authorization settings</title>
+<p>Connection
 authorization properties are fixed for the duration of a connection. If you
 change the connection authorization properties during a connection, those
 changes are not in affect until you establish a new connection.</p></section>

Modified: db/derby/docs/trunk/src/devguide/cdevcsecure37817.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevcsecure37817.dita?rev=1304566&r1=1304565&r2=1304566&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevcsecure37817.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevcsecure37817.dita Fri Mar 23 19:19:26 2012
@@ -22,9 +22,10 @@ limitations under the License.
 <title>Defining users</title>
 <shortdesc><ph conref="../conrefs.dita#prod/productshortname"></ph> provides
 several ways to define the repository of users and passwords. To specify which
-of these services to use with your <ph conref="../conrefs.dita#prod/productshortname"></ph> system,
-set the property <i>derby.authentication.provider</i> to the appropriate value
-as discussed here.</shortdesc>
+of these services to use with your
+<ph conref="../conrefs.dita#prod/productshortname"></ph> system, set the
+property <codeph>derby.authentication.provider</codeph> to an appropriate
+value.</shortdesc>
 <prolog><metadata>
 <keywords><indexterm>Users<indexterm>defining for a system</indexterm></indexterm>
 <indexterm>Authentication provider<indexterm>specifying</indexterm></indexterm>
@@ -35,9 +36,10 @@ as discussed here.</shortdesc>
 Setting the property as a database-wide property creates users for a single
 database only.</p>
 <ul>
-<li><xref href="cdevcsecure38522.dita#cdevcsecure38522"></xref>: <xref href="cdevcsecure41285.dita#cdevcsecure41285"></xref>.
-This includes Windows NT domain user authentication through the Netscape NT
-Synchronization Service.</li>
+<li><xref href="cdevcsecurenativeauth.dita#cdevcsecurenativeauth"></xref></li>
+<li><xref href="cdevcsecure38522.dita#cdevcsecure38522"></xref>: 
+<xref href="cdevcsecure41285.dita#cdevcsecure41285"></xref>.
+</li>
 <li><xref href="cdevcsecure21561.dita#cdevcsecure21561"></xref></li>
 <li><xref href="cdevcsecure21547.dita#cdevcsecure21547"></xref></li>
 </ul>

Modified: db/derby/docs/trunk/src/devguide/cdevcsecure42374.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevcsecure42374.dita?rev=1304566&r1=1304565&r2=1304566&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevcsecure42374.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevcsecure42374.dita Fri Mar 23 19:19:26 2012
@@ -22,11 +22,11 @@ limitations under the License.
 <title>Working with user authentication</title>
 <shortdesc><ph conref="../conrefs.dita#prod/productshortname"></ph> provides
 support for user authentication and user authorization. <term>User
-authentication</term> means that
-<ph conref="../conrefs.dita#prod/productshortname"></ph> authenticates the name
-and password for a user before allowing that user access to the system.
-<term>User authorization</term> allows access to a particular
-database. You are strongly urged to implement both authentication and
+authentication</term> determines whether a user is a valid user. It establishes
+the user's identity.
+<term>User authorization</term> determines what operations a user's established
+identity can perform.
+You are strongly urged to implement both authentication and
 authorization on any multi-user database used in production.</shortdesc>
 <prolog><metadata>
 <keywords><indexterm>user authentication<indexterm>overview</indexterm></indexterm>
@@ -34,29 +34,37 @@ authorization on any multi-user database
 </keywords>
 </metadata></prolog>
 <conbody>
-<p>When user authentication is enabled (which it is not by default), the user
-requesting a connection must provide a valid name and password, which <ph
-conref="../conrefs.dita#prod/productshortname"></ph> verifies against the
-repository of users defined for the system. After <ph conref="../conrefs.dita#prod/productshortname"></ph> authenticates
-the user, it grants the user access to the <ph conref="../conrefs.dita#prod/productshortname"></ph> system
-but not necessarily access to the database made in the connection request.
-In the <ph conref="../conrefs.dita#prod/productshortname"></ph> system, access
-to a database is determined by <xref href="cdevcsecure36595.dita#cdevcsecure36595">user
-authorization</xref>.</p>
+<p>When user authentication is enabled (by default, it is <i>not</i> enabled), 
+the user that requests a connection must provide a valid name and password,
+which <ph conref="../conrefs.dita#prod/productshortname"></ph> verifies against
+the repository of users defined for the system. After
+<ph conref="../conrefs.dita#prod/productshortname"></ph> authenticates the user
+as valid, <xref href="cdevcsecure36595.dita#cdevcsecure36595">user
+authorization</xref> determines what operations the user can perform on the
+database to which the user is requesting a connection.</p>
 <p>For user authentication, <ph conref="../conrefs.dita#prod/productshortname"></ph> allows
-you to provide a repository of users in a number of different ways. For example,
-you can hook <ph conref="../conrefs.dita#prod/productshortname"></ph> up to
-an external directory service elsewhere in your enterprise, create your own
-directory service, or use <ph conref="../conrefs.dita#prod/productshortname"></ph>'s
-simple mechanism for creating a built-in repository of users.</p>
+you to provide a repository of users in a number of different ways:</p>
+<ul>
+<li>You can use <ph conref="../conrefs.dita#prod/productshortname"></ph>'s
+NATIVE authentication mechanism to store user credentials in a database. See
+<xref href="cdevcsecurenativeauth.dita#cdevcsecurenativeauth"></xref> for
+details.</li>
+<li>You can hook <ph conref="../conrefs.dita#prod/productshortname"></ph> up to
+an external directory service elsewhere in your enterprise.</li>
+<li>You can create your own directory service.</li>
+<li>You can use <ph conref="../conrefs.dita#prod/productshortname"></ph>'s
+simple BUILTIN mechanism for creating a repository of users.
+</li></ul>
 <note type="important"><ph conref="../conrefs.dita#prod/productshortname"></ph>'s
-built-in authentication mechanism is suitable only for development and testing
-purposes. It is strongly recommended that production systems rely on an
-external directory service such as LDAP or a user-defined class for
+BUILTIN authentication mechanism is suitable only for development and testing
+purposes, and it will no longer be documented in future releases. It is strongly
+recommended that production systems rely on NATIVE authentication, an
+external directory service such as LDAP, or a user-defined class for
 authentication. It is also strongly recommended that production systems protect
 network connections with SSL/TLS.</note>
 <p>You can define a repository of users for a particular database or for an
-entire system, depending on whether you use system-wide or database-wide properties.</p>
+entire system, depending on whether you use system-wide or database-wide
+properties.</p>
 <p>When <ph conref="../conrefs.dita#prod/productshortname"></ph> user authentication
 is enabled and <ph conref="../conrefs.dita#prod/productshortname"></ph> uses
 an external directory service, the architecture looks something like that

Modified: db/derby/docs/trunk/src/devguide/cdevcsecure51876.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevcsecure51876.dita?rev=1304566&r1=1304565&r2=1304566&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevcsecure51876.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevcsecure51876.dita Fri Mar 23 19:19:26 2012
@@ -20,7 +20,7 @@ limitations under the License.
 -->
 <concept id="cdevcsecure51876" xml:lang="en-us">
 <title>User authentication and authorization examples</title>
-<shortdesc>This section provides examples on using user authentication and
+<shortdesc>This section provides examples that show user authentication and
 authorization in <ph conref="../conrefs.dita#prod/productshortname"></ph> in
 either a client/server environment or in an embedded environment.</shortdesc>
 <prolog></prolog>

Modified: db/derby/docs/trunk/src/devguide/cdevcsecure865818.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevcsecure865818.dita?rev=1304566&r1=1304565&r2=1304566&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevcsecure865818.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevcsecure865818.dita Fri Mar 23 19:19:26 2012
@@ -20,15 +20,17 @@ limitations under the License.
 -->
 <concept id="cdevcsecure865818" xml:lang="en-us">
 <title>Setting the default connection access mode</title>
-<shortdesc>Use the <codeph>derby.database.defaultConnectionMode</codeph> property
-to specify the default type of access that users have when they connect to
-the database.</shortdesc>
+<shortdesc>You can use the <codeph>derby.database.defaultConnectionMode</codeph>
+property to specify the default type of access that users have when they connect
+to the database.</shortdesc>
 <prolog><metadata>
 <keywords><indexterm>databases<indexterm>controlling access to</indexterm></indexterm>
 <indexterm>derby.database.ConnectionMode property</indexterm><indexterm><indexterm>properties</indexterm>defaultConnectionMode</indexterm>
 </keywords>
 </metadata></prolog>
 <conbody>
+<p>If you use SQL authorization (the default with NATIVE authentication), you
+typically do not use this property.</p>
 <p>The valid settings for the <codeph>derby.database.defaultConnectionMode</codeph> property
 are:<ul>
 <li><varname>noAccess</varname></li>

Modified: db/derby/docs/trunk/src/devguide/cdevcsecure865880.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevcsecure865880.dita?rev=1304566&r1=1304565&r2=1304566&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevcsecure865880.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevcsecure865880.dita Fri Mar 23 19:19:26 2012
@@ -20,9 +20,10 @@ limitations under the License.
 -->
 <concept id="cdevcsecure865880" xml:lang="en-us">
 <title>Setting access for individual users</title>
-<shortdesc>Use the <codeph>derby.database.fullAccessUsers</codeph> and <codeph>derby.database.readOnlyAccessUsers</codeph> properties
-to specify the user IDs that have read-write access and read-only access to
-a database.</shortdesc>
+<shortdesc>You can use the <codeph>derby.database.fullAccessUsers</codeph> and
+<codeph>derby.database.readOnlyAccessUsers</codeph> properties to specify the
+user IDs that have read-write access and read-only access to a
+database.</shortdesc>
 <prolog><metadata>
 <keywords><indexterm>databases<indexterm>access for individual users, setting </indexterm></indexterm>
 <indexterm>derby.database.fullAccessUsers property</indexterm><indexterm><indexterm>properties</indexterm>derby.database.fullAccessUsers</indexterm>
@@ -30,6 +31,8 @@ a database.</shortdesc>
 </keywords>
 </metadata></prolog>
 <conbody>
+<p>If you use SQL authorization (the default with NATIVE authentication), you
+typically do not use these properties.</p>
 <p>You can specify multiple user IDs by using a comma-separated list, with
 no spaces between the comma and the next user ID.</p>
 <p>To set the user authorizations for individual users, specify the access

Modified: db/derby/docs/trunk/src/devguide/cdevcsecure866060.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevcsecure866060.dita?rev=1304566&r1=1304565&r2=1304566&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevcsecure866060.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevcsecure866060.dita Fri Mar 23 19:19:26 2012
@@ -19,34 +19,37 @@ limitations under the License.
 -->
 <concept id="cdevcsecure866060" xml:lang="en-us">
 <title>Setting the SQL standard authorization mode</title>
-<shortdesc>Use the <codeph>derby.database.sqlAuthorization</codeph> property
-to enable SQL standard authorization.</shortdesc>
+<shortdesc>If you use NATIVE authentication, SQL standard authorization is
+automatically enabled. Otherwise, use the
+<codeph>derby.database.sqlAuthorization</codeph> property to enable SQL standard
+authorization.</shortdesc>
 <prolog><metadata>
 <keywords><indexterm>databases<indexterm>SQL standard authorization, setting</indexterm></indexterm>
 <indexterm>derby.database.sqlAuthorization property</indexterm><indexterm><indexterm>properties</indexterm>derby.database.sqlAuthorization</indexterm>
 </keywords>
 </metadata></prolog>
 <conbody>
-<p>The <codeph>derby.database.sqlAuthorization</codeph> property controls
-the ability for object owners to grant and revoke permission for users to
-perform actions on database objects. It also controls the ability for users
-to create, set, and drop roles.</p>
+<p>If SQL standard authorization mode is enabled, object owners can grant and
+revoke permission for other users to perform actions on database objects. SQL
+standard authorization mode also controls users' ability to create, set, and
+drop roles.</p>
 <p>The valid settings for the <codeph>derby.database.sqlAuthorization</codeph> property
 are:</p><ul>
 <li><varname>TRUE</varname></li>
 <li><varname>FALSE</varname></li>
-</ul><p>The default setting for the <codeph>derby.database.sqlAuthorization</codeph> property
-is <varname>FALSE</varname>.</p>
+</ul><p>The default setting for the
+<codeph>derby.database.sqlAuthorization</codeph> property is
+<varname>FALSE</varname>, unless NATIVE authentication is enabled.</p>
 <p>The <codeph>derby.database.sqlAuthorization</codeph> property is usable only
 if the property <codeph>derby.connection.requireAuthentication</codeph> is also
 set to true, since SQL authorization is of no value unless authentication is
-also enabled.</p>
+also enabled. (With NATIVE authentication, both are enabled automatically.)</p>
 <p>After you set the <codeph>derby.database.sqlAuthorization</codeph> property
 to <varname>TRUE</varname>, you cannot set the property back to <varname>FALSE</varname>.</p>
 <p>You can set the <codeph>derby.database.sqlAuthorization</codeph> property
 as a system property or as a database property. If you set this property as
 a system property before you create the databases, all new databases will
-automatically have SQL authorization enabled. If the databases already exists,
+automatically have SQL authorization enabled. If the databases already exist,
 you can set this property only as a database property.</p>
 <p>To enable SQL standard authorization for the entire system, set the <codeph>derby.database.sqlAuthorization</codeph> property
 as a system property:</p><codeblock><b>derby.database.sqlAuthorization=true</b></codeblock>

Modified: db/derby/docs/trunk/src/devguide/cdevcsecureDbOwner.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevcsecureDbOwner.dita?rev=1304566&r1=1304565&r2=1304566&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevcsecureDbOwner.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevcsecureDbOwner.dita Fri Mar 23 19:19:26 2012
@@ -25,7 +25,8 @@ limitations under the License.
 <shortdesc>
   The term <i>database owner</i> refers to the current authorization
   identifier when the database is created, that is, the user creating
-  the database. If you enable or plan to enable SQL authorization,
+  the database. If you use NATIVE authentication, or if you manually enable
+  or plan to enable SQL authorization,
   controlling the identity of the database owner becomes important.
 </shortdesc>
 

Added: db/derby/docs/trunk/src/devguide/cdevcsecurenativeauth.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevcsecurenativeauth.dita?rev=1304566&view=auto
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevcsecurenativeauth.dita (added)
+++ db/derby/docs/trunk/src/devguide/cdevcsecurenativeauth.dita Fri Mar 23 19:19:26 2012
@@ -0,0 +1,171 @@
+<?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="cdevcsecurenativeauth" xml:lang="en-us">
+<title>Using NATIVE authentication</title>
+<shortdesc><ph conref="../conrefs.dita#prod/productshortname"></ph>'s simplest
+authentication mechanism is NATIVE authentication.</shortdesc>
+<prolog><metadata>
+<keywords><indexterm>user authentication<indexterm>NATIVE authentication</indexterm></indexterm>
+<indexterm>NATIVE authentication<indexterm>overview</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<conbody>
+<p>When you use NATIVE authentication, user names and encrypted passwords are
+stored in a database. You can specify a dedicated credentials database
+for this purpose, or you can store the credentials in the same database you use
+for your application data. The credentials are stored in the SYSUSERS system
+table of the database.</p>
+<p>To specify NATIVE authentication, specify one of the following values for the
+<codeph>derby.authentication.provider</codeph> property:</p>
+<ul>
+<li>NATIVE:<i>credentialsDB</i>
+<p>This value tells <ph conref="../conrefs.dita#prod/productshortname"></ph> to
+use <i>credentialsDB</i>, a dedicated database, to store user credentials. This
+value must be set by using system-wide Java Virtual Machine (JVM) properties or
+by using the <codeph>derby.properties</codeph> file; it cannot be set in the
+database by using the <codeph>SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY</codeph>
+procedure. When this system-wide value is set, <i>credentialsDB</i> is used to
+authenticate all operations. Individual databases can override this directive by
+specifying their own value for
+<codeph>derby.authentication.provider</codeph>.</p>
+<p>The value of <i>credentialsDB</i> must be a valid name for a database.</p>
+</li>
+<li>NATIVE:<i>credentialsDB</i>:LOCAL
+<p>This value tells <ph conref="../conrefs.dita#prod/productshortname"></ph> to
+use <i>credentialsDB</i> for system-wide operations, but to use an individual
+database's SYSUSERS system table to authenticate connections to that database.
+This value must be set by using system-wide JVM properties or by using the
+<codeph>derby.properties</codeph> file; it cannot be set in the database by
+using the <codeph>SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY</codeph> system
+procedure.</p>
+</li>
+<li>NATIVE::LOCAL
+<p>This value tells <ph conref="../conrefs.dita#prod/productshortname"></ph> to
+use an individual database's SYSUSERS system table to authenticate connections
+to it. This value is never explicitly set by an application. It is only set by
+<ph conref="../conrefs.dita#prod/productshortname"></ph> itself when it marks a
+database as a credentials database.</p>
+</li>
+</ul>
+<section><title>Working with a credentials database</title>
+<p>With NATIVE authentication, a database can become a credentials database
+in any of the following ways:</p>
+<ul>
+<li>When the database is being created, it is identified as the credentials
+database by the system-level property setting
+<codeph>derby.authentication.provider=NATIVE:<i>credentialsDB</i></codeph>.</li>
+<li>When the database is being created, LOCAL authentication of connections is
+specified by the system-level property setting
+<codeph>derby.authentication.provider=NATIVE:<i>credentialsDB</i>:LOCAL</codeph>.</li>
+<li>When the database already exists, the
+<xref href="cdevcsecureDbOwner.dita#cdevcsecureDbOwner">database owner</xref>
+calls the <codeph>SYSCS_UTIL.SYSCS_CREATE_USER</codeph> system procedure to
+store the database owner's credentials in the database. If the database owner
+calls this procedure to store another user's credentials first, an error is
+raised.</li>
+</ul>
+<p>When a database becomes a credentials database, the following things
+happen:</p>
+<ul>
+<li>The value of <codeph>derby.authentication.provider=NATIVE::LOCAL</codeph>
+is stored in the database, marking it as a credentials database.</li>
+<li>From this point forward, the value of
+<codeph>derby.authentication.provider</codeph> cannot be overridden or changed
+for connections to this database.</li>
+<li>If the database is being newly created, the database owner's credentials
+(provided in the connection arguments) are stored in the database's SYSUSERS
+system table.</li>
+<li>All future connections to the database are authenticated against the
+credentials in its SYSUSERS system table.</li>
+</ul>
+</section>
+<section><title>NATIVE authentication and other database properties</title>
+<p>When NATIVE authentication is enabled,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> behaves as if the
+<codeph>derby.connection.requireAuthentication</codeph> and
+<codeph>derby.database.sqlAuthorization</codeph> properties are also set. That
+is, a user name and password must be specified whenever a user connects to a
+database, and object owners control access to database objects. See
+<xref href="cdevcsecure866060.dita#cdevcsecure866060"></xref> for more
+information, and see
+<xref href="rdevcsecurenativeauthex.dita#rdevcsecurenativeauthex"></xref> for an
+example of the use of NATIVE authentication.</p>
+<p>For maximum security, the passwords that users specify when they connect to
+databases have an expiration date that you can modify by using the property
+<codeph>derby.authentication.native.passwordLifetimeMillis</codeph>. The
+password of the database owner never expires. By default, ordinary user
+passwords expire after 31 days.</p>
+<p>If a password is about to expire, or if the database owner's password is
+near what would be the expiration date, 
+<ph conref="../conrefs.dita#prod/productshortname"></ph> issues a warning that
+the password will soon expire (or, in the database owner's case, that the
+password is stale). By default, the warning is issued if the password is due to
+expire in one-eighth of the password's lifetime. For example, if the password
+has a 31-day lifetime, the warning will be issued 3.875 days before the
+expiration date. You can change this proportion by using the property
+<codeph>derby.authentication.native.passwordLifetimeThreshold</codeph>.</p>
+<p>Use the <codeph>derby.authentication.builtin.algorithm</codeph> property to
+change the way passwords are encrypted when they are stored in the SYSUSERS
+system table. The default algorithm is SHA-256.</p></section>
+<section><title>Managing users and passwords</title>
+<p>To manage users and passwords,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> provides a group of
+system procedures:</p>
+<ul>
+<li>To create users for a database, the database owner calls
+<codeph>SYSCS_UTIL.SYSCS_CREATE_USER</codeph>, which takes a user name and
+password as arguments. This procedure can also be executed by a user or role
+to which the database owner has granted sufficient privileges.</li>
+<li>To remove a user, the database owner calls
+<codeph>SYSCS_UTIL.SYSCS_DROP_USER</codeph>, which takes one argument,
+the user name of the user. This procedure can also be executed by a user or role
+to which the database owner has granted sufficient privileges.</li>
+<li>To reset a forgotten or expired password, the database owner calls 
+<codeph>SYSCS_UTIL.SYSCS_RESET_PASSWORD</codeph>, with a user name and
+password as arguments. This procedure can also be executed by a user or role
+to which the database owner has granted sufficient privileges.</li>
+<li>To change a user's own password, any user can call the system procedure
+<codeph>SYSCS_UTIL.SYSCS_MODIFY_PASSWORD</codeph>, which takes only one
+argument, the password. Typically, a user calls this procedure when their
+password is about to expire.</li>
+</ul>
+</section>
+<section><title>Converting an existing database to use NATIVE authentication</title>
+<p>If you wish to apply NATIVE authentication to a database that was created
+without it, the procedure is slightly different depending on whether you specify
+NATIVE:<i>credentialsDB</i> or NATIVE:<i>credentialsDB</i>:LOCAL:</p>
+<ul>
+<li>If you specify NATIVE:<i>credentialsDB</i>, add users of the existing
+database to the <i>credentialsDB</i>. Typically, you would specify uppercase
+user names and case-sensitive passwords. For instance, if the old database was
+created without any authentication, then its default user name is APP, and you
+would do the following:
+<codeblock><b>CALL SYSCS_UTIL.SYSCS_CREATE_USER('APP', 'app');</b></codeblock></li>
+<li>If you plan to specify NATIVE:<i>credentialsDB</i>:LOCAL, first connect to
+the existing database as its database owner using its old authentication scheme.
+Call <codeph>SYSCS_UTIL.SYSCS_CREATE_USER</codeph> to add credentials for the
+database owner. For example, if the existing database was created with no
+authentication, the database owner is APP, and you would add credentials for
+APP as shown above.</li>
+</ul>
+</section>
+</conbody>
+</concept>

Propchange: db/derby/docs/trunk/src/devguide/cdevcsecurenativeauth.dita
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: db/derby/docs/trunk/src/devguide/cdevsetprop824451.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevsetprop824451.dita?rev=1304566&r1=1304565&r2=1304566&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevsetprop824451.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevsetprop824451.dita Fri Mar 23 19:19:26 2012
@@ -49,13 +49,15 @@ Conglomerates created earlier are unaffe
 <p><note>Database-wide properties are stored in the database and are simpler for
 deployment, in the sense that they follow the database. Database-wide properties
 are also recommended for security reasons when you use
-<ph conref="../conrefs.dita#prod/productshortname"></ph> built-in user
+<ph conref="../conrefs.dita#prod/productshortname"></ph> BUILTIN user
 authentication (see <xref href="cdevcsecuree.dita#cdevcsecuree"></xref>).
 System-wide properties can be more practical during the development
 process.</note></p>
 <p><note type="important"><ph conref="../conrefs.dita#prod/productshortname"></ph>'s
-built-in authentication mechanism is suitable only for development and testing
-purposes. It is strongly recommended that production systems rely on LDAP or a
-user-defined class for authentication. It is also strongly recommended that
-production systems protect network connections with SSL/TLS.</note></p>
+BUILTIN authentication mechanism is suitable only for development and testing
+purposes, and it will no longer be documented in future releases. It is strongly
+recommended that production systems rely on NATIVE authentication, an external
+directory service such as LDAP, or a user-defined class for authentication. It
+is also strongly recommended that production systems protect network connections
+with SSL/TLS.</note></p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/devguide/derbydev.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/derbydev.ditamap?rev=1304566&r1=1304565&r2=1304566&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/derbydev.ditamap (original)
+++ db/derby/docs/trunk/src/devguide/derbydev.ditamap Fri Mar 23 19:19:26 2012
@@ -1300,14 +1300,14 @@ system"></topicref>
 </relrow>
 <relrow>
 <relcell>
-<topicref href="cdevcsecure36127.dita" navtitle="Enabling user authentication">
+<topicref href="cdevcsecurenativeauth.dita" navtitle="Using NATIVE authentication">
 </topicref>
 </relcell>
 <relcell>
+<topicref href="cdevcsecure36127.dita" navtitle="Enabling user authentication"></topicref>
 <topicref href="cdevcsecure37817.dita" navtitle="Defining users"></topicref>
 <topicref href="cdevcsecure38522.dita" navtitle="External directory service">
 </topicref>
-<topicref href="cdevcsecure21547.dita" navtitle="Built-in Derby users"></topicref>
 <topicref href="rdevcsecure557.dita" navtitle="List of user-authentication properties">
 </topicref>
 <topicref href="cdevcsecure79358.dita" navtitle="Programming applications for Derby user authentication">
@@ -1316,43 +1316,45 @@ system"></topicref>
 </relrow>
 <relrow>
 <relcell>
-<topicref href="cdevcsecure37817.dita" navtitle="Defining users"></topicref>
+<topicref href="cdevcsecure36127.dita" navtitle="Enabling user authentication">
+</topicref>
 </relcell>
 <relcell>
+<topicref href="cdevcsecurenativeauth.dita" navtitle="Using NATIVE authentication"></topicref>
+<topicref href="cdevcsecure37817.dita" navtitle="Defining users"></topicref>
 <topicref href="cdevcsecure38522.dita" navtitle="External directory service">
 </topicref>
-<topicref href="cdevcsecure21547.dita" navtitle="Built-in Derby users"></topicref>
 <topicref href="rdevcsecure557.dita" navtitle="List of user-authentication properties">
 </topicref>
 <topicref href="cdevcsecure79358.dita" navtitle="Programming applications for Derby user authentication">
 </topicref>
-<topicref href="cdevcsecure21561.dita" navtitle="User-defined class"></topicref>
 </relcell>
 </relrow>
 <relrow>
 <relcell>
-<topicref href="cdevcsecure38522.dita" navtitle="External directory service">
-</topicref>
+<topicref href="cdevcsecure37817.dita" navtitle="Defining users"></topicref>
 </relcell>
 <relcell>
-<topicref href="cdevcsecure21547.dita" navtitle="Built-in Derby users"></topicref>
+<topicref href="cdevcsecurenativeauth.dita" navtitle="Using NATIVE authentication"></topicref>
+<topicref href="cdevcsecure38522.dita" navtitle="External directory service">
+</topicref>
 <topicref href="rdevcsecure557.dita" navtitle="List of user-authentication properties">
 </topicref>
 <topicref href="cdevcsecure79358.dita" navtitle="Programming applications for Derby user authentication">
 </topicref>
+<topicref href="cdevcsecure21561.dita" navtitle="User-defined class"></topicref>
 </relcell>
 </relrow>
 <relrow>
 <relcell>
-<topicref href="cdevcsecure21547.dita" navtitle="Built-in Derby users"></topicref>
+<topicref href="cdevcsecure38522.dita" navtitle="External directory service">
+</topicref>
 </relcell>
 <relcell>
 <topicref href="rdevcsecure557.dita" navtitle="List of user-authentication properties">
 </topicref>
 <topicref href="cdevcsecure79358.dita" navtitle="Programming applications for Derby user authentication">
 </topicref>
-<topicref href="cdevcsecure37241.dita" navtitle="Users and authorization identifiers">
-</topicref>
 </relcell>
 </relrow>
 <relrow>
@@ -1361,6 +1363,7 @@ system"></topicref>
 </topicref>
 </relcell>
 <relcell>
+<topicref href="cdevcsecurenativeauth.dita" navtitle="Using NATIVE authentication"></topicref>
 <topicref href="cdevcsecure79358.dita" navtitle="Programming applications for Derby user authentication">
 </topicref>
 </relcell>
@@ -1531,16 +1534,6 @@ system"></topicref>
 </relrow>
 <relrow>
 <relcell>
-<topicref href="rdevcsecure125.dita" navtitle="User authentication example in a client/server environment">
-</topicref>
-</relcell>
-<relcell>
-<topicref href="rdevcsecure13713.dita" navtitle="User authentication example in a single-user, embedded environment">
-</topicref>
-</relcell>
-</relrow>
-<relrow>
-<relcell>
 <topicref href="cdevbabejgjd.dita" navtitle="Granting permissions to Derby">
 </topicref>
 </relcell>
@@ -2045,6 +2038,8 @@ with updatable result sets"></topicref>
 </topicref>
 </topicref>
 <topicref href="cdevcsecure42374.dita" navtitle="Working with user authentication">
+<topicref href="cdevcsecurenativeauth.dita" navtitle="Using NATIVE authentication">
+</topicref>
 <topicref href="cdevcsecure36127.dita" navtitle="Enabling user authentication">
 </topicref>
 <topicref href="cdevcsecure37817.dita" navtitle="Defining users"></topicref>
@@ -2090,11 +2085,6 @@ with updatable result sets"></topicref>
 </topicref>
 </topicref>
 <topicref collection-type="family" href="cdevcsecure36595.dita" navtitle="User authorizations">
-<topicref href="cdevcsecure865818.dita" navtitle="Setting the default connection access mode"></topicref>
-<topicref collection-type="family" href="cdevcsecure865880.dita" navtitle="Setting access for individual users">
-<topicref href="rdevcsecure190.dita" navtitle="Read-only and full access permissions"></topicref>
-<topicref href="rdevcsecure379.dita" navtitle="User authorization exceptions"></topicref>
-</topicref>
 <topicref collection-type="family" href="cdevcsecure866060.dita" navtitle="Setting the SQL standard authorization mode">
 <topicref href="cdevcsecuregrantrevokeaccess.dita" navtitle="Using SQL standard authorization"></topicref>
 <topicref href="cdevcsecureprivileges.dita" navtitle="Privileges on views, triggers, and constraints"></topicref>
@@ -2102,6 +2092,11 @@ with updatable result sets"></topicref>
 <topicref href="cdevcsecuresqlauthupgrade.dita" navtitle="Upgrading an old database to use SQL standard authorization"></topicref>
 <topicref href="rdevcsecuresqlauthexceptions.dita" navtitle="SQL standard authorization exceptions"></topicref>
 </topicref>
+<topicref href="cdevcsecure865818.dita" navtitle="Setting the default connection access mode"></topicref>
+<topicref collection-type="family" href="cdevcsecure865880.dita" navtitle="Setting access for individual users">
+<topicref href="rdevcsecure190.dita" navtitle="Read-only and full access permissions"></topicref>
+<topicref href="rdevcsecure379.dita" navtitle="User authorization exceptions"></topicref>
+</topicref>
 </topicref>
 <topicref href="cdevcsecure24366.dita" navtitle="Encrypting databases on disk">
 <topicref href="cdevcsecure96815.dita" navtitle="Requirements for Derby encryption">
@@ -2131,17 +2126,9 @@ with updatable result sets"></topicref>
 <topicref href="cdevcsecure10983.dita" navtitle="Notes on the Derby security features">
 </topicref>
 <topicref href="cdevcsecure51876.dita" navtitle="User authentication and authorization examples">
-<topicref href="rdevcsecure125.dita" navtitle="User authentication example in a client/server environment">
-<topicref href="rdevcsecureclientexample.dita" navtitle="User authentication and authorization client example">
-</topicref>
-</topicref>
-<topicref href="rdevcsecure13713.dita" navtitle="User authentication example in a single-user, embedded environment">
-<topicref href="rdevcsecure26537.dita" navtitle="User authentication and authorization embedded example">
-</topicref>
+<topicref href="rdevcsecurenativeauthex.dita" navtitle="NATIVE authentication and SQL authorization example">
 </topicref>
-<topicref href="rdevcsecuresqlauthexs.dita" navtitle="User authentication examples using SQL authorization">
-<topicref href="rdevcsecuresqlauthclientex.dita" navtitle="User authentication and SQL authorization client example"></topicref>
-<topicref href="rdevcsecuresqlauthembeddedex.dita" navtitle="User authentication and SQL authorization embedded example"></topicref>
+<topicref href="rdevcsecure125.dita" navtitle="Setting LDAP user authentication properties in a client/server environment">
 </topicref>
 </topicref>
 <topicref href="cdevcbabejdfj.dita" navtitle="Running Derby under a security manager">

Modified: db/derby/docs/trunk/src/devguide/rdevcsecure125.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/rdevcsecure125.dita?rev=1304566&r1=1304565&r2=1304566&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/rdevcsecure125.dita (original)
+++ db/derby/docs/trunk/src/devguide/rdevcsecure125.dita Fri Mar 23 19:19:26 2012
@@ -19,7 +19,7 @@ See the License for the specific languag
 limitations under the License.
 -->
 <reference id="rdevcsecure125" xml:lang="en-us">
-<title>User authentication example in a client/server environment</title>
+<title>Setting LDAP user authentication properties in a client/server environment</title>
 <shortdesc>In this example, <ph conref="../conrefs.dita#prod/productshortname"></ph> is
 running in a user-designed application server.</shortdesc>
 <prolog></prolog>

Modified: db/derby/docs/trunk/src/devguide/rdevcsecure557.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/rdevcsecure557.dita?rev=1304566&r1=1304565&r2=1304566&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/rdevcsecure557.dita (original)
+++ db/derby/docs/trunk/src/devguide/rdevcsecure557.dita Fri Mar 23 19:19:26 2012
@@ -20,15 +20,21 @@ limitations under the License.
 -->
 <reference id="rdevcsecure557" xml:lang="en-us">
 <title>List of user authentication properties</title>
-<shortdesc>The following table summarizes the various properties related to user
-authentication.</shortdesc>
+<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*"/>
@@ -40,48 +46,67 @@ list of</indexterm></keywords>
 </thead>
 <tbody>
 <row>
-<entry colname="1"><i>derby.connection.requireAuthentication</i></entry>
-<entry colname="2">Turns on user authentication.</entry>
+<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"><i>derby.authentication.provider</i></entry>
-<entry colname="2">Specifies the kind of user authentication to use.</entry>
+<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 or BUILTIN
+authentication.</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"><i>derby.authentication.server</i></entry>
+<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"><i>derby.authentication.ldap.searchAuthDN, derby.authentication.ldap.searchAuthPW,
-derby.authentication.ldap.searchFilter,</i> and <i>derby.authentication.ldap.searchBase</i></entry>
+<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"><i>derby.user.UserName</i></entry>
-<entry colname="2">Creates a user name and password for the built-in user
+<entry colname="1"><codeph>derby.user.UserName</codeph></entry>
+<entry colname="2">Creates a user name and password for the BUILTIN user
 repository in <ph conref="../conrefs.dita#prod/productshortname"></ph>.</entry>
 </row>
 <row>
-<entry colname="1"><i>derby.authentication.builtin.algorithm</i></entry>
-<entry colname="2">Specifies the message digest algorithm to use to protect the
-passwords that are stored in the database when using built-in
-authentication.</entry>
-</row>
-<row>
-<entry colname="1"><i>java.naming.*</i></entry>
+<entry colname="1"><codeph>java.naming.*</codeph></entry>
 <entry colname="2">JNDI properties. See Appendix A in the JNDI API reference
-for more information about these properties.</entry>
+(<xref format="html" 
+href="http://download.oracle.com/javase/1.5.0/docs/guide/jndi/spec/jndi/properties.html"
+scope="external">http://download.oracle.com/javase/1.5.0/docs/guide/jndi/spec/jn
+di/properties.html</xref>) for more information about these properties.</entry>
 </row>
 </tbody>
 </tgroup>
 </table>
 <section>
-<p><note type="important"><ph conref="../conrefs.dita#prod/productshortname"></ph>'s
-built-in authentication mechanism is suitable only for development and testing
-purposes. It is strongly recommended that production systems rely on LDAP or a
-user-defined class for authentication. It is also strongly recommended that
-production systems protect network connections with SSL/TLS.</note></p>
+<note type="important"><ph conref="../conrefs.dita#prod/productshortname"></ph>'s
+BUILTIN authentication mechanism is suitable only for development and testing
+purposes, and it will no longer be documented in future releases. It is strongly
+recommended that production systems rely on NATIVE authentication, an
+external directory service such as LDAP, or a user-defined class for
+authentication. It is also strongly recommended that production systems protect
+network connections with SSL/TLS.</note>
 </section>
 </refbody>
 </reference>

Modified: db/derby/docs/trunk/src/devguide/rdevcsecure766.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/rdevcsecure766.dita?rev=1304566&r1=1304565&r2=1304566&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/rdevcsecure766.dita (original)
+++ db/derby/docs/trunk/src/devguide/rdevcsecure766.dita Fri Mar 23 19:19:26 2012
@@ -44,7 +44,8 @@ Connection conn = DriverManager.getConne
 <section> <note>The password is not encrypted. When you are using <ph conref="../conrefs.dita#prod/productshortname"></ph> in
 the context of a server framework, the framework should be responsible for
 encrypting the password across the network. If your framework does not encrypt
-the password, consider using SSL. </note></section>
+the password, it is strongly recommended that you protect network connections
+with SSL/TLS.</note></section>
 <section><p>For information about the treatment of user names within the <ph
 conref="../conrefs.dita#prod/productshortname"></ph> system, see <xref href="cdevcsecure37241.dita#cdevcsecure37241"></xref>.</p></section>
 </refbody>

Added: db/derby/docs/trunk/src/devguide/rdevcsecurenativeauthex.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/rdevcsecurenativeauthex.dita?rev=1304566&view=auto
==============================================================================
--- db/derby/docs/trunk/src/devguide/rdevcsecurenativeauthex.dita (added)
+++ db/derby/docs/trunk/src/devguide/rdevcsecurenativeauthex.dita Fri Mar 23 19:19:26 2012
@@ -0,0 +1,740 @@
+<?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="rdevcsecurenativeauthex" 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>
+<note>It is strongly recommended that, in addition to using
+<ph conref="../conrefs.dita#prod/productshortname"></ph>'s NATIVE
+authentication mechanism, LDAP, or a user-defined class for authentication, 
+production systems protect network connections with SSL/TLS.</note>
+<p>See <xref href="cdevcsecurenativeauth.dita#cdevcsecurenativeauth"></xref>
+for information on NATIVE authentication. See
+<xref href="cdevcsecure36595.dita#cdevcsecure36595"></xref> for more
+information on using SQL authorization, which allows you to use ANSI SQL
+Standard GRANT and REVOKE statements.
+</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 database owner. 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;
+
+/*
+ * &lt;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.
+ * &lt;/p>
+ *
+ * &lt;p>
+ * Here's how you compile the program:
+ * &lt;/p>
+ *
+ * &lt;pre>
+ * javac -cp ${DERBY_LIB}/derbynet.jar NativeAuthenticationExample.java
+ * &lt;/pre>
+ *
+ * &lt;p>
+ * Here's how you run the program embedded:
+ * &lt;/p>
+ *
+ * &lt;pre>
+ * java -cp ${DERBY_LIB}/derby.jar:. NativeAuthenticationExample embedded
+ * &lt;/pre>
+ *
+ * &lt;p>
+ * Here's how you run the program client/server:
+ * &lt;/p>
+ *
+ * &lt;pre>
+ * java -cp \
+ *  ${DERBY_LIB}/derby.jar:${DERBY_LIB}/derbynet.jar:${DERBY_LIB}/derbyclient.jar:. \
+ *  NativeAuthenticationExample client
+ * &lt;/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/devguide/rdevcsecurenativeauthex.dita
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: db/derby/docs/trunk/src/devguide/tdevcsecure81850.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/tdevcsecure81850.dita?rev=1304566&r1=1304565&r2=1304566&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/tdevcsecure81850.dita (original)
+++ db/derby/docs/trunk/src/devguide/tdevcsecure81850.dita Fri Mar 23 19:19:26 2012
@@ -37,17 +37,9 @@ be overridden by system properties by se
 to TRUE. See the <ph conref="../conrefs.dita#pub/citref"></ph> for details
 on this property.</cmd></step>
 <step><cmd>To prevent unauthorized users from accessing databases once they
-are booted, turn on user authentication for the database and configure user
-authorization for the database.</cmd></step>
-<step><cmd>If you are using <ph conref="../conrefs.dita#prod/productshortname"></ph>'s
-built-in users, configure each user as a database-level property so that user
-names and passwords can be encrypted.</cmd>
-<info><p><note type="important"><ph conref="../conrefs.dita#prod/productshortname"></ph>'s
-built-in authentication mechanism is suitable only for development and testing
-purposes. It is strongly recommended that production systems rely on LDAP or a
-user-defined class for authentication. It is also strongly recommended that
-production systems protect network connections with SSL/TLS.</note></p></info>
-</step>
+are booted, turn on user authentication and SQL authorization for the database.
+Use NATIVE authentication or, alternatively, LDAP or a user-defined
+class.</cmd></step>
 </steps>
 <result></result>
 </taskbody>



Mime
View raw message