Documentation, Bring your own AES-256 key for Liberty Secrets

[jacobwdv]

Feature epic details

• For the title of this issue, type: Documentation, Development epic name
• Link to development epic:Bring your own AES-256 key for Liberty Secrets open-liberty#31289
• Target GA release: 25.0.0.12

Operating systems

Does the documentation apply to all operating systems?

• [x ] Yes
• No; specify operating systems: ______

Summary

Provide a concise summary of your feature. What is the update, why does it matter, and to whom? What do 80% of target users need to know to be most easily productive using your runtime update?

This feature will allow customers to 'bring their own' AES 256 key by providing it as a base64 string in a new property (at the time of writing wlp.aes.encryption.key).

Bring Your Own AES-256 Key

The Bring Your Own AES-256 Key feature allows you to provide a Base64-encoded 256-bit AES key for password encryption in Liberty.

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.

With Bring Your Own AES-256 Key, you can now 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.

Why It Matters

This feature not only improves performance but also prepares for migration from traditional WebSphere (tWAS). The encoded password format remains the same, and future migration tools will allow you to export keys from tWAS for use in Liberty.

---

How to Enable It

1. Obtain a 256-bit AES key - Generate a 256-bit AES key using your own infrastructure and encode it in Base64, or by using securityUtility.

   • To generate a 256-bit AES key using securityUtility, run the new securityUtility generateAESKey task to:
     • Generate a random AES key:

       ./securityUtility generateAESKey

     • Derive a key from a passphrase:

       ./securityUtility generateAESKey --key=<password>

     • Optionally, use a configuration file with --createConfigFile which will output an xml file containing the necessary server configuration with the key entered in it.

2. Configure the key in Liberty
   Add the following variable in server.xml or an included file.

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

   or to include an external xml file (such as the one generated by generateAESKey --createConfigFile):

   <include location="/path/to/included/file" />

3. Encode your passwords
   Use securityUtility encode with one of these options:

   • Provide the key directly:

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

   • Specify an XML or properties file containing wlp.aes.encryption.key or *wlp.password.encryption.key. Note: * The aesKeyFile parameter now allows users to encode with either of the aes properties. :

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

4. Update configuration
   Copy the new encoded values into your server configuration.

---

Performance Tip: For best results, re-encode all passwords using the new key. Mixed usage of old and new formats is supported for backward compatibility, but full migration ensures optimal performance.

Other command line tasks have been updated to accept base64 keys and aes configuration files in a similar fashion:

1. securityUtility
   1. createSSLCertificate
   2. createLTPAKeys
   3. encode
2. configUtility
   1. install
3. collective
   1. create
   2. join
   3. replicate

Configuration

List any new or changed properties, parameters, elements, attributes, etc. Include default values and configuration examples where relevant:
A new configuration variable 'wlp.aes.encryption.key' which stores an AES-256bit key in base64 format
additional command line options to pre-existing command lines: securityUtility, configUtility and collective.
new task in securityUtility 'generateAesKey'.

Usage:
	securityUtility generateAESKey [options]

Description:
	Generates a value to be placed in configuration variable 
	wlp.aes.encryption.key for aes encryption.


Options:
    --createConfigFile=name
	Creates an XML file with the generated value saved in a variable
	named wlp.aes.encryption.key. If not provided, the generated value
	will be written to the console screen.

    --key=[key]
	This string is hashed to produce an encryption
	key that is used to encrypt and decrypt passwords. If this option is
	omitted, a random key is generated.

new parameters for other command lines shown below:

--aesConfigFile=aesConfigFile
	An XML or Java properties file with a variable named 
	wlp.password.encryption.key or wlp.aes.encryption.key with valid
	values respectively. Both variables cannot be specified in the same file.
	If --aesConfigFile is specified then --key and --base64Key cannot be specified.

--base64Key=base64Key
	A Base64-encoded AES-256 key is to be used to encrypt and decrypt the
	password. Provide this key to the server by defining the
	wlp.aes.encryption.key variable. If --base64Key is
	specified then --aesConfigFile and --key cannot be specified.

