Configuring security in an embedded environment

Return-Path: X-Original-To: apmail-db-derby-commits-archive@www.apache.org Delivered-To: apmail-db-derby-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id E8DDF11797 for ; Mon, 19 May 2014 20:10:40 +0000 (UTC) Received: (qmail 69049 invoked by uid 500); 19 May 2014 20:10:40 -0000 Delivered-To: apmail-db-derby-commits-archive@db.apache.org Received: (qmail 69022 invoked by uid 500); 19 May 2014 20:10:40 -0000 Mailing-List: contact derby-commits-help@db.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: List-Post: Reply-To: "Derby Development" List-Id: Delivered-To: mailing list derby-commits@db.apache.org Received: (qmail 69015 invoked by uid 99); 19 May 2014 20:10:40 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 19 May 2014 20:10:40 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 19 May 2014 20:10:38 +0000 Received: from eris.apache.org (localhost [127.0.0.1]) by eris.apache.org (Postfix) with ESMTP id 97AD02388C42; Mon, 19 May 2014 20:09:41 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1596037 [13/13] - in /db/derby/docs/trunk: ./ src/security/ Date: Mon, 19 May 2014 20:09:36 -0000 To: derby-commits@db.apache.org From: chaase3@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20140519200941.97AD02388C42@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Added: db/derby/docs/trunk/src/security/security_os.gif URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/security_os.gif?rev=1596037&view=auto ============================================================================== Binary file - no diff available. Propchange: db/derby/docs/trunk/src/security/security_os.gif ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream Added: db/derby/docs/trunk/src/security/security_os.jpg URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/security_os.jpg?rev=1596037&view=auto ============================================================================== Binary file - no diff available. Propchange: db/derby/docs/trunk/src/security/security_os.jpg ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream Added: db/derby/docs/trunk/src/security/tseccsecure81850.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/tseccsecure81850.dita?rev=1596037&view=auto ============================================================================== --- db/derby/docs/trunk/src/security/tseccsecure81850.dita (added) +++ db/derby/docs/trunk/src/security/tseccsecure81850.dita Mon May 19 20:09:33 2014 @@ -0,0 +1,56 @@ + + + + + +Configuring security in an embedded environment +In an embedded environment, typically there is only one database +per system, and there are no administrative resources to protect +databases. + + +To configure security in an embedded environment: + +Encrypt the database when you create it. +Configure all security features as database-level properties. +These properties are stored in the database (which is encrypted). See +"Scope of properties" and "Setting database-wide properties" in the + for more information. + +Turn on protection for database-level properties so that they cannot +be overridden by system properties by setting the +derby.database.propertiesOnly property to true. See the + for details on this +property. +To prevent unauthorized users from accessing databases once they +are booted, turn on user authentication and SQL authorization for the database. +Use NATIVE authentication or, alternatively, LDAP or a user-defined +class. +Configure Java security for your environment. + +

The following figure shows how disk encryption protects data when the +recipient might not know how to protect data. It is useful for databases +deployed in an embedded environment.

+Using disk encryption to protect data +This figure shows disk encryption between the Derby engine and the database. + + + + + Propchange: db/derby/docs/trunk/src/security/tseccsecure81850.dita ------------------------------------------------------------------------------ svn:eol-style = native Added: db/derby/docs/trunk/src/security/tseccsecure82556.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/tseccsecure82556.dita?rev=1596037&view=auto ============================================================================== --- db/derby/docs/trunk/src/security/tseccsecure82556.dita (added) +++ db/derby/docs/trunk/src/security/tseccsecure82556.dita Mon May 19 20:09:33 2014 @@ -0,0 +1,58 @@ + + + + + +Configuring security in a client/server environment +This procedure requires a system with multiple databases and some +administrative resources. + + + +Configure security features as system-level properties. + +Provide administrative-level protection for the +derby.properties file +and databases. For +example, you can protect these files and directories with operating system +permissions and firewalls. +Turn on user authentication for your system. All users must provide +valid user IDs and passwords to access the + system. Use NATIVE +authentication (or, alternatively, LDAP or a user-defined class). +

It is also strongly recommended that production +systems protect network connections with SSL/TLS.

