Password encryption allows you to store encrypted passwords in the sqlrelay.conf file so that they are not publicly visible. Passwords for SQL Relay users and database passwords may both be encrypted.
Encryption and decryption are achieved via loadable modules.
The passwordencryptions section of the sqlrelay.conf file indicates which modules to load and parameters in the user and connection tags indicate which module to use with the password defined in that same tag.
For example, the rot (rotate) module encrypts by performing a simple character rotation. To use this module you would include a section in the sqlrelay.conf file like:
<?xml version="1.0"?>
<instances>
...
<instance id="example" ... >
...
<passwordencryptions>
<passwordencryption module="rot" id="rot13" count="13"/>
</passwordencryptions>
...
</instance>
...
</instances>
The module attribute specifies which module to load. The id and count attributes are parameters for the module. "13" tells the module to rotate by 13 characters. The id attribute is defined by you and just assigns this particular configuration an id that may be referred to later.
Module configurations may have attributes and/or nested tags. How these elements are interpreted is module-specific. All password encryption modules must have an id attribute.
To use this module with with an SQL Relay password, you would specify:
<?xml version="1.0"?>
<instances>
...
<instance id="example" ... >
...
<passwordencryptions>
<passwordencryption module="rot" id="rot13" count="13"/>
</passwordencryptions>
...
<users>
<user user="test" password="grfg" passwordencryptionid="rot13"/>
</users>
...
</instance>
...
</instances>
Note that the password is encrypted. Unencrypted, it would just be "test". A command line program (described later) is provided to encrypt passwords.
Note also that the passwordencryptionid attribute refers to the id of the module as set using the id parameter in the passwordencryption tag (//rot13//), not the module name (//rot//).
To use password encryption with a database password, you would specify:
<?xml version="1.0"?>
<instances>
...
<instance id="example" ... >
...
<passwordencryptions>
<passwordencryption module="rot" id="rot13" count="13"/>
</passwordencryptions>
...
<connection connectionid="db" string="user=testuser;password=grfgcnffjbeq;..." passwordencryptionid="rot13" metric="6"/>
...
</instance>
...
</instances>
Again, the password is encrypted. Unencrypted, it would just be "testpassword".
It is possible to load multiple modules and use each one with a different password. For example, you might want to use the rot module with a count of 13 for the SQL Relay password and a count of 10 for the database password.
<?xml version="1.0"?>
<instances>
...
<instance id="example" ... >
...
<passwordencryptions>
<passwordencryption module="rot" id="rot13" count="13"/>
<passwordencryption module="rot" id="rot10" count="10"/>
</passwordencryptions>
...
<users>
<user user="test" password="grfg" passwordencryptionid="rot13"/>
</users>
...
<connection connectionid="db" string="user=testuser;password=docdzkccgybn;..." passwordencryptionid="rot10" metric="6"/>
...
</instance>
...
</instances>
Encryption modules may be either two-way or one-way. Two-way encryption modules can both encrypt and decrypt a password. One-way encryption modules can only encrypt a password.
Symmetric and asymmetric key encryption techniques are two-way. The rot encryption is an example of symmetric key encryption. Asymmetric key encryptions generally use a public/private key pair, where the publicly available key is be used to encrypt the data but a privately held key is required to decrypt it. SQL Relay can use two-way encryption modules with passwords for SQL Relay users and database passwords.
One-way encryption techniques include DES, MD5 and SHA1 hashes. When using those techniques, the password can be encrypted but cannot effectively be decrypted. SQL Relay can use one-way encryption moudles with passwords for SQL Relay users but can not use one-way encryption modules to encrypt database passwords.
The command line tool sqlr-pwdenc is provided to help encrypt passwords for inclusion in the sqlrelay.conf file. Given an encryption module and password, it will print out the encrypted password.
sqlr-pwdenc [-config configfile] -id id -pwdencid passwordencryptionid -password password
For example:
$ sqlr-pwdenc -id example -pwdencid rot13 -password testpassword grfgcnffjbeq
The resulting string "grfgcnffjbeq" can now be put in the sqlrelay.conf file as the password.
There is one final thing to note. Command line client programs like sqlrsh and sqlr-import take a -id option. The -id option causes the program to open the sqlrelay.conf file and extract the host, port, socket, user and password from the specified instance. If the password is encrypted, then the encrypted password will be extracted and passed to the server. This will fail. So, when using the -id option with an encrypted password, you must also use the -user and -password option, to override the user/password that are extracted from the sqlrelay.conf file.
For example, rather than just using:
sqlrsh -id example
You should use:
sqlrsh -id example -user test -password test
Currently, the following password encryption modules are available:
The rot module is a two-way encryption module that performs a character rotation, similar to the popular ROT13 algorithm, though it can rotate by any amount specified in the count attribute, not just 13 and rotates digits as well as upper and lower-case characters. See the Introduction for example usage.
The md5 module is a one-way encryption module that encrypts the password using the MD5 algorithm.
The crypt module is a one-way encryption module that encrypts the password using the DES algorithm using a salt specified in the salt attribute. The salt is required and must be a 2 digit alphanumeric code.
Custom modules may also be developed.
For more information, please contact David Muse at david.muse@firstworks.com.