or

    --passwordBase64Key=base64Key
       A Base64-encoded AES-256 key is to be used to encrypt and decrypt the
	password. Provide this key to the server by defining the
	wlp.aes.encryption.key variable. If --passwordBase64Key is
       specified then --aesConfigFile and --passwordKey cannot be specified.

    --aesConfigFile=aesConfigFile
       An XML or Java properties file with a variable named 
       wlp.password.encryption.key or wlp.aes.encryption.key with valid
       values respectively. Both variables cannot be specified in the same file.
       If --aesConfigFile is specified then --passwordBase64Key and --passwordKey
       cannot be specified.

Updates to existing topics

We will need to add new command line parameters and task

The following parameters will be added to encode, collective and configUtility:

--base64Key
--aesConfigFile

securityUtility docs
collective join/create/replicate docs:
configUtility install docs

The following parameters will be added to createSSLCertificate and createLTPAKeys

--passwordBase64Key
--aesConfigFile

securityUtility createSSLCertificate
securityUtility createLTPAKeys:

Create a new topic

To create a topic, specify a first draft of the topic that you want added and the section in the navigation where the topic should go.

[arkarkala]

@ramkumar-k-9286 are you good with this info?

[ramkumar-k-9286]

Hi Jacob @jacobwdv

Made the following updates:

Created a new page for BYOK:

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/bring-your-own-aes-256-key.html

An additional new page for securityUtility generateAesKey:

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/securityUtility-generateAESKey.html

Updates in the following pages:

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/securityUtility-commands.html

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/securityUtility-encode.html

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/securityUtility-createSSLCertificate.html

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/securityUtility-createLTPAKeys.html

I have not updated the WL pages - collective join/create/replicate docs:
configUtility install docs I will make the updates as part of the WL update

Please review the same and let me know if corrections need to be made.

Regards,
Ramkumar.

[jacobwdv]

For https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/bring-your-own-aes-256-key.html : configUtility also allows --base64Key parameter. I can see you didn't want to provide all examples since it's pretty trivial but maybe it's worth calling out that all the commands have the option to specify the config file or directly specify the key?

For https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/securityUtility-generateAESKey.html
This looks good, there is a weird font problem in the options box at the bottom on firefox:

For https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/securityUtility-createSSLCertificate.html

The examples for aes are missing --passwordEncoding=aes

For https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/securityUtility-createLTPAKeys.html

The examples for aes are missing --passwordEncoding=aes

[jacobwdv]

After reviewing more with Ajay, could we please update instances where we say 'Secrets' to 'Passwords'? This is my fault, i prefer to say secret but in all our older documentation we refer to the encrypted values as 'passwords'.

For for example let's update this doc name Bring your own AES-256 key for Liberty Passwords

and all other references to 'secrets' we should change.

Also there is a hardening doc that needs updating (just found it now): https://openliberty.io/docs/latest/server-configuration-hardening.html#password-encryption

[ramkumar-k-9286]

Hi Jacob @jacobwdv

Incorporated suggested comments:

Please have a look.

BYOK: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/bring-your-own-aes-256-key.html

securityUtility generateAesKey: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/securityUtility-generateAESKey.html

securityUtility-commands: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/securityUtility-commands.html

securityUtility-encode: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/securityUtility-encode.html

Utility-createSSLCertificate: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/securityUtility-createSSLCertificate.html

securityUtility-createLTPAKeys: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/securityUtility-createLTPAKeys.html

hardening: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/server-configuration-hardening.html

Please add the Developer Reviewed label if you are satisfied with the changes.

Regards,
Ramkumar.

[jacobwdv]

BYOK: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/bring-your-own-aes-256-key.html

All Liberty command-line utilities that support AES encryption accept either of the following options:

    --base64Key: Provide the Base64-encoded AES key directly.

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

You can use it with the securityUtility, configUtility, and collective commands.

this is unfortunately not true, for the LTPA and SSL tasks it's passwordBase64Key. I had to update that in order to follow the pattern with passwordKey passwordEncoding, etc.