Configure custom password encryption

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.

DirectoryFileNotes

\wlp\usr\extension\lib

com.ibm.websphere.crypto.sample.customencryption_1.0.jar

This file contains the custom encryption logic.

\wlp\usr\extension\lib\features

customEncryption-1.0.mf

This file makes Liberty aware of the custom feature.

\wlp\usr\servers\<server_name>

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

customEncryption.jar

This file instructs securityUtility to use the custom feature.

If your uploaded files have different names, rename them to match the names listed in the table.

  1. Update server.xml.
    Edit the server.xml to include the custom encryption feature and configure the keystore.

<server description="Custom password encryption setup">
    <!-- Enable features -->
    <featureManager>
        <feature>webProfile-8.0</feature>
        <feature>usr:customEncryption-1.0</feature>
    </featureManager>

    <!-- To access this server from a remote client add a host attribute to the following element, e.g. host="*" -->
    <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>

  1. Start the server
    Start the server using the following command.

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.

keytool -list -keystore key.p12 -storepass secret -storetype PKCS12

  1. 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.

[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].

  1. Stop the server.
    Stop the server with the following command.

server stop test

  1. Encrypt the password.
    Unlike traditional WebSphere, enabling custom password encryption in Open Liberty does not automatically encrypt passwords in server.xml. Use the securityUtility command to encrypt passwords manually.

  2. Confirm custom encryption is enabled.
    Run the following command to list custom encryption encodings.

securityUtility encode --listCustom

[{"name":"custom","featurename":"usr:customEncryption-1.0","description":"%description"}]

Ensure that custom is listed as an available encoding.

  1. Encode and update password.
    Encrypt the password using the following command.

securityUtility encode --encoding=custom secret

Replace the plain text password in server.xml with the encrypted one.

<keyStore id="defaultKeyStore" password="{custom}OhT339Bw3wymUcP92Mkz+Q==" />

  1. Restart the server.
    Start the server again to ensure that the keystore opens successfully with the encrypted password.

[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 Password encryption limitations.