+ +Configure fine-grained user authorization (SQL authorization) for +your databases. +Configure Java security for your environment. + +

The following figure shows some of the + security mechanisms at +work in a client/server environment. User authentication is performed by +accessing an LDAP directory service. The data in the database is not encrypted +in this trusted environment.

+Using an LDAP directory service in a trusted +environment +This figure shows user authentication from an LDAP directory service to the Derby engine, and user authorization to read and write data. The Derby database is a trusted environment, and the data is not encrypted. + + + + + Propchange: db/derby/docs/trunk/src/security/tseccsecure82556.dita ------------------------------------------------------------------------------ svn:eol-style = native Added: db/derby/docs/trunk/src/security/tseccsecurenewbootpw.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/tseccsecurenewbootpw.dita?rev=1596037&view=auto ============================================================================== --- db/derby/docs/trunk/src/security/tseccsecurenewbootpw.dita (added) +++ db/derby/docs/trunk/src/security/tseccsecurenewbootpw.dita Mon May 19 20:09:33 2014 @@ -0,0 +1,79 @@ + + + + + +Encrypting databases with a new boot password +You can apply a new boot password to a + database by specifying +the newBootPassword=newPassword attribute on the +connection URL when you boot the database. + + +encrypting databasesnew boot password +databasesencrypting, new boot password + + + +

If the database is configured with log archival for roll-forward recovery, +you must disable log archival and perform a shutdown before you can encrypt the +database with a new boot password.
If any global transactions are in the prepared state after recovery, the +database cannot be encrypted with a new boot password.
If the database is currently encrypted with an external encryption key, +use the +newEncryptionKey=key attribute to encrypt the +database.

When you use the newBootPassword=newPassword +attribute, a new encryption key is generated internally by the engine, and the +key is protected using the new boot password. The newly generated encryption key +encrypts the database, including the existing data. You cannot change the +encryption provider or encryption algorithm when you apply a new boot +password.

To encrypt a database with a new boot password:

+ +Specify the newBootPassword=newPassword +attribute in a URL and reboot the database. +For example, if you use the following URL to reboot +the salesdb database, the database is encrypted +with the new encryption key and is protected by the password +new1234xyz: +jdbc:derby:salesdb;bootPassword=abc1234xyz;newBootPassword=new1234xyz + + +

If authentication and +SQL authorization are +both enabled, the credentials of the +Database Owner must be supplied as +well, since reencryption is a restricted operation.

After you change the boot password, be sure to check for +SQLWarnings. The change succeeded only if there were no +SQLWarnings or SQLExceptions.

If you disabled log archival before you applied the new boot password, create +a new backup of the database after the database is reconfigured with the new +boot password. For more information, see the section "Backing up and restoring +databases" in the , particularly +"Roll-forward recovery".

+ + + + + Propchange: db/derby/docs/trunk/src/security/tseccsecurenewbootpw.dita ------------------------------------------------------------------------------ svn:eol-style = native Added: db/derby/docs/trunk/src/security/tseccsecurenewextkey.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/tseccsecurenewextkey.dita?rev=1596037&view=auto ============================================================================== --- db/derby/docs/trunk/src/security/tseccsecurenewextkey.dita (added) +++ db/derby/docs/trunk/src/security/tseccsecurenewextkey.dita Mon May 19 20:09:33 2014 @@ -0,0 +1,74 @@ + + + + + +Encrypting databases with a new external encryption key +You can apply a new external encryption key to a + database by specifying +the newEncryptionKey=key attribute on the connection URL +when you boot the database. + + +encrypting databasesnew external key +databasesencrypting, new external key + + + +

If the database is configured with log archival for roll-forward recovery, +you must disable log archival and perform a shutdown before you can encrypt the +database with a new external encryption key.
If any global transaction are in the prepared state after recovery, the +database cannot be encrypted with a new encryption key.
If the database is currently encrypted with a boot password, +use the +newBootPassword=newPassword attribute to encrypt +the database.

To encrypt a database with a new external encryption key:

+ + +Specify the newEncryptionKey=key attribute in +a URL and reboot the database. +For example, if you use the following URL to reboot the +salesdb database, the database is encrypted with the new +encryption key 6862636465666768: +jdbc:derby:salesdb;encryptionKey=6162636465666768; +newEncryptionKey=6862636465666768' + + +

