Enable custom password encryption

We need to protect passwords contained in the WebSphere Application Server configuration. After creating the server profile, we can add protection by creating a custom class for encrypting the passwords.

Create our custom class for encrypting passwords. See Plug point for custom password encryption.

Enable custom password encryption. For a list of files in an application server profile that contain passwords that should be encrypted and their navigation paths, see Encoding passwords in files.

Tasks

1. Add the following system properties for every server and client process. For server processes, update the server.xml file for each process. Add these properties as a genericJvmArgument argument preceded by a -D prefix.

   com.ibm.wsspi.security.crypto.customPasswordEncryptionClass=
          com.acme.myPasswordEncryptionClass
   com.ibm.wsspi.security.crypto.customPasswordEncryptionEnabled=true
   

   Important: Regarding the wsadmin client, if we use wsadmin in connected mode, this property must be set in the deployment manager or server connected using AdminTask.setJVMSystemProperties command or through the console. If we use wsadmin in local mode (conntype=NONE), we can set the property with a javaoption command option, as shown here:

   wsadmin -conntype none -lang jython -javaoption
   -Dcom.ibm.wsspi.security.crypto.customPasswordEncryptionClass=<encryptionClassToUse>
   

   Tip: If the custom encryption class name is com.ibm.wsspi.security.crypto.CustomPasswordEncryptionImpl, it is automatically enabled when this class is present in the classpath. Do not define the system properties listed previously when the custom implementation has this package and class name. To disable encryption for this class, specify com.ibm.wsspi.security.crypto.customPasswordEncryptionEnabled=false as a system property.

2. Choose one of the following methods to configure the WAS runtime to load the custom encryption implementation class:

   • Place the custom encryption class in a Java archive (JAR) file that resides in the ${WAS_INSTALL_ROOT}/classes directory, which we have created.

     WAS does not create the ${WAS_INSTALL_ROOT}/classes directory. For more information on the classes directory, see the topic, "Creating a classes subdirectory in your profile for custom classes".

   • Place the custom encryption class in a JAR file that resides in the ${WAS_HOME}/lib/ext directory.

3. Restart all server processes.

4. Edit each configuration document containing a password and save the configuration. All password fields are then run through the WSEncoderDecoder utility, which calls the plug point when it is enabled. The {custom:alias} tags are displayed in the configuration documents. The passwords, even though they are encrypted, are still Base64-encoded. They seem similar to encoded passwords, except for the tags different.
5. Encrypt any passwords in client-side property files using the PropsFilePasswordEncoder (.bat or .sh) utility. This utility requires that the properties listed previously are defined as system properties in the script to encrypt new passwords instead of encoding them. You will need to edit the script to add the properties to the java command line. For instance:

   %JAVA_EXE% -Dcom.ibm.wsspi.security.crypto.customPasswordEncryptionEnabled=true 
   -Dcom.ibm.wsspi.security.crypto.customPasswordEncryptionClass=mysample.MySampleEncryption 
   -Dcmd.properties.file=%TMPJAVAPROPFILE% 
   "-Dwas.install.root=%WAS_HOME%" com.ibm.ws.bootstrap.WSLauncher com.ibm.ws.security.util.PropFilePasswordEncoder %*
   

   For the list of files to be run through the PropsFilePasswordEncoder, refer to table two in Encoding passwords in files.

6. To decrypt passwords from client Java virtual machines (JVMs), add the properties listed previously as system properties for each client utility.
7. Ensure that all nodes have the custom encryption classes in their class paths before enabling this function. The order in which enablement occurs is important. When adding a new node to a cell containing password encryption, the new node must contain the custom encryption classes prior to using the addNode command. Consider the following WAS ND enablement scenarios:

   1. The StandAloneProfile profile is encrypting passwords with a different key before federation to a deployment manager cell. For this scenario, uninstall custom password encryption to ensure that the configuration has {xor} tags preceding the passwords before running the addNode command. The same implementation of the plug point must be in the /classes directory before running the addNode command, and the proper configuration properties are set so that the new node can recognize the encrypted password format of the security.xml file after federation completes.

   2. The StandAloneProfile profile does not have password encryption configured before federation to a deployment manager cell. The same implementation of the plug point must be in the /classes directory before running the addNode command, and the proper configuration properties are set so that the new node can recognize the encrypted password format of the security.xml file after federation completes.

   3. If enabling custom password encryption in a cell with multiple nodes present, update the correct configuration properties and have the custom password encryption implementation class that is located on all nodes. Stop all processes in the cell, and then start the deployment manager. Use the administrative console to edit the security configuration and then save it. Verify that the passwords are encrypted by looking at the security.xml file to see if the passwords are preceded by {custom:alias} tags.

   4. Run the syncNode command on each node, and start each one individually. If any nodes fail to start, make sure that they have custom password encryption enabled properly in each security.xml file and that the implementation class is in the appropriate /classes directory for the platform.

Custom password encryption is enabled.

What to do next

If custom password encryption fails or is no longer required, see Disable custom password encryption.

Subtopics

• Disable custom password encryption
  If custom password encryption fails or is no longer required, perform this task to disable custom password encryption.

Related:

Plug point for custom password encryption

Secure passwords in files

(iSeries) Create a classes subdirectory in your profile for custom classes

(iSeries) Encoding passwords in files