| Title: DataSource Password Encryption |
| _Apache OpenEJB 3.1.2 or later required_ |
| |
| _TomEE 1.5.0 switched from Apache Commons-DBCP to Tomcat-pool. On that specific version, password encryption is not |
| available. You can still switch back to Apache Commons DBCP buy adding the following property: DataSourceCreator dbcp. |
| On all following versions, the database encryption will be ported and hence available on Tomcat-pool as well._ |
| |
| <a name="DataSourcePasswordEncryption-Cipheringpasswords"></a> |
| # Ciphering passwords |
| Apache OpenEJB now provides an easy and extensible way to cipher databases |
| passwords. Not that by default, this feature is not activated so plain |
| passwords are used. |
| |
| <a name="DataSourcePasswordEncryption-Usage"></a> |
| ## Usage |
| |
| Default Plain text password example: |
| |
| <Resource id="MySQL Database" type="DataSource"> |
| # MySQL example |
| # |
| # This connector will not work until you download the driver at: |
| # http://www.mysql.com/downloads/api-jdbc-stable.html |
| |
| JdbcDriver com.mysql.jdbc.Driver |
| JdbcUrl jdbc:mysql://localhost/test |
| UserName test |
| Password Passw0rd |
| </Resource> |
| |
| |
| 3DES ciphered password example. |
| |
| Note that the built in 3DES implementation uses *a static key* to |
| encode/decode your password. _It's only meant to be a sample on how to implement a Codec. On a real |
| enterprise life, you should implement your how relying on an HSM for example._ |
| The easiest way to do it is to implement the *org.apache.openejb.resource.jdbc.cipher.PasswordCipher* interface. |
| |
| <Resource id="MySQL Database" type="DataSource"> |
| # MySQL example |
| # |
| # This connector will not work until you download the driver at: |
| # http://www.mysql.com/downloads/api-jdbc-stable.html |
| |
| JdbcDriver com.mysql.jdbc.Driver |
| JdbcUrl jdbc:mysql://localhost/test |
| UserName test |
| |
| # ciphered value for Passw0rd using Static3DES codec is |
| xMH5uM1V9vQzVUv5LG7YLA== |
| Password xMH5uM1V9vQzVUv5LG7YLA== |
| PasswordCipher Static3DES |
| </Resource> |
| |
| |
| # Hint |
| You can plug your own algorithm to extend Apache OpenEJB built in ones. To |
| do such, you just need to implement the |
| |
| ## Command line tool |
| |
| Apache OpenEJB also provides a command line tool allowing password cipher |
| algorithm. Actually, it's useful to get the ciphered value of a plain text |
| value using a given algorithm. |
| |
| ### NAME |
| |
| openejb cipher - OpenEJB Cypher Tool |
| |
| ### SYNOPSIS |
| |
| openejb cipher [#options] |
| |
| ### DESCRIPTION |
| |
| The OpenEJB Cipher tool is an OPTIONAL tool that allows you to use |
| `PasswordCipher` algorithm to encode/decode values. |
| |
| *This tool isn't package by default on TomEE 1.5.0. It's only available on the standalone distribution. After 1.5.0, it's in TomEE as well.* |
| |
| The OpenEJB Cipher tool can be executed from any directory as long as |
| `<OPENEJB_HOME>/bin` is in the system PATH. Before running this tool you need |
| to set the environment variable OPENEJB_HOME to the path of the directory |
| where you unpacked the OpenEJB installation. For for the remainder of this |
| document we will assume you unpacked OpenEJB into the directory |
| C:\openejb-3.1.2. |
| |
| In Windows, the cipher tool can be executed as follows: |
| |
| `C:\openejb-3.1.2> bin\openejb cipher --help` |
| |
| In UNIX, Linux, or Mac OS X, the cipher tool can be executed as follows: |
| |
| `\[user@host openejb-3.1.2]# bin/openejb cipher --help` |
| |
| Depending on your OpenEJB version, you may need to change execution bits to |
| make the scripts executable. You can do this with the following command. |
| |
| `\[user@host openejb-3.1.2]# chmod 755 bin/openejb` |
| |
| From here on out, it will be assumed that you know how to execute the right |
| openejb script for your operating system and commands will appear in |
| shorthand as show below. |
| |
| `openejb cipher --help` |
| |
| ### OPTIONS |
| |
| <table> |
| <tr><td>-h, --_help_ <td></td>Lists these options and exit.</td></tr> |
| <tr><td>-c, --_cipher_ <td></td>Specifies the password cipher implementation to use (default is Static3DES).</td></tr> |
| <tr><td>-d, --_decrypt_ <td></td>Switches command line tool to decrypt.</td></tr> |
| <tr><td>-e, --_encrypt_ <td></td>Switches command line tool to encrypt (default).</td></tr> |
| </table> |
| |
| ### EXAMPLES |
| |
| Encrypt a plain password using the default algorithm. |
| |
| `openejb cipher Passw0rd` |
| |
| Output |
| |
| xMH5uM1V9vQzVUv5LG7YLA== |