If authentication and +SQL authorization are +both enabled, the credentials of the +Database Owner must be supplied as +well, since encryption is a restricted operation.

+ +

After you change the encryption key, be sure to check for +SQLWarnings. The change succeeded only if there were no +SQLWarnings or SQLExceptions.

If you disabled log archival before you applied the new encryption key, +create a new backup of the database after the database is reconfigured with the +new encryption key. For more information, see the section "Backing up and +restoring databases" in the , +particularly "Roll-forward recovery".

+ + + + Propchange: db/derby/docs/trunk/src/security/tseccsecurenewextkey.dita ------------------------------------------------------------------------------ svn:eol-style = native Added: db/derby/docs/trunk/src/security/tseccsecurenewkeyoverview.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/tseccsecurenewkeyoverview.dita?rev=1596037&view=auto ============================================================================== --- db/derby/docs/trunk/src/security/tseccsecurenewkeyoverview.dita (added) +++ db/derby/docs/trunk/src/security/tseccsecurenewkeyoverview.dita Mon May 19 20:09:33 2014 @@ -0,0 +1,69 @@ + + + + + +Encrypting databases with a new key +You can apply a new encryption key to a + database by specifying +a new boot password or a new external key. + + +encrypting databasesnew key, overview +databasesoverview of encrypting, new key + + + +

Encrypting a database with a new encryption key is a time-consuming +process because it involves encrypting all of the existing data in the database +with the new encryption key. If the process is interrupted before completion, +all the changes are rolled back the next time the database is booted. If the +interruption occurs immediately after the database is encrypted with the new +encryption key but before the connection is returned to the application, you +might not be able to boot the database with the old encryption key. In these +rare circumstances, you should try to boot the database with the new encryption +key.

+Ensure that you have enough free +disk space before you encrypt a database with a new key. In addition to the disk +space required for the current size of the database, temporary disk space is +required to store the old version of the data to restore the database back to +its original state if the new encryption is interrupted or returns errors. All +of the temporary disk space is released back to the operating system after the +database is reconfigured to work with the new encryption key. +

To encrypt a database with a new encryption key:

+ +Use the type of encryption that is currently used to encrypt the +database: + +To encrypt the database with a +new boot password key, use the +newBootPassword=newPassword attribute. +To encrypt the database with a +new external encryption key, use the +newEncryptionKey=key attribute. + +If authentication and +SQL authorization are +both enabled, the credentials of the +Database Owner must be supplied, +since reencryption is a restricted operation. + + + + Propchange: db/derby/docs/trunk/src/security/tseccsecurenewkeyoverview.dita ------------------------------------------------------------------------------ svn:eol-style = native Added: db/derby/docs/trunk/src/security/tseccsecureunencrypteddb.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/tseccsecureunencrypteddb.dita?rev=1596037&view=auto ============================================================================== --- db/derby/docs/trunk/src/security/tseccsecureunencrypteddb.dita (added) +++ db/derby/docs/trunk/src/security/tseccsecureunencrypteddb.dita Mon May 19 20:09:33 2014 @@ -0,0 +1,93 @@ + + + + + +Encrypting an existing unencrypted database +You can encrypt an unencrypted + database by specifying +attributes on the connection URL when you boot the database. The attributes that +you specify depend on how you want the database encrypted. + +encrypting databasesexisting unencrypted databases +databasesencrypting, existing unencrypted + + + +

If the database is configured with log archival, you must disable log +archival and perform a shutdown before you can encrypt the database.
If any global transactions are in the prepared state after +recovery, the database cannot be encrypted.

When you encrypt an existing, unencrypted database, you can specify +whether the database should be encrypted using a boot password +(bootPassword=key) or an external encryption key +(encryptionKey=key). You can also specify the +encryptionProvider=providerName attribute and the +encryptionAlgorithm=algorithm attribute on the +connection URL. The database is configured with the specified encryption +attributes, and all of the existing data in the database is encrypted.

See the for details on the +connection URL attributes.

Encrypting a database is a time-consuming process because it involves +encrypting all of the existing data in the database. If the process is +interrupted before completion, all the changes are rolled back the next time the +database is booted. If the interruption occurs immediately after the database is +encrypted but before the connection is returned to the application, you might +not be able to boot the database without the boot password or external +encryption key. In these rare circumstances, you should try to boot the database +with the boot password or the external encryption key.

+Ensure that you have enough free +disk space before you encrypt a database. In addition to the disk space required +for the current size of the database, temporary disk space is required to store +the old version of the data to restore the database back to its original state +if the encryption is interrupted or returns errors. All of the temporary disk +space is released back to the operating system after the database is +encrypted. +

To encrypt an existing unencrypted database:

+ + +Specify the dataEncryption=true attribute and either the +encryptionKey=key attribute or the +bootPassword=key attribute in a connection URL and boot +the database. +For example, to encrypt the salesdb database with +the boot password abc1234xyz, specify the following attributes +in the URL: +jdbc:derby:salesdb;dataEncryption=true;bootPassword=abc1234xyz +

If +authentication and +SQL authorization +are both enabled, the credentials of the +Database Owner must be supplied as +well, since encryption is a restricted operation.

After you encrypt an existing, unencrypted database, be sure to check for +SQLWarnings. The encryption succeeded only if there were no +SQLWarnings or SQLExceptions.

+If you disabled log archival before you encrypted the database, create a new +backup of the database after the database is encrypted. For more information, +see the section "Backing up and restoring databases" in the +, particularly "Roll-forward +recovery".

+ + + + Propchange: db/derby/docs/trunk/src/security/tseccsecureunencrypteddb.dita ------------------------------------------------------------------------------ svn:eol-style = native Added: db/derby/docs/trunk/src/security/tsecnetservopen.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/tsecnetservopen.dita?rev=1596037&view=auto ============================================================================== --- db/derby/docs/trunk/src/security/tsecnetservopen.dita (added) +++ db/derby/docs/trunk/src/security/tsecnetservopen.dita Mon May 19 20:09:33 2014 @@ -0,0 +1,42 @@ + + + + + +Running the Network Server without a security manager +You may override the Network Server's default installation of a +security manager if, for some reason, you need to run your application outside +of the Java security protections. + + +Network Serverno security manager + + + + +You incur a severe security risk by opening +up the server to all clients without limiting access via user authentication and +a security policy. +

Use the -noSecurityManager option to force the Network +Server to come up without a security manager. For example:

+java org.apache.derby.drda.NetworkServerControl start \ +-h localhost -noSecurityManager + + + Propchange: db/derby/docs/trunk/src/security/tsecnetservopen.dita ------------------------------------------------------------------------------ svn:eol-style = native Added: db/derby/docs/trunk/src/security/tsecnetservrun.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/tsecnetservrun.dita?rev=1596037&view=auto ============================================================================== --- db/derby/docs/trunk/src/security/tsecnetservrun.dita (added) +++ db/derby/docs/trunk/src/security/tsecnetservrun.dita Mon May 19 20:09:33 2014 @@ -0,0 +1,51 @@ + + + + + +Running the Network Server with a security manager +If you start the Network Server without specifying a security +manager, the Network Server installs a default Java security manager that +enforces a Basic policy. + +Network Serverrunning under security manager +Network Serverbasic policy + + + +

You are encouraged to customize this policy to fit the security needs of your +application and its runtime environment.

You may also run the Network Server without a security manager, although this +is not recommended.

The default policy is used if you boot the Network Server as your VM's entry +point, using a command like the following:

+java org.apache.derby.drda.NetworkServerControl start ... +

Some of your application code may run as procedures and functions that you +have declared using the CREATE PROCEDURE and CREATE FUNCTION statements. You +will need to add privileged blocks to your declared procedures and functions if +they perform sensitive operations, such as file and network I/O, classloading, +system property reading, and the like.

The Network Server attempts to install a security manager only if you start +the server as the entry point of your VM. The Network Server will not attempt to +install a security manager if you start the server from your application using +the programmatic API described in "Starting the Network Server from a Java +application" in the .

