Bring your own AES-256 key for Liberty passwords

Liberty now allows you to provide a Base64-encoded 256-bit AES key for password encryption. This feature removes the need for Liberty to derive a key during startup, resulting in faster and more efficient password encryption.

What’s New?

Previously, Liberty supported the wlp.password.encryption.key property, which accepted a password and derived an AES key through a computationally intensive process. This derivation involved repeated hashing with a salt over many iterations, which added overhead during server startup.

Now, you can supply a pre-generated AES key directly. This eliminates the derivation step, resulting in faster startup times and improved runtime performance when encrypting and decrypting passwords.

Obtain 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 256-bit AES key using securityUtility, run the new generateAESKey task to:

  • Generate a random AES key:

    ./securityUtility generateAESKey

  • Optionally, save a random AES key to an XML file:

    ./securityUtility generateAESKey --createConfigFile=myAesConfig.xml

or

  • Generate a non-random AES key from a passphrase:

    ./securityUtility generateAESKey --key=<password>

  • Optionally, generate a non-random AES key from a passphrase and save it into an XML file:

    ./securityUtility generateAESKey --key=<password> --createConfigFile=myAesConfig.xml

Configure the 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>" />

Alternatively, you can load the AES key from an external configuration file, such as the one generated by the generateAESKey --createConfigFile command. The included file must contain the variable definition for wlp.aes.encryption.key as mentioned previously.

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

Encrypt your passwords

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

  • Provide the key directly:

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

  • Use an XML or Java properties file that contains the AES key variable:

    ./securityUtility encode --encoding=aes --aesConfigFile=<xml_or_properties_file_path> <password>

Copy the resulting encrypted value into your Liberty configuration.

Performance Tip: For best performance, re-encrypt 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

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.

The following command line tasks have been updated to accept Base64 keys and AES configuration files:

  • securityUtility: createSSLCertificate, createLTPAKeys, encode

  • configUtility: install

  • collective: create, join, replicate

Configuration reference

The following variable and 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 new securityUtility task that generates a Base64-encoded 256-bit AES key.

--base64Key=<value>

Specifies a Base64-encoded 256-bit AES key that is used to encrypt and decrypt passwords.

--aesConfigFile=<file>

Specifies an XML or properties file that contains either the wlp.password.encryption.key or wlp.aes.encryption.key variable.

--passwordBase64Key=<value>

Used by utilities to encrypt generated passwords by using a Base64-encoded AES-256 key.