JBoss.orgCommunity Documentation

Chapter 15. Encrypting Data Source Passwords

15.1. Secured Identity
15.1.1. Encrypt the data source password
15.1.2. Create an application authentication policy with the encrypted password
15.1.3. Configure the data source to use the application authentication policy
15.2. Configured Identity with Password Based Encryption

Database connections for the JBoss AS are defined in *-ds.xml data source files. These database connection details include clear text passwords. You can increase the security of your server by replacing clear text passwords in datasource files with encrypted passwords.

This chapter presents two different methods for encrypting data source passwords. The first is Secured Identity. The second is Configured Identity with Password Based Encryption (PBE).

15.1. Secured Identity

The class org.jboss.resource.security.SecureIdentityLoginModule can be used to both encrypt database passwords and to provide a decrypted version of the password when the data source configuration is required by the server. The SecureIdentityLoginModule uses a hard-coded password to encrypt/decrypt the data source password.

Procedure 15.1. Overview: Using SecureIdentityLoginModule to encrypt a datasource password

  1. Encrypt the data source password.

  2. Create an application authentication policy with the encrypted password.

  3. Configure the data source to use the application authentication policy.

The data source password is encrypted using the SecureIdentityLoginModule main method by passing in the clear text password. The SecureIdentityLoginModule is provided by jbosssx.jar.

Procedure 15.2. Encrypt a datasource password

This procedure is for JBoss Enterprise Application Platform versions 5.1 and later

  1. Change directory to the jboss-as directory

  2. Linux command
    java -cp client/jboss-logging-spi.jar:lib/jbosssx.jar org.jboss.resource.security.SecureIdentityLoginModule PASSWORD
    Windows command:
    java -cp client\jboss-logging-spi.jar;lib\jbosssx.jar org.jboss.resource.security.SecureIdentityLoginModule PASSWORD
    Result:

    The command will return an encrypted password.

Each JBoss Application Server server profile has a conf/login-config.xml file, where application authentication policies are defined for that profile. To create a an application authentication policy for your encrypted password, add a new <application-policy> element to the <policy> element.

Example 15.1, “Example application authentication policy with encrypted data source password” is a fragment of a login-config.xml file showing an application authentication policy of name "EncryptDBPassword".

Example 15.1. Example application authentication policy with encrypted data source password

  
  <policy>
  ...
      <!-- Example usage of the SecureIdentityLoginModule -->
      <application-policy name="EncryptDBPassword">
          <authentication>
              <login-module code="org.jboss.resource.security.SecureIdentityLoginModule" flag="required">
                  <module-option name="username">admin</module-option>
                  <module-option name="password">5dfc52b51bd35553df8592078de921bc</module-option>
                  <module-option name="managedConnectionFactoryName">jboss.jca:name=PostgresDS,service=LocalTxCM</module-option>
              </login-module>
          </authentication>
      </application-policy>
  </policy>

SecureIdentityLoginModule module options

username

Specify the user name to use when establishing a connection to the database.

password

Provide the encrypted password generated in Section 15.1.1, “Encrypt the data source password”.

managedConnectionFactoryName
jboss.jca:name

Nominate a Java Naming and Directory Interface (JNDI) name for this datasource.

jboss.jca:service

Specify the transaction type

Transaction types

NoTxCM

No transaction support

LocalTxCM

Single resource transaction support

TxCM

Single resource or distributed transaction support

XATxCM

Distributed transaction support

The data source is configured in a *-ds.xml file. Remove the <user-name> and <password> elements from this file, and replace them with a <security-domain> element. This element will contain the application authentication policy name specified following Section 15.1.2, “Create an application authentication policy with the encrypted password”.

Using the example name from Section 15.1.2, “Create an application authentication policy with the encrypted password”, "EncryptDBPassword", will result in a data source file that looks something like Example 15.2, “Example data source file using secured identity”.

Example 15.2. Example data source file using secured identity


<?xml version="1.0" encoding="UTF-8"?>
<datasources>
    <local-tx-datasource>
        <jndi-name>PostgresDS</jndi-name>
        <connection-url>jdbc:postgresql://127.0.0.1:5432/test?protocolVersion=2</connection-url>
        <driver-class>org.postgresql.Driver</driver-class>
        <min-pool-size>1</min-pool-size>
        <max-pool-size>20</max-pool-size>

        <!-- REPLACED WITH security-domain BELOW
        <user-name>admin</user-name>
        <password>password</password>
        -->

        <security-domain>EncryptDBPassword</security-domain>

        <metadata>
            <type-mapping>PostgreSQL 8.0</type-mapping>
        </metadata>
    </local-tx-datasource>
</datasources>

15.2. Configured Identity with Password Based Encryption