+ + + Propchange: db/derby/docs/trunk/src/security/tsecnetservrun.dita ------------------------------------------------------------------------------ svn:eol-style = native Added: db/derby/docs/trunk/src/security/tsecsslclientkeycert.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/tsecsslclientkeycert.dita?rev=1596037&view=auto ============================================================================== --- db/derby/docs/trunk/src/security/tsecsslclientkeycert.dita (added) +++ db/derby/docs/trunk/src/security/tsecsslclientkeycert.dita Mon May 19 20:09:33 2014 @@ -0,0 +1,69 @@ + + + + +Creating a client key pair and certificate +Follow these steps to create a client key pair and a client +certificate. + + + +Choose a password for the key store. +

Suppose you choose the password +secretClientPassword.

+ + +On the client system, issue the following command to create the client's +public/private key pair. +

You will be prompted to enter the password plus some identifying +information (your input is marked bold):

+keytool -genkey -alias MyClientName -keystore ~/vault/ClientKeyStore +Enter keystore password: secretClientPassword +What is your first and last name? +[Unknown]: MyFirstName MyLastName +What is the name of your organizational unit? +[Unknown]: Proofreading Department +What is the name of your organization? +[Unknown]: Name of my bookstore +What is the name of your City or Locality? +[Unknown]: New York +What is the name of your State or Province? +[Unknown]: NY +What is the two-letter country code for this unit? +[Unknown]: US +Is CN=MyFirstName MyLastName, OU=Proofreading Department, O=Name of my bookstore, L=New York, ST=NY, C=US correct? +[no]: yes + + +Enter key password for <MyClientName> + (RETURN if same as keystore password): + + +Next, create a certificate for this client. Enter the command all on +one line: +keytool -export -alias MyClientName \ +-keystore ~/vault/ClientKeyStore -rfc -file ClientCertificate \ +-storepass secretClientPassword + +This command creates a file called ClientCertificate. +Later, you will import this file into the server's trust store. + + + + \ No newline at end of file Propchange: db/derby/docs/trunk/src/security/tsecsslclientkeycert.dita ------------------------------------------------------------------------------ svn:eol-style = native Added: db/derby/docs/trunk/src/security/tsecsslimportcerts.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/tsecsslimportcerts.dita?rev=1596037&view=auto ============================================================================== --- db/derby/docs/trunk/src/security/tsecsslimportcerts.dita (added) +++ db/derby/docs/trunk/src/security/tsecsslimportcerts.dita Mon May 19 20:09:33 2014 @@ -0,0 +1,44 @@ + + + + +Importing certificates +Follow these steps to import each certificate into the other's +trust store. + + + +On the client, import the server certificate into the client's trust +store: +keytool -import -alias favoriteServerCertificate \ +-file ServerCertificate -keystore ~/vault/ClientTrustStore \ +-storepass secretClientTrustStorePassword + + + +On the server, import the client certificate into the server's trust +store: +keytool -import -alias Client_1_Certificate \ +-file ClientCertificate -keystore ~/vault/ServerTrustStore \ +-storepass secretServerTrustStorePassword + + + + + Propchange: db/derby/docs/trunk/src/security/tsecsslimportcerts.dita ------------------------------------------------------------------------------ svn:eol-style = native Added: db/derby/docs/trunk/src/security/tsecsslserverkeycert.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/security/tsecsslserverkeycert.dita?rev=1596037&view=auto ============================================================================== --- db/derby/docs/trunk/src/security/tsecsslserverkeycert.dita (added) +++ db/derby/docs/trunk/src/security/tsecsslserverkeycert.dita Mon May 19 20:09:33 2014 @@ -0,0 +1,45 @@ + + + + +Creating a server key pair and certificate +Follow these steps to create a server key pair and a server +certificate. + + + +On the server system, issue the following command to to create a server +key pair in a key store guarded by the secretServerPassword +password: +keytool -genkey -alias MyServerName -keystore ~/vault/ServerKeyStore +Enter keystore password: secretServerPassword +... + + + +Issue the following command (all on one line) to create a certificate named +ServerCertificate from this key: +keytool -export -alias MyServerName \ +-keystore ~/vault/ServerKeyStore -rfc -file ServerCertificate \ +-storepass secretServerPassword + + + + + Propchange: db/derby/docs/trunk/src/security/tsecsslserverkeycert.dita ------------------------------------------------------------------------------ svn:eol-style = native