Skip to content

Commit c9f1cc6

Browse files
ramkumar-k-9286ramkumar-k-9286
authored
Merge pull request #8083 from OpenLiberty/staging
v250012-stg-vnxt
2 parents fea3107 + e86eb66 commit c9f1cc6

9 files changed

Lines changed: 388 additions & 0 deletions

‎modules/ROOT/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,7 @@
8787
** xref:network-hardening.adoc[Network]
8888
** xref:application-configuration-hardening.adoc[Application configuration]
8989
* xref:password-encryption.adoc[Password encryption limitations]
90+
* xref:bring-your-own-aes-256-key.adoc[Bring your own AES-256 key for Liberty Passwords]
9091
* xref:audit-logs.adoc[Audit logs]
9192
* xref:verifying-package-signatures.adoc[Verifying release package signatures]
9293
* xref:enable-fips.adoc[Run FIPS-compliant applications]

‎modules/ROOT/pages/bring-your-own-aes-256-key.adoc‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
// Copyright (c) 2025 IBM Corporation and others.
2+
// Licensed under Creative Commons Attribution-NoDerivatives
3+
// 4.0 International (CC BY-ND 4.0)
4+
// https://creativecommons.org/licenses/by-nd/4.0/
5+
//
6+
// Contributors:
7+
// IBM Corporation
8+
//
9+
:page-description: 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.
10+
:seo-title: Bring your own AES-256 key for Liberty passwords
11+
:page-layout: general-reference
12+
:page-type: general
13+
14+
15+
= Bring your own AES-256 key for Liberty passwords
16+
17+
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.
18+
19+
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.
20+
21+
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.
22+
23+
== Generate a 256-bit AES key
24+
25+
You can obtain a 256-bit AES key from your security infrastructure or generate one by using the `securityUtility generateAESKey` command.
26+
27+
To generate a random AES key, run the following command.
28+
29+
[source,sh]
30+
----
31+
securityUtility generateAESKey
32+
----
33+
34+
To derive a key from a passphrase, specify the `--key` option.
35+
36+
[source,sh]
37+
----
38+
securityUtility generateAESKey --key=<password>
39+
----
40+
41+
Optionally, To generate a key and automatically create an XML configuration file, use the following example.
42+
43+
[source,sh]
44+
----
45+
securityUtility generateAESKey --createConfigFile=myAesConfig.xml
46+
----
47+
48+
== Configure the AES key in Liberty
49+
50+
To configure the AES key directly in your `server.xml` file, add the following variable definition.
51+
52+
[source,xml]
53+
----
54+
<variable name="wlp.aes.encryption.key" value="<your_aes_key>" />
55+
----
56+
57+
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.
58+
59+
[source,xml]
60+
----
61+
<include location="/path/to/aesConfig.xml" />
62+
----
63+
64+
== Encode passwords with the AES key
65+
66+
You can encode passwords that use the AES-256 key by running the `securityUtility encode` command.
67+
68+
To specify the Base64-encoded key directly, use the following options.
69+
70+
[source,sh]
71+
----
72+
securityUtility encode --encoding=aes --base64Key=<your_base64_key> <password>
73+
----
74+
75+
To use an XML or Java properties file that contains the AES key variable, specify the `--aesConfigFile` option:
76+
77+
[source,sh]
78+
----
79+
securityUtility encode --encoding=aes --aesConfigFile=<xml_or_properties_file> <password>
80+
----
81+
82+
Copy the resulting encrypted value into your Liberty configuration.
83+
84+
[NOTE]
85+
====
86+
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.
87+
88+
89+
Liberty commands that support AES encryption accept the following options:
90+
91+
* `--base64Key` or `--passwordBase64Key`: Provide the Base64-encoded AES-256 key directly.
92+
93+
* `--aesConfigFile`: Provide a configuration file that defines either `wlp.aes.encryption.key` or `wlp.password.encryption.key`.
94+
====
95+
96+
== Updated certificate and key management tasks
97+
98+
The `securityUtility createSSLCertificate` and `securityUtility createLTPAKeys` commands support AES-based encryption options.
99+
100+
To generate an SSL certificate by using a Base64-encoded AES key for encrypting the keystore password, run the following command:
101+
102+
[source,sh]
103+
----
104+
securityUtility createSSLCertificate \
105+
--password=password \
106+
--passwordEncoding=aes \
107+
--aesConfigFile=aesConfig.xml \
108+
--server=server1
109+
----
110+
111+
The following example shows how to create LTPA keys by using a configuration file that contains the AES key definition:
112+
113+
[source,sh]
114+
----
115+
securityUtility createLTPAKeys \
116+
--passwordEncoding=aes \
117+
--aesConfigFile=aesConfig.xml \
118+
--password=password \
119+
--file=ltpa.keys
120+
----
121+
122+
== New securityUtility task
123+
124+
The `generateAESKey` task generates a Base64-encoded 256-bit AES key for the `wlp.aes.encryption.key` variable.
125+
126+
To display command usage, see the following syntax:
127+
128+
[source,sh]
129+
----
130+
securityUtility generateAESKey [options]
131+
----
132+
133+
=== Description
134+
135+
Generates a value for the `wlp.aes.encryption.key` configuration variable. If no options are specified, a random AES key is generated.
136+
137+
=== Options
138+
139+
`--createConfigFile=<name>`::
140+
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.
141+
142+
`--key=<string>`::
143+
Derives an AES key from the provided passphrase. If omitted, a random AES key is generated.
144+
145+
== Configuration reference
146+
147+
The following variable, task, and command options support the Bring your own AES-256 key feature.
148+
149+
[cols="30,70", options="header"]
150+
|===
151+
| Name | Description
152+
153+
| `wlp.aes.encryption.key`
154+
| Stores a Base64-encoded 256-bit AES key for password encryption.
155+
156+
| `generateAESKey`
157+
| A `securityUtility` task that generates an AES-256 key and optionally writes it to an XML configuration file.
158+
159+
| `--base64Key=<value>`
160+
| Specifies a Base64-encoded 256-bit AES key that is used to encrypt and decrypt passwords. Cannot be combined with `--aesConfigFile` or `--key`.
161+
162+
| `--aesConfigFile=<file>`
163+
| 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`.
164+
165+
| `--passwordBase64Key=<value>`
166+
| 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`.
167+
|===
168+

