IBM Support

How to set up a custom password encryption for WebSphere Liberty

How To


Summary

This article shows how to set up a custom password encryption for WebSphere Liberty

Environment

  • This article was tested with WebSphere Liberty 21.0.0.1 on Windows 10. 
  • In this example, server name is "test" 

Steps

1.  Download and unpack WebSphere Liberty or OpenLiberty
2.  Place following files according to the directory location in the table. 
(Note: Uploaded file may have a little different file name.  Please rename them according to the name in the table) 
Directory File Notes
\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 there is a user feature. 
\wlp\usr\servers\(server_name) server.xml
\wlp\usr\servers\test\server.xml
The server name in this example is "test"  
\wlp\bin\tools\extensions\ws-customPasswordEncryption customEncryption.jar This file tells securityUtility to use the user feature. 
3.  In the sample server.xml, note that "usr:customEncryption-1.0" user feature defined.  Also make sure the server.xml has the keyStore configuration with plain text password.  In this example, the password is "secret" first. 
    <keyStore id="defaultKeyStore" password="secret" />
This tells Liberty to create the default key store (\wlp\usr\servers\test\resources\security\key.p12) with the password when the server started for the first time.  We will replace this plain text password with the custom encrypted password later. 
server.xml 

<?xml version="1.0" encoding="UTF-8"?>

<server description="new server">

    <!-- 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"/>

    <keyStore id="defaultKeyStore" password="secret" />

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

</server>

4. Start the server by running following command. test is the server name. 
     wlp\bin> server start test 
Once the server is started, make sure the keystore (key.p12) is created under (wlp\usr\servers\test\resources\security) and can be opened using the specified password. 
     wlp\usr\servers\test\resources\security> keytool -list -keystore key.p12 -storepass secret -storetype PKCS12
5.  Open the messages.log file to confirm the custom password encryption service is started. The usr:customEncryption-1.0 is displayed as the installed feature. 

[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 by 
     wlp\bin> server stop test 
7.  Unlike traditional WebSphere, enabling the custom password encryption service does not automatically encrypt the passwords in the server.xml in Liberty. The password can be encrypted by the securityUtility command in \wlp\bin directory. 
8. First, run "securityUtility encode --listCustom" to confirm that the custom encryption is enabled. 

C:\wlp\bin > securityUtility encode --listCustom

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

9. Encode the password by "securityUtility encode --encoding=custom secret" . Then manually set the encrypted password back in the server.xml. 

C:\wlp-21.0.0.1\wlp\bin > securityUtility encode --encoding=custom secret

{custom}OhT339Bw3wymUcP92Mkz+Q==

server.xml snippet 

    <!-- keyStore id="defaultKeyStore" password="secret" /-->

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

10. Start the server again to make sure the keystore is opened 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

Additional Information

The article "Developing a customPasswordEncryption Provider" has details on how to create the custom encryption files.   
The Liberty's user feature is in general is described  in "Developing a Liberty feature manually". 
The "CustomPasswordInterface" is the same between Liberty and the traditional WebSphere. 
Sample files 
  1. com.ibm.websphere.crypto.sample.customencryption_1.0.jar
  2. customEncryption-1.0.mf
  3. server.xml
  4. customEncryption.jar
Note: Uploaded file may have a little different file name.  Please rename them according to the above names. 

Document Location

Worldwide

[{"Line of Business":{"code":"LOB45","label":"Automation"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Product":{"code":"SSD28V","label":"WebSphere Application Server Liberty Core"},"ARM Category":[{"code":"a8m0z0000001gI0AAI","label":"Liberty->Security"}],"ARM Case Number":"TS004584926","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"All Version(s)"}]

Document Information

Modified date:
31 March 2021

UID

ibm16439321

Page Feedback