Password encryption limitations

Open Liberty supports Advanced Encryption Standard (AES) encryption for passwords that are stored in the server.xml file. When you use this option for protecting passwords in the Open Liberty configuration, understand the limitations of the protection that AES encryption provides.

The Open 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, Open Liberty supports AES-128 and AES-256. Use --encoding=aes-128 to encrypt with AES-128 for compatibility with server versions before 25.0.0.2.

Starting in version 26.0.0.3, the securityUtility encode --encoding=aes command no longer uses a default encryption key. One of the following arguments must now be specified: --key, --base64Key, --aesConfigFile, or --keyring. Previous versions allowed AES encoding without an explicit key, falling back to a built-in default.

Encrypting a password in the Open Liberty configuration does not guarantee that the password is secure or protected. Encrypting a password means that someone who can see the encrypted password cannot easily recover the password unless they know the encryption key. The application server process requires access to the encrypted password and the decryption key, so these items must 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. If an attacker has access to the same set of files as the Open Liberty server, applying AES encryption to the password provides no additional security over XOR (exclusive OR) encoding. However, there are reasons why you might consider encrypting passwords in the Open Liberty configuration.

The Open Liberty configuration is composable and shareable. Open Liberty is designed to be configured without an administration subsystem, so any XOR-encoded password is visible to any administrator. Because of these design features, consider whether passwords are sensitive and need to be encrypted.

  • If passwords are not sensitive, encoding them might provide little value.

  • If passwords are sensitive, protect the configuration files or the encoding key, depending on the scenario.

Either the configuration files that contain the passwords are sensitive and access to these files must be controlled, or the passwords are encrypted and the encoding key is treated as sensitive and protected accordingly.

For more information about how to obfuscate passwords for Open Liberty, see the securityUtility encode command.

Encryption key protection

In Open Liberty, you can configure the encryption key that is used for encrypting and decrypting by setting either the wlp.password.encryption.key property or the wlp.aes.encryption.key property. For a more secure configuration, set the encryption key property in a separate file that is stored outside the Liberty installation directory. Otherwise, the file that contains the key might be included when you run the server dump or server package commands.

The separate configuration file must contain only a single property declaration. For example, /protected/key.xml could contain one of the following definitions:

<variable name="wlp.aes.encryption.key" value="<your_aes_key>" />

or

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

You cannot use wlp.aes.encryption.key and wlp.password.encryption.key at the same time.

You can include this configuration file in a server.xml file, as shown in the following example.

<server>
  ...
  <include location="/protected/key.xml" />
</server>

See also