‎modules/ROOT/pages/security-vulnerabilities.adoc‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,13 @@ The `CWWKF0012I` message uses the word "installed", but it lists features that a
2828
|===
2929
|CVE |CVSS score |Vulnerability assessment |Versions affected |Version fixed |Notes
3030

31+
|https://www.cve.org/CVERecord?id=CVE-2025-7962[CVE-2025-7962]
32+
|7.5
33+
|SMTP injection
34+
|17.0.0.3-25.0.0.11
35+
|25.0.0.12
36+
|Affects the feature:javaMail-1.5[], feature:javaMail-1.6[], feature:mail-2.0[] and feature:mail-2.1[] features
37+
3138
|https://www.cve.org/CVERecord?id=CVE-2020-36732[CVE-2020-36732]

3239
|5.3

3340
|Weaker security

‎modules/ROOT/pages/server-configuration-hardening.adoc‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -182,3 +182,28 @@ For more information, see xref:password-encryption.adoc[Password encryption limi
182182
With AES encryption, the default encryption key that is used for decryption can be overridden by setting the `wlp.password.encryption.key` property.
183183
This property must not be set in the `server.xml` file, but in a separate configuration file that is included by the `server.xml` file.
184184
This separate configuration file must contain only a single property declaration, and must be stored outside the normal configuration directory for the server.
185+
186+
[#pre-gen-aes256-key]
187+
=== Use a pre-generated AES-256 key
188+
189+
Open Liberty also supports supplying your own Base64-encoded AES key for password encryption.
190+
This key is defined in the `wlp.aes.encryption.key` variable and improves performance by avoiding the key-derivation process that is required during server start.
191+
192+
You can generate an AES key by using the `securityUtility generateAESKey` command.
193+
This command can generate a random key or derive a key from a passphrase.
194+
195+
[source,sh]
196+
----
197+
securityUtility generateAESKey --createConfigFile=myAesKey.xml
198+
----
199+
200+
You can define the generated key directly in `server.xml` or in an included configuration file.
201+
202+
[source,xml]
203+
----
204+
<variable name="wlp.aes.encryption.key" value="<base64_key>" />
205+
----
206+
207+
For more information, see xref:bring-your-own-aes-256-key.adoc[Bring your own AES-256 key for Liberty passwords].
208+
209+

‎modules/reference/pages/command/securityUtility-commands.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ The following `securityUtility` commands are available:
2222

2323
* xref:command/securityUtility-createLTPAKeys.adoc[securityUtility createLTPAKeys]: The command creates a set of LTPA keys for use by the server, or that can be shared with multiple servers.
2424
* xref:command/securityUtility-createSSLCertificate.adoc[securityUtility createSSLCertificate]: The command supports TLS certificate creation for Open Liberty.
25+
* xref:command/securityUtility-generateAESKey.adoc[securityUtility generateAESKey]: Generates a Base64-encoded 256-bit AES key for use with password encryption in Open Liberty.
2526
* xref:command/securityUtility-encode.adoc[securityUtility encode]: The command supports plain text obfuscation for Open Liberty.
2627
* xref:command/securityUtility-help.adoc[securityUtility help]: The command displays information about the `securityUtility` command, with details about its actions and options.
2728

‎modules/reference/pages/command/securityUtility-createLTPAKeys.adoc‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,28 @@ Create LTPA keys with the `mypassword` password that is encrypted with Advanced
3535
securityUtility createLTPAKeys --password=mypassword --passwordEncoding=aes
3636
----
3737

38+
Create LTPA keys by using a Base64-encoded AES key to encrypt the LTPA password, specify the `--passwordBase64Key` option:
39+
40+
[source,sh]
41+
----
42+
securityUtility createLTPAKeys \
43+
--password=password \
44+
--passwordEncoding=aes \
45+
--passwordBase64Key=<your_base64_key> \
46+
--file=ltpa.keys
47+
----
48+
49+
Create LTPA keys by using a configuration file that contains the AES key variable:
50+
51+
[source,sh]
52+
----
53+
securityUtility createLTPAKeys \
54+
--password=password \
55+
--passwordEncoding=aes \
56+
--aesConfigFile=aesConfig.xml \
57+
--file=ltpa.keys
58+
----
59+
3860
== Syntax
3961

4062
Run the command from the `_path_to_liberty_/wlp/bin` directory.
@@ -73,6 +95,16 @@ You can use the `securityUtility encode --listCustom` command to see if any addi
7395
This string is hashed to produce an encryption key that is used to encrypt and decrypt the password.
7496
You can provide the key by defining the `wlp.password.encryption.key` variable as the key value.
7597
If this option isn't specified, a default key is used.
98+
This option cannot be combined with `--passwordBase64Key` or `--aesConfigFile`.
99+
100+
|--passwordBase64Key=<key>
101+
|Specifies a Base64-encoded 256-bit AES key that is used to encrypt the generated LTPA password.
102+
This option cannot be combined with `--aesConfigFile` or `--passwordKey`.
103+
104+
|--aesConfigFile=<file>
105+
|Specifies an XML or Java properties file that contains either the `wlp.password.encryption.key` or `wlp.aes.encryption.key` variable.
106+
Only one variable can be present in a file.
107+
This option cannot be combined with `--passwordBase64Key` or `--passwordKey`.
76108

77109
|--server=_name_
78110
|Specifies the name of the Open Liberty server for which the LTPA keys are created.

‎modules/reference/pages/command/securityUtility-createSSLCertificate.adoc‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,31 @@ Create a TLS certificate for the `myserver` server with the `mypassword` passwor
2828
securityUtility createSSLCertificate --server=myserver --password=mypassword --validity=365
2929
----
3030

31+
32+
Create an SSL certificate by using a Base64-encoded AES-256 key to encrypt the keystore password, specify the `--passwordBase64Key` option:
33+
34+
[source,sh]
35+
----
36+
securityUtility createSSLCertificate \
37+
--password=password \
38+
--passwordEncoding=aes \
39+
--passwordBase64Key=<your_base64_key> \
40+
--server=server1
41+
----
42+
43+
44+
Create an SSL certificate by using a configuration file that contains the AES key variable:
45+
46+
[source,sh]
47+
----
48+
securityUtility createSSLCertificate \
49+
--password=password \
50+
--passwordEncoding=aes \
51+
--aesConfigFile=aesConfig.xml \
52+
--server=server1
53+
----
54+
55+
3156
== Syntax
3257

3358
Run the command from the `_path_to_liberty_/wlp/bin` directory. You must specify either the `server` or `client` option or the command fails. The keystore password must be at least six characters long. If the `password` option is not specified, you’re prompted for a password value when you run this command.
@@ -97,6 +122,16 @@ If this option isn't specified, a default encoding type of `xor` is used.
97122
This string is hashed to produce an encryption key that is used to encrypt and decrypt the password.
98123
You can provide the key by defining the `wlp.password.encryption.key` variable as the key value.
99124
If this option isn't specified, a default key is used.
125+
This option cannot be combined with `--passwordBase64Key` or `--aesConfigFile`.
126+
127+
|--passwordBase64Key=<Key>
128+
|Specifies a Base64-encoded 256-bit AES key that is used to encrypt the generated keystore password.
129+
This option cannot be combined with `--aesConfigFile` or `--passwordKey`.
130+
131+
|--aesConfigFile=<File>
132+
|Specifies an XML or Java properties file that contains either the `wlp.password.encryption.key` or `wlp.aes.encryption.key` variable.
133+
Only one variable can be present in a file.
134+
This option cannot be combined with `--passwordBase64Key` or `--passwordKey`.
100135

101136
|--server=_name_
102137
|Specifies the name of the Open Liberty server for which the keystore and certificate are created.

‎modules/reference/pages/command/securityUtility-encode.adoc‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,26 @@ Hash a password. After you enter this command, interactive mode prompts you for
4141
securityUtility encode --encoding=hash
4242
----
4343

44+
Encode a password by using a Base64-encoded AES key, specify the key directly:
45+
46+
[source,sh]
47+
----
48+
securityUtility encode --encoding=aes --base64Key=<your_base64_key> MyPassword
49+
----
50+
51+
Use a configuration file that contains the AES key variable, specify the `--aesConfigFile` option:
52+
53+
[source,sh]
54+
----
55+
securityUtility encode --encoding=aes --aesConfigFile=aesConfig.xml MyPassword
56+
----
57+
58+
[NOTE]
59+
====
60+
The configuration file must contain either the `wlp.aes.encryption.key` or `wlp.password.encryption.key` variable. Only one variable can be present in a file.
61+
====
62+
63+
4464
== Syntax
4565

4666
Run the command from the `_path_to_liberty_/wlp/bin` directory.
@@ -76,6 +96,7 @@ When FIPS 140-3 is enabled, both the `aes` and `hash` options use enhanced algor
7696
This string is hashed to produce an encryption key that is used to encrypt and decrypt the password.
7797
You can provide the key by defining the `wlp.password.encryption.key` variable as the key value.
7898
If this option isn't specified, a default key is used.
99+
This option cannot be combined with `--base64Key` or `--aesConfigFile`.
79100

80101
|--listCustom
81102
a|Displays the information of the custom password encryption in JSON format.
@@ -90,6 +111,15 @@ The information consists of the following things:
90111
If this option is specified, the provided text is encoded as it is.
91112
If this option isn't specified, space characters are removed from the beginning and end of the specified text.
92113

114+
|--base64Key=<key>
115+
|Specifies a Base64-encoded 256-bit AES key that is used to encrypt and decrypt the password.
116+
This option cannot be combined with `--aesConfigFile` or `--key`.
117+
118+
|--aesConfigFile=<file>
119+
|Specifies an XML or Java properties file that contains either the `wlp.password.encryption.key` or `wlp.aes.encryption.key` variable.
120+
Only one of these variables can be present in a file.
121+
This option cannot be combined with `--base64Key` or `--key`.
122+
93123
|===
94124

95125
== Exit codes
@@ -145,3 +175,4 @@ pa$$W0rd
145175
146176
$ securityUtility encode pa\$\$W0rd
147177
----
178+

0 commit comments

Comments
 (0)