The org.jboss.resource.security.JaasSecurityDomainIdentityLoginModule is a login module for statically defining a data source using an encrypted password. that has been encrypted by a JaasSecurityDomain. The base64 format of the data source password may be generated using the PBEUtils command: 

java -cp jbosssx.jar org.jboss.security.plugins.PBEUtils SALT ITERATION-COUNT DOMAIN-PASSWORD DATASOURCE-PASSWORD

The commands for PBEUtils arguments are:

SALT

The Salt attribute from the JaasSecurityDomain (Must only be eight characters long).

ITERATION COUNT

The IterationCount attribute from the JaasSecurity domain.

DOMAIN-PASSWORD

The plaintext password that maps to the KeyStorePass attribute from the JaasSecurityDomain.

DATASOURCE-PASSWORD

The plaintext password for the data source that should be encrypted with the JaasSecurityDomain password.

Example 15.3, “PBEUtils command example” provides an example of the command.

Example 15.3. PBEUtils command example

 java -cp jbosssx.jar org.jboss.security.plugins.PBEUtils abcdefgh 13 master ''
 Encoded password: E5gtGMKcXPP

Add the following application policy to the $JBOSS_HOME/server/$PROFILE/conf/login-config.xml file.

        
<application-policy name = "EncryptedHsqlDbRealm">
   <authentication>
      <login-module code = "org.jboss.resource.security.JaasSecurityDomainIdentityLoginModule"
       flag = "required">
          <module-option name = "username">sa</module-option>
          <module-option name = "password">E5gtGMKcXPP</module-option>
          <module-option name = "managedConnectionFactoryName">jboss.jca:service=LocalTxCM,name=DefaultDS</module-option>
          <module-option name = "jaasSecurityDomain">jboss.security:service=JaasSecurityDomain,domain=ServerMasterPassword</module-option>
       </login-module>
    </authentication>
 </application-policy>

The $JBOSS_HOME/server/$PROFILE/docs/examples/jca/hsqldb-encrypted-ds.xml illustrates that data source configuration along with the JaasSecurityDomain configuration for the keystore: 

<?xml version="1.0" encoding="UTF-8"?>

<!-- The Hypersonic embedded database JCA connection factory config
that illustrates the use of the JaasSecurityDomainIdentityLoginModule
to use encrypted password in the data source configuration. 

$Id: hsqldb-encrypted-ds.xml,v 1.1.2.1 2004/06/04 02:20:52 starksm Exp $ -->


