docs/datasource-password-encryption.adoc

= 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==
----