| = DataSource Password Encryption |
| :index-group: Datasource |
| :jbake-date: 2018-12-05 |
| :jbake-type: page |
| :jbake-status: published |
| |
| _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._ |
| |
| = 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. |
| |
| == Usage |
| |
| Default Plain text password example: |
| |
| [source,xml] |
| ---- |
| <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. |
| |
| [source,xml] |
| ---- |
| <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 |
| |
| [source,properties] |
| ---- |
| 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:-3.1.2. |
| |
| In Windows, the cipher tool can be executed as follows: |
| |
| [source,java] |
| ---- |
| `C:\openejb-3.1.2> bin\openejb cipher --help` |
| ---- |
| |
| In UNIX, Linux, or Mac OS X, the cipher tool can be executed as follows: |
| |
| [source,java] |
| ---- |
| `\[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. |
| |
| [source,java] |
| ---- |
| `\[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. |
| |
| [source,java] |
| ---- |
| `openejb cipher --help` |
| ---- |
| |
| ==== OPTIONS |
| |
| -h, --_help_ |
| |
| Lists these options and exit. |
| |
| -c, --_cipher_ |
| |
| Specifies the password cipher implementation to use (default is |
| Static3DES). |
| |
| -d, --_decrypt_ |
| |
| Switches command line tool to decrypt. |
| |
| -e, --_encrypt_ |
| |
| Switches command line tool to encrypt (default). |
| |
| ==== EXAMPLES |
| |
| Encrypt a plain password using the default algorithm. |
| |
| [source,java] |
| ---- |
| `openejb cipher Passw0rd` |
| ---- |
| |
| Output |
| |
| [source,properties] |
| ---- |
| xMH5uM1V9vQzVUv5LG7YLA== |
| ---- |