<datasources>
   <local-tx-datasource>

      <!-- The jndi name of the DataSource, it is prefixed with java:/ -->
      <!-- Datasources are not available outside the virtual machine -->
      <jndi-name>DefaultDS</jndi-name>

      <!-- for tcp connection, allowing other processes to use the hsqldb
      database. This requires the org.jboss.jdbc.HypersonicDatabase mbean.
      <connection-url>jdbc:hsqldb:hsql://localhost:1701</connection-url>
      -->
      <!-- for totally in-memory db, not saved when jboss stops. 
      The org.jboss.jdbc.HypersonicDatabase mbean necessary
      <connection-url>jdbc:hsqldb:.</connection-url>
      -->
      <!-- for in-process persistent db, saved when jboss stops. The
      org.jboss.jdbc.HypersonicDatabase mbean is necessary for properly db shutdown
      -->
      <connection-url>jdbc:hsqldb:${jboss.server.data.dir}${/}hypersonic${/}localDB</connection-url>

      <!-- The driver class -->
      <driver-class>org.hsqldb.jdbcDriver</driver-class>

      <!--example of how to specify class that determines if exception means connection should be destroyed-->
      <!--exception-sorter-class-name>org.jboss.resource.adapter.jdbc.vendor.DummyExceptionSorter</exception-sorter-class-name-->

      <!-- this will be run before a managed connection is removed from the pool for use by a client-->
      <!--<check-valid-connection-sql>select * from something</check-valid-connection-sql> -->

      <!-- The minimum connections in a pool/sub-pool. Pools are lazily constructed on first use -->
      <min-pool-size>5</min-pool-size>

      <!-- The maximum connections in a pool/sub-pool -->
      <max-pool-size>20</max-pool-size>

      <!-- The time before an unused connection is destroyed -->
      <!-- NOTE: This is the check period. It will be destroyed somewhere between 1x and 2x this timeout after last use -->
      <!-- TEMPORARY FIX! - Disable idle connection removal, HSQLDB has a problem with not reaping threads on closed connections -->
      <idle-timeout-minutes>0</idle-timeout-minutes>

      <!-- sql to call when connection is created
        <new-connection-sql>some arbitrary sql</new-connection-sql>
      -->

      <!-- sql to call on an existing pooled connection when it is obtained from pool 
         <check-valid-connection-sql>some arbitrary sql</check-valid-connection-sql>
      -->

      <!-- example of how to specify a class that determines a connection is valid before it is handed out from the pool
         <valid-connection-checker-class-name>org.jboss.resource.adapter.jdbc.vendor.DummyValidConnectionChecker</valid-connection-checker-class-name>
      -->

      <!-- Whether to check all statements are closed when the connection is returned to the pool,
           this is a debugging feature that should be turned off in production -->
      <track-statements></track-statements>

      <!-- Use the getConnection(user, pw) for logins
        <application-managed-security></application-managed-security>
      -->

      <!-- Use the security domain defined in conf/login-config.xml -->
      <security-domain>EncryptedHsqlDbRealm</security-domain>

      <!-- This mbean can be used when using in process persistent hypersonic -->
      <depends>jboss:service=Hypersonic,database=localDB</depends>

      <!-- The datasource must depend on the mbean -->
      <depends>jboss.security:service=JaasSecurityDomain,domain=ServerMasterPassword</depends>
   </local-tx-datasource>

   <!-- The JaasSecurityDomain used for encryption. Use the name
   "jboss.security:service=JaasSecurityDomain,domain=ServerMasterPassword"
   as the value of the JaasSecurityDomainIdentityLoginModule
   jaasSecurityDomain login module option in the EncryptedHsqlDbRealm
   login-config.xml section. Typically this service config should be in
   the conf/jboss-service.xml descriptor.
   The opaque master.password file could be created using: 
   java -cp jbosssx.jar org.jboss.security.plugins.FilePassword 12345678 17 master server.password

   The corresponding login-config.xml would look like:
    <application-policy name = "EncryptedHsqlDbRealm">
       <authentication>
          <login-module code = "org.jboss.resource.security.JaasSecurityDomainIdentityLoginModule"
          flag = "required">
             <module-option name = "username">sa</module-option>
             <module-option name = "password">E5gtGMKcXPP</module-option>
             <module-option name = "managedConnectionFactoryName">jboss.jca:service=LocalTxCM,name=DefaultDS</module-option>
             <module-option name = "jaasSecurityDomain">jboss.security:service=JaasSecurityDomain,domain=ServerMasterPassword</module-option>
          </login-module>
       </authentication>
    </application-policy>
    where the encrypted password was generated using:
     java -cp jbosssx.jar org.jboss.security.plugins.PBEUtils abcdefgh 13 master ''
     Encoded password: E5gtGMKcXPP
   -->
   <mbean code="org.jboss.security.plugins.JaasSecurityDomain"
      name="jboss.security:service=JaasSecurityDomain,domain=ServerMasterPassword">
      <constructor>
         <arg type="java.lang.String" value="ServerMasterPassword"></arg>
      </constructor>
      <!-- The opaque master password file used to decrypt the encrypted
      database password key -->
      <attribute name="KeyStorePass">{CLASS}org.jboss.security.plugins.FilePassword:${jboss.server.home.dir}/conf/server.password</attribute>
      <attribute name="Salt">abcdefgh</attribute>
      <attribute name="IterationCount">13</attribute>
   </mbean>

   <!-- This mbean can be used when using in process persistent db -->
   <mbean code="org.jboss.jdbc.HypersonicDatabase"
      name="jboss:service=Hypersonic,database=localDB">
      <attribute name="Database">localDB</attribute>
      <attribute name="InProcessMode">true</attribute>
   </mbean>
</datasources>

Warning

Remember to use the same Salt and IterationCount in the MBean that was used during the password generation step.

Note

You may see the following error while starting a service that depends on the encrypted data source: 

Caused by: java.security.InvalidAlgorithmParameterException: Parameters missing
        at com.sun.crypto.provider.SunJCE_af.a(DashoA12275)
        at com.sun.crypto.provider.PBEWithMD5AndDESCipher.engineInit(DashoA12275)
        at javax.crypto.Cipher.a(DashoA12275)
        at javax.crypto.Cipher.a(DashoA12275)
        at javax.crypto.Cipher.init(DashoA12275)
        at javax.crypto.Cipher.init(DashoA12275)
        at org.jboss.security.plugins.JaasSecurityDomain.decode(JaasSecurityDomain.java:325)
        at org.jboss.security.plugins.JaasSecurityDomain.decode64(JaasSecurityDomain.java:351)
        at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
        at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
        at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
        at java.lang.reflect.Method.invoke(Method.java:585)
        at org.jboss.mx.interceptor.ReflectedDispatcher.invoke(ReflectedDispatcher.java:155)
        ... 139 more

The error most likely means that the following MBean is not yet started as a service: 

(jboss.security:service=JaasSecurityDomain,domain=ServerMasterPassword)

The following element should be included so that the MBean starts before the data source, as per the example hsqldb-encrypted-ds.xml code shown previously. 

<depends>jboss.security:service=JaasSecurityDomain,domain=ServerMasterPassword</depends>