Bring your own AES-256 key for Liberty passwords

The Bring your own AES-256 key feature allows you to supply a Base64-encoded 256-bit AES key for password encryption in Open Liberty. By providing a pre-generated key, you can avoid deriving a key from a passphrase during server startup and improve performance when encrypted values are processed.

In earlier versions, Open Liberty supported the wlp.password.encryption.key variable, which accepted a password and derived an AES key by repeatedly hashing the password with a salt over many iterations. This derivation increased CPU cost overhead and slowed server startup.

By specifying the wlp.aes.encryption.key configuration variable with a Base64-encoded 256-bit AES key, you bypass key derivation. The encoded password format remains unchanged, which supports migrations from traditional WebSphere Application Server (tWAS). Future migration tooling will allow tWAS encryption keys to be exported for use with Liberty.

Generate a 256-bit AES key

You can obtain a 256-bit AES key from your security infrastructure or generate one by using the securityUtility generateAESKey command.

To generate a random AES key, run the following command.

securityUtility generateAESKey

To derive a key from a passphrase, specify the --key option.

securityUtility generateAESKey --key=<password>

Optionally, To generate a key and automatically create an XML configuration file, use the following example.

securityUtility generateAESKey --createConfigFile=myAesConfig.xml

Configure the AES key in Liberty

To configure the AES key directly in your server.xml file, add the following variable definition.

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

Or to load the AES key from an external configuration file (such as the one generated by generateAESKey --createConfigFile), include the file by using the following configuration.

<include location="/path/to/aesConfig.xml" />

Encode passwords with the AES key

You can encode passwords that use the AES-256 key by running the securityUtility encode command.

To specify the Base64-encoded key directly, use the following options.

securityUtility encode --encoding=aes --base64Key=<your_base64_key> <password>

To use an XML or Java properties file that contains the AES key variable, specify the --aesConfigFile option:

securityUtility encode --encoding=aes --aesConfigFile=<xml_or_properties_file> <password>

Copy the resulting encrypted value into your Liberty configuration.

For best performance, re-encode all passwords by using the new AES-256 key. Open Liberty supports older password formats, but full migration provides consistent startup performance.

Liberty commands that support AES encryption accept the following options:

  • --base64Key or --passwordBase64Key: Provide the Base64-encoded AES-256 key directly.

  • --aesConfigFile: Provide a configuration file that defines either wlp.aes.encryption.key or wlp.password.encryption.key.

Updated certificate and key management tasks

The securityUtility createSSLCertificate and securityUtility createLTPAKeys commands support AES-based encryption options.

To generate an SSL certificate by using a Base64-encoded AES key for encrypting the keystore password, run the following command:

securityUtility createSSLCertificate \
  --password=password \
  --passwordEncoding=aes \
  --aesConfigFile=aesConfig.xml \
  --server=server1

The following example shows how to create LTPA keys by using a configuration file that contains the AES key definition:

securityUtility createLTPAKeys \
  --passwordEncoding=aes \
  --aesConfigFile=aesConfig.xml \
  --password=password \
  --file=ltpa.keys

New securityUtility task

The generateAESKey task generates a Base64-encoded 256-bit AES key for the wlp.aes.encryption.key variable.

To display command usage, see the following syntax:

securityUtility generateAESKey [options]

Description

Generates a value for the wlp.aes.encryption.key configuration variable. If no options are specified, a random AES key is generated.

Options

--createConfigFile=<name>

Creates an XML file that contains the generated AES key in the wlp.aes.encryption.key variable. If this option is omitted, the generated key is written to the console.

--key=<string>

Derives an AES key from the provided passphrase. If omitted, a random AES key is generated.

Configuration reference

The following variable, task, and command options support the Bring your own AES-256 key feature.

NameDescription

wlp.aes.encryption.key

Stores a Base64-encoded 256-bit AES key for password encryption.

generateAESKey

A securityUtility task that generates an AES-256 key and optionally writes it to an XML configuration file.

--base64Key=<value>

Specifies a Base64-encoded 256-bit AES key that is used to encrypt and decrypt passwords. Cannot be combined with --aesConfigFile or --key.

--aesConfigFile=<file>

Specifies an XML or properties file that contains either the wlp.password.encryption.key or wlp.aes.encryption.key variable. Only one variable can be present in a file. Cannot be combined with --base64Key or --key.

--passwordBase64Key=<value>

Used by SSL certificate and LTPA key utilities to encrypt generated passwords by using a Base64-encoded AES-256 key. Cannot be combined with --aesConfigFile or --passwordKey.