The limits to protection through password encryption

Liberty supports Advanced Encryption Standard (AES) encryption for passwords that are stored in the server.xml file. When you use Advanced Encryption Standard (AES) encryption for protecting system passwords in the Liberty configuration, you need to understand the limits to the protection it provides.

The latest documentation about password encryption limitations for Liberty is available on the Open Liberty website.

[25.0.0.2 and later] The Liberty securityUtility encode command uses AES-256 encryption when the --encoding option is set to aes. The default value for this option is xor. For AES decryption, Liberty supports both AES-128 and AES-256.

Liberty supports AES-256 encryption for passwords stored in the server.xml configuration file. AES-256 provides stronger encryption, making encrypted passwords more secure.

To encrypt a password with AES-256, use the securityUtility encode command with the --encoding=aes option:

securityUtility encode --encoding=aes superAES256password

This command generates an AES-256 encrypted password, as shown in the following example:

{aes}ARAmkTCr3of9G0gvieyx7NtHFbeX5fiueD6yGTvnYzyFMxyg7Cd5V6Ew34uxunYb0pYixwDiR6V2qCx2Yxm9io4KBZiW8T9GJLCut1ClauY7GNBM6lFM+PMZfCaScPzUgSE07PJYI37WQ8lSzjaeWGCA+K5dlA==

You can then use this encrypted password in your server.xml, such as in a keystore definition:

<keyStore id="MyKeyStore" password="{aes}ARAmkTCr3of9G0gvieyx7NtHFbeX5fiueD6yGTvnYzyFMxyg7Cd5V6Ew34uxunYb0pYixwDiR6V2qCx2Yxm9io4KBZiW8T9GJLCut1ClauY7GNBM6lFM+PMZfCaScPzUgSE07PJYI37WQ8lSzjaeWGCA+K5dlA==" />

Important:

The AES key used for encryption is typically stored in a keystore such as aesKey.jceks used in WebSphere® Application Server traditional. Make sure that the keystore is accessible to the runtime server for decryption.
The Liberty securityUtility encode command uses AES-256 encryption when the --encoding option is set to aes. The default value for this option is xor. For AES decryption, Liberty supports AES-128 and AES-256. --encoding=aes-128 can be used to encrypt with AES-128 for compatibility with server versions before 25.0.0.2.

[25.0.0.12 and later] For information about supplying your own pre-generated AES-256 key for password encryption, including how to define wlp.aes.encryption.key, see Supplying your own AES-256 key for password encryption.

Encrypting a password in the Liberty configuration does not mean that the password is secure or protected; it only means that someone who can see the encrypted password, but does not know the encryption key, cannot easily recover the password. The application server process requires access to both the encrypted password and the decryption key, so both these data items need to be stored on the file system that is accessible to the server runtime environment. The encryption key is also required by anyone who encrypts a password that is placed in the server configuration. For an attacker that has access to exactly the same set of files as the Liberty server instance, applying AES encryption to the password therefore provides no additional security beyond exclusive or (XOR) encoding.

Nonetheless, there are still reasons why you might consider encrypting passwords in the Liberty configuration. The Liberty configuration is designed to be highly composable and sharable. The administration subsystem of WebSphere Application Server traditional (the administrative console and wsadmin scripting) prevents an administrator from gaining access to an XOR-encoded password. Liberty is designed to be configured without an administration subsystem, and so any XOR-encoded password is visible to any administrator. Given these design features, consider the following scenarios:

The passwords are not sensitive, so encoding them provides little value.
The passwords are sensitive, so either the configuration files containing the password are security sensitive and access needs to be controlled, or the passwords are encrypted and the encoding key is then protected as security sensitive.

The encryption key used for decrypting can be overridden from the default by setting the wlp.password.encryption.key property. To ensure that the file containing the key is not included when you are running the server dump or package command, do not set this property in the server.xml file that stores the password, but in a separate configuration file that is included by the server.xml file. This separate configuration file must contain only a single property declaration, and must be stored outside the normal configuration directory for the server. The encryption key property can also be specified as a bootstrap property. If you choose this option, put the encryption key in a separate properties file that is included in the server bootstrap.properties file.

Usage

The following examples demonstrate setting the wlp.password.encryption.key property.

How to define the property in the server.xml file.

<server>
  ...
  <variable name="wlp.password.encryption.key" value="yourKey" />
</server>

How to include the property as a separate file in the server.xml file.

<server>
  ...
  <include location="${shared.config.dir}/key.xml" />
</server>