docs(notes): update WebSphere AES encryption notes

Author: lzwjava

notes/2025-03-25-websphere-aes-en.md

@@ -183,4 +183,106 @@ bin/securityUtility encode --encoding=aes "suspectedpassword"
   You’d need to replicate the environment or use the Java approach above.
 - **Default Key**: If no custom key was set, Liberty uses a default key, but this is still only accessible within the server runtime, not via `securityUtility`.
 
-Since `securityUtility decode` isn’t an option, the Java program is your best bet if you need the original password. If that’s not feasible, resetting it is the simplest workaround. Let me know which approach you’d like to pursue or if you need help with the setup!
+Since `securityUtility decode` isn’t an option, the Java program is your best bet if you need the original password. If that’s not feasible, resetting it is the simplest workaround. Let me know which approach you’d like to pursue or if you need help with the setup!
+
+---
+
+In WebSphere Liberty, when a custom key is specified with `<variable name="wlp.password.encryption.key" value="yourCustomKey"/>` in `server.xml`, it refers to a user-defined **plaintext encryption key** (a string), not a keystore file (like a `.keystore` or `.p12` file) or a cryptographic key from a `server.properties` file. This custom key is used by Liberty’s AES encryption mechanism to encrypt and decrypt sensitive data, such as passwords in `server.xml`. It’s distinct from SSL/TLS keystores or other key management systems like JKS or PKCS12 files, which are typically used for securing network communication rather than password encryption.
+
+Let me clarify what this "custom key" means and how it relates to your question:
+
+---
+
+### What is the Custom Key (`wlp.password.encryption.key`)?
+- **Definition**: The `wlp.password.encryption.key` is a variable that specifies a custom string (e.g., `yourCustomKey`) used as the encryption key for AES password encryption in Liberty. This overrides the default encryption key that Liberty generates internally.
+- **Purpose**: It allows administrators to control the encryption key explicitly, ensuring that encrypted values (like `{aes}YSPuwMQqjeo/DlSNYnUZ3E6z6WLVmEaAtDmMaFg6JCY=`) are portable across servers or reproducible, provided the same custom key is used.
+- **Format**: It’s a plaintext string, not a file reference or a cryptographic key in a keystore. For example:
+  ```xml
+  <variable name="wlp.password.encryption.key" value="mySecretKey123"/>
+  ```
+- **Usage**: When you run `securityUtility encode --encoding=aes "myPassword"` with a custom key defined, Liberty uses that key instead of its default key to generate the encrypted output.
+
+---
+
+### Is It Related to `server.properties`, `.keystore`, or `.p12` Files?
+- **No, it’s not a keystore or `.p12` file**: Keystores (e.g., JKS or PKCS12 `.p12` files) are used in Liberty for SSL/TLS configurations (e.g., `<keyStore id="defaultKeyStore" .../>` in `server.xml`) to store certificates and private keys for secure communication. The `wlp.password.encryption.key` is unrelated to these; it’s specifically for encrypting configuration data like passwords.
+- **No direct relation to `server.properties`**: There’s no standard `server.properties` file in Liberty. You might be thinking of `bootstrap.properties` or `jvm.options`, which are optional configuration files:
+  - **Bootstrap.properties**: You *could* define the custom key here instead of `server.xml`, like this:
+    ```
+    wlp.password.encryption.key=mySecretKey123
+    ```
+    Liberty would then use this value for AES encryption/decryption.
+  - However, `wlp.password.encryption.key` is typically set in `server.xml` as a `<variable>` element, not tied to a keystore or properties file unless explicitly configured that way.
+
+---
+
+### How the Custom Key Works in Context
+- **Default Behavior**: If `wlp.password.encryption.key` is not specified, Liberty generates an internal default key unique to the server instance. This key isn’t exposed and is managed internally, making encrypted passwords non-portable across servers.
+- **Custom Key**: When you define `wlp.password.encryption.key`, Liberty uses that string as the AES encryption key. For example:
+  ```xml
+  <variable name="wlp.password.encryption.key" value="mySecretKey123"/>
+  ```
+  Then, running:
+  ```bash
+  bin/securityUtility encode --encoding=aes "myPassword"
+  ```
+  produces an AES-encrypted value based on `mySecretKey123`. The same key must be present to decrypt it (e.g., via a Java program running in that server context).
+
+---
+
+### Decoding with a Custom Key
+Since `securityUtility` doesn’t offer a `decode` option, you need to use a Java program like the one I provided earlier (`PasswordUtil.decode`), and it must run in the Liberty server context where the custom key is defined. Here’s why:
+- The `PasswordUtil` class automatically retrieves the `wlp.password.encryption.key` value from the server’s configuration (e.g., `server.xml` or `bootstrap.properties`) when running in that environment.
+- If you run the program outside the server context, you’d need to manually supply the custom key, but `PasswordUtil` doesn’t provide a public API to pass the key directly—it relies on the runtime configuration.
+
+Updated Java example with context awareness:
+```java
+import com.ibm.websphere.crypto.PasswordUtil;
+
+public class DecodeAesPassword {
+    public static void main(String[] args) {
+        String encryptedPassword = "{aes}YSPuwMQqjeo/DlSNYnUZ3E6z6WLVmEaAtDmMaFg6JCY=";
+        try {
+            String decryptedPassword = PasswordUtil.decode(encryptedPassword);
+            System.out.println("Decrypted Password: " + decryptedPassword);
+        } catch (Exception e) {
+            System.err.println("Error decoding password: " + e.getMessage());
+        }
+    }
+}
+```
+- **Run this**:
+  - Deploy it as a simple app on the Liberty server with the custom key defined.
+  - Ensure the `server.xml` includes `<variable name="wlp.password.encryption.key" value="yourCustomKey"/>`.
+  - The program will use `yourCustomKey` to decrypt the password.
+
+---
+
+### Answering Your Question Directly
+- **Custom key ≠ `.keystore` or `.p12`**: It’s not a reference to a keystore file or a cryptographic key in a `.p12` format. It’s a plaintext string you define.
+- **Not tied to `server.properties`**: Liberty doesn’t use a `server.properties` file by default, but you could define the key in `bootstrap.properties` if preferred. Typically, it’s in `server.xml`.
+
+---
+
+### What to Do Next
+1. **Check for the Custom Key**:
+   - Look in your `server.xml` for:
+     ```xml
+     <variable name="wlp.password.encryption.key" value="yourCustomKey"/>
+     ```
+   - Or in `bootstrap.properties` for:
+     ```
+     wlp.password.encryption.key=yourCustomKey
+     ```
+   - If it’s not defined, Liberty used a default key, and decoding requires running in the server context.
+
+2. **Decode the Password**:
+   - Use the Java program above, executed on the Liberty server with the custom key configured.
+   - If you know the custom key (e.g., `yourCustomKey`), you can also test encoding a suspected plaintext password to see if it matches the encrypted value:
+     ```bash
+     bin/securityUtility encode --encoding=aes --key=yourCustomKey "suspectedPassword"
+     ```
+
+3. **Fallback**: If decoding isn’t practical, reset the Oracle password and re-encrypt it with `securityUtility` using the same custom key.
+
+Let me know if you’ve found the custom key in your setup or need help running the Java code!