Merge pull request #7481 from OpenLiberty/7469-custom-password-encryp…

…tion-feature

7469-Custom-password-encryption-draft-1

modules/ROOT/pages/custom-password-encryption.adoc

@@ -0,0 +1,140 @@
+
+= Configure custom password encryption
+
+// Assisted by WCA@IBM
+// Latest GenAI contribution: ibm/granite-20b-code-instruct-v2
+Custom password encryption is a feature that allows users to customize the encryption algorithm that is used by the Liberty runtime to protect sensitive information such as passwords. This feature can be useful in situations where organizations have specific security requirements around how passwords are stored and managed.
+
+The following instructions will guide you through configuring custom password encryption in Open Liberty.
+
+1. Download and unpack Open Liberty +
+Ensure that you have the latest version of Open Liberty that is downloaded and unpacked.
++
+2. Place the required files +
+Place the following files in the specified directories.
++
+// Assisted by WCA@IBM
+// Latest GenAI contribution: ibm/granite-20b-code-instruct-v2
+[cols="2,2,6"]
+|===
+| Directory | File | Notes
+
+| `\wlp\usr\extension\lib`
+| https://www.ibm.com/support/pages/system/files/inline-files/com.ibm_.websphere.crypto.sample.customencryption_1.0_0.jar[com.ibm.websphere.crypto.sample.customencryption_1.0.jar]
+| This file contains the custom encryption logic.
+
+| `\wlp\usr\extension\lib\features`
+| https://www.ibm.com/support/pages/system/files/inline-files/customEncryption-1.0.mf_.txt[customEncryption-1.0.mf]
+| This file makes Liberty aware of the custom feature.
+
+| `\wlp\usr\servers\{server_name}`
+| https://https//www.ibm.com/support/pages/system/files/inline-files/server_1.xml[server.xml]
+| The configuration file for your server. 
+`\wlp\usr\servers\test\server.xml`
+The server name in this example is `test`.
+
+| `\wlp\bin\tools\extensions\ws-customPasswordEncryption`
+| https://https//www.ibm.com/support/pages/system/files/inline-files/customEncryption.jar[customEncryption.jar]
+| This file instructs `securityUtility` to use the custom feature.
+|===
++
+NOTE: If your uploaded files have different names, rename them to match the names listed in the table.
++
+3. Update `server.xml` +
+Edit the `server.xml` to include the custom encryption feature and configure the keystore.
+
+[source,xml]
+----
+<server description="Custom password encryption setup">
+    <!-- Enable features -->
+    <featureManager>
+        <feature>webProfile-8.0</feature>
+        <feature>usr:customEncryption-1.0</feature>
+    </featureManager>
+
+    <!-- Define the HTTP endpoint -->
+    <httpEndpoint id="defaultHttpEndpoint"
+                  httpPort="9080"
+                  httpsPort="9443" />
+
+    <!-- Automatically expand WAR files and EAR files -->
+    <applicationManager autoExpand="true"/>
+
+    <!-- Define the keystore with a plain text password initially -->
+    <keyStore id="defaultKeyStore" password="secret" />
+    <!-- Uncomment the following line to use the encrypted password -->
+    <!-- <keyStore id="defaultKeyStore" password="{custom}OhT339Bw3wymUcP92Mkz+Q==" /> -->
+</server>
+----
++
+4. Start the server +
+Start the server using the following command.
+
+[source,bash]
+----
+server start test
+----
+
+Verify that the keystore (`key.p12`) is created in `wlp\\usr\\servers\\test\\resources\\security` and can be accessed using the specified password.
+
+[source,bash]
+----
+keytool -list -keystore key.p12 -storepass secret -storetype PKCS12
+----
++
+5. Verify custom password encryption service +
+Check the `messages.log` file to confirm that the custom password encryption service has started. Look for entries similar to the following.
+
+[source,plaintext]
+----
+[2/11/21 16:56:50:292 EST] 00000020 com.ibm.ws.crypto.util.PasswordCipherUtil   I CWWKS1850I: The custom password encryption service has started. The class name is com.ibm.websphere.crypto.sample.customencryption.CustomEncryptionImpl.
+
+[2/11/21 16:56:52:776 EST] 0000002d com.ibm.ws.kernel.feature.internal.FeatureManager   A CWWKF0012I: The server installed the following features: [appSecurity-2.0, appSecurity-3.0, beanValidation-2.0, cdi-2.0, distributedMap-1.0, ejbLite-3.2, el-3.0, jaspic-1.1, jaxrs-2.1, jaxrsClient-2.1, jdbc-4.2, jndi-1.0, jpa-2.2, jpaContainer-2.2, jsf-2.3, jsonb-1.0, jsonp-1.1, jsp-2.3, managedBeans-1.0, servlet-4.0, ssl-1.0, usr:customEncryption-1.0, webProfile-8.0, websocket-1.1].
+----
++
+6. Stop the server +
+Stop the server with the following command.
+
+[source,bash]
+----
+server stop test
+----
++
+7. Encrypt the password +
+Unlike traditional WebSphere, enabling custom password encryption in Open Liberty doesn't automatically encrypt passwords in `server.xml`. Use the `securityUtility` command to encrypt passwords manually.
++
+8. Confirm custom encryption is enabled +
+Run the following command to list custom encryption encodings.
+
+[source,bash]
+----
+securityUtility encode --listCustom
+----
++
+Ensure that `custom` is listed as an available encoding.
++
+9. Encode and update password +
+Encrypt the password using the following command.
+
+[source,bash]
+----
+securityUtility encode --encoding=custom secret
+----
++
+Replace the plain text password in `server.xml` with the encrypted one.
+
+[source,xml]
+----
+<keyStore id="defaultKeyStore" password="{custom}OhT339Bw3wymUcP92Mkz+Q==" />
+----
++
+10. Restart the server +
+Start the server again to ensure that the keystore opens successfully with the encrypted password.
+
+[source,plaintext]
+----
+[3/31/21 21:37:32:638 EDT] 00000029 com.ibm.ws.ssl.config.WSKeyStore    I Successfully loaded default keystore: c:/LibertyRuntime/wlp-webProfile8-21.0.0.1/wlp/usr/servers/test/resources/security/key.p12 of type: PKCS12
+----
+
+For more information on password encryption limitations, see the xref:password-encryption.adoc[Password encryption limitations].
+