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

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

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.
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" />
```
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>
```
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:

securityUtility
1. createSSLCertificate
2. createLTPAKeys
3. encode
configUtility
1. install
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.

@ramkumar-k-9286

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

8021-updates-2-multiple-pages-1

@jacobwdv

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.

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

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

8021-byok-comment-incorporation-2

@jacobwdv

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.

byok-corrections-3

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.

byok-comment-inc-1

@jacobwdv

Hi jake @jacobwdv

Incorporated comments:

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

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

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

Regards,
Ramkumar.

byok-update-remove-collective-1

@jacobwdv

Hi Jacob @jacobwdv

Made the changes we discussed on Slack. 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.

in Configuration Reference:

I would remove only one AES-related variable can be defined in a configuration file. , it's a true statement wrt to the command lines but users can still define both wlp.password.encryption.key and wlp.aes.encryption.key in the same server configuration.

for return codes:

It should be 0 on success and 1 on failure. THat is my mistake i see in slack i mixed the two up, sorry about that.

for createSSLCertificate we need to pass in --password for that one and there is no outputFile parameter. Here is a sample invocation:

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

For LTPA there is no --outputFile parameter, it's --file, also --password is needed, here is a command exacmple

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

byok-updates-ssl-ltpa

updates-byok

update-generateAESKey-exitcodes

@jacobwdv

@jacobwdv

Suggested corrections have been done. Not adding the links here again.

Please let me know if you want more changes to the docs.

Regards,
Ramkumar

@arkarkala

@arkarkala before i add the Developer Reviewed label can you review #8021 (comment)

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

can you please sync this with the blog post? the text in here is basically copy/paste from the blog post, ajay and i updated it recently to be more clear.

Blog post: OpenLiberty/open-liberty#33391

Could we add a link to the new BYOK landing page in https://openliberty.io/docs/latest/password-encryption.html , just so customers reading about password encryption are easily guided to the new feature?

the last few suggestions came after it was too late, we plan to add them post GA of 25.0.0.12

Doc completed and published.

Link: https://openliberty.io/docs/latest/bring-your-own-aes-256-key.html

The last few suggestions came after doc freeze. We plan to add them in the 26.0.0.1 release.

A separate issue created for follow-up doc updates - #8088

Navigation Menu

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

Feature epic details

Operating systems

Summary

Bring Your Own AES-256 Key

What’s New?

Why It Matters

How to Enable It

Configuration

Updates to existing topics

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

The following parameters will be added to createSSLCertificate and createLTPAKeys

Create a new topic

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

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

Description

Feature epic details

Operating systems

Summary

Bring Your Own AES-256 Key

What’s New?

Why It Matters

How to Enable It

Configuration

Updates to existing topics

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

The following parameters will be added to createSSLCertificate and createLTPAKeys

Create a new topic

Activity

arkarkala commented on Nov 10, 2025

ramkumar-k-9286 commented on Nov 18, 2025

jacobwdv commented on Nov 18, 2025

jacobwdv commented on Nov 18, 2025

ramkumar-k-9286 commented on Nov 19, 2025

jacobwdv commented on Nov 19, 2025

ramkumar-k-9286 commented on Nov 19, 2025

ramkumar-k-9286 commented on Nov 20, 2025

jacobwdv commented on Nov 20, 2025

ramkumar-k-9286 commented on Nov 20, 2025

jacobwdv commented on Nov 20, 2025

jacobwdv commented on Nov 25, 2025

jacobwdv commented on Nov 25, 2025

jacobwdv commented on Nov 26, 2025

ramkumar-k-9286 commented on Jan 15, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions