close

Filter

loading table of contents...

Content Server Manual / Version 2107

Table Of Contents

3.13.2.12 Password Property Encryption

In order to encrypt passwords stored in property files you can use the keystore based encryption service. This service uses a pair of public and private keys to encode and decode passwords. The keys are retrieved from a keystore located in the file system.

Preliminary Setup

Before you can use the keystore based encryption service, you have to create a keystore file using the Java keytool command. The keystore file will contain the private key and the certificate that will be used to encrypt and decrypt the passwords. On the command prompt type:

keytool -genkeypair -keyalg RSA -validity 3650
    -keystore <KEYSTORE_FILENAME>
    -storepass <KEYSTORE_PASSWORD>
    -alias <KEY_ALIAS>
    -keypass <KEY_PASSWORD>

For secure usage at command line, it is not recommended providing passwords directly. For alternatives, see the documentation of keytool. For certain keystore types, different store and key passwords are not supported. You will get an appropriate warning when generating the key. In this case, KEY_PASSWORD will be the same as KEYSTORE_PASSWORD to be used below.

The tool will prompt you for your user name, organizational unit, organization, city, state/province, country code. This information (which goes into your self-signed certificate) is not relevant for the correct functioning of your keystore. The resulting key/certificate will be valid for 3650 days (about 10 years). It is assumed that this should be enough for your CM installation.

Having the keystore created, the keystore credentials now have to be stored in a password file, so that the servers and clients can access the keystore without prompting for passwords. The password file is in Java properties file format and has to contain the following entries:

CM_KEYSTORE_PASSWORD=<KEYSTORE_PASSWORD>
CM_KEY_ALIAS=<KEY_ALIAS>
CM_KEY_PASSWORD=<KEY_PASSWORD>

As the password file will contain the clear text passwords for your keystore, the file has to be protected from unauthorized access. This could be done for example by setting reasonable access rights for the file, or by putting it on a removable device.

Cipher transformation: By default the service uses less secure RSA-transformation, which is known to be available on all systems. For enhanced security it is recommended, to switch to an RSA algorithm with padding. You may do so by providing an additional property CM_CIPHER_TRANSFORMATION with your password file mentioned above. For available Cipher transformations have a look at your installed security providers. By default, your Java platform should support the following Cipher transformations, which you may set:

  • RSA (default and fallback; see below)

    RSA/ECB/PKCS1Padding

    RSA/ECB/OAEPWithSHA-1AndMGF1Padding

    RSA/ECB/OAEPWithSHA-256AndMGF1Padding

Example configuration:

CM_KEYSTORE_PASSWORD=<KEYSTORE_PASSWORD>
CM_KEY_ALIAS=<KEY_ALIAS>
CM_KEY_PASSWORD=<KEY_PASSWORD>
CM_CIPHER_TRANSFORMATION=RSA/ECB/OAEPWithSHA-256AndMGF1Padding

Cipher transformation migration: To ease migrating from the default RSA transformation to a more secure transformation with padding, the RSA is always used as possible fallback, in case decrypting a password failed for the configured transformation.

In order to use the keystore with the Encryption Service, you have two options:

  • By default, the service expects

    • the keystore file under the path ${user.home}/.cmservices/.keystore

    • and the password file under ${user.home}/.cmservices/.keystore.properties

  • If you want store the files under different paths you have to provide the following two system properties:

    • CM_KEYSTORE_LOCATION: location of the keystore file

    • CM_KEYSTORE_PASSWORD_FILE_LOCATION: location of the password file

Password Encryption

For each password you want to encrypt take the following steps:

  1. Login as a user who can access the keystore and password file. Switch to the installation directory of the command line tools and enter the following command where <plaintextpassword> should be replaced with the password you want to encrypt:

bin/cm encryptpasswordproperty <plaintextpassword>
  1. The command output is the encrypted password (which includes the curly brackets!) and some informational text. Use the -r option (bin/cm encryptpasswordproperty -r <plaintextpassword>) to have the tool just dump out the encrypted password without other information.

Note

Note

The tool will generate a unique value for the same plain text value each time you invoke it.

  1. Copy the password (including the curly brackets) into your respective properties file. You can append a comment after the closing curly bracket to add information. For example:

sql.store.password={G/7UZ7hPQnGZ/xX4J/7b8FNp/ybEH/JU
Qp5c8NRoDEQSlK5ypbkwotfu6j8U1SHr
QifmKeAQUvou/+ES34/pRHs=} --- generated by User xxx on 28/03/2013
Verify a password

If you want to verify that a given encrypted password actually represents a given plaintext password, use

cm encryptpasswordproperty -c <plaintext password> <encrypted entry>

where <plaintext password> should be replaced with the password and <encrypted entry> with the result of the encryption tool. The command will provide you with textual information whether these passwords match. The command returns with return value "0" whether the tokens match or not.

Troubleshooting

You must set the CM_KEYSTORE_LOCATION and CM_KEYSTORE_PASSWORD_FILE_LOCATION system properties not only for the encryptpasswordproperty tool, but also for the tool that uses the encrypted password, for instance schemaaccess.

View the respective component's log file. If an encrypted password cannot be decoded, you will see an error message in your log file telling you so. Since passwords decryption is verified early on (fail fast), you will find the error messages shortly after the component, service, or server starts.

Search Results

Table Of Contents
warning

Your Internet Explorer is no longer supported.

Please use Mozilla Firefox, Google Chrome, or Microsoft Edge.