Enable a plugpoint for custom password encryption

Two properties govern the protection of passwords. By configuring these two properties, we can enable a plugpoint for custom password encryption.

To view an example code sample that illustrates the com.ibm.wsspi.security.crypto.CustomPasswordEncryption interface, see Plug point for custom password encryption.

The encryption method is called for password processing whenever the custom class is configured and custom encryption is enabled. The decryption method is called whenever the custom class is configured and the password contains the {custom:alias} tag. The custom:alias tag is stripped prior to decryption.

1. To enable custom password encryption, configure two properties:

   • com.ibm.wsspi.security.crypto.customPasswordEncryptionClass - Defines the custom class that implements the com.ibm.wsspi.security.crypto.CustomPasswordEncryption password encryption interface.

   • com.ibm.wsspi.security.crypto.customPasswordEncryptionEnabled - Defines when the custom class is used for default password processing. When the passwordEncryptionEnabled option is not specified or set to false, and the passwordEncryptionClass class is specified, the decryption method is called whenever a {custom:alias} tag still exists in the configuration repository.

2. (dist)(zos) To configure custom password encryption, configure both of these properties in the server.xml file. How you perform this configuration is dependent on the existing directory structure. Choose one of the following ways to perform this configuration:

   • Place The custom encryption class (com.acme.myPasswordEncryptionClass) in a JAR file that resides in the ${WAS_INSTALL_ROOT}/classes directory. In this case, we have created the ${WAS_INSTALL_ROOT}/classes directory for this purpose.

     WAS does not create the ${WAS_INSTALL_ROOT}/classes directory.

   • Place the custom encryption class (com.acme.myPasswordEncryptionClass) in a JAR file that resides in the ${WAS_HOME}/lib/ext directory or another valid existing directory.

   Every configuration document containing a password (security.xml and any application bindings containing RunAs passwords), must be saved before all of the passwords become encrypted with the custom encryption class.

3. (iseries) To configure custom password encryption, configure both of these properties in security.xml. The custom encryption class (com.acme.myPasswordEncryptionClass) must be placed in a JAR file in the ${APP_SERVER_ROOT}/classes directory in all WebSphere Application Server processes. Every configuration document containing a password (security.xml and any application bindings containing RunAs passwords), must be saved before all of the passwords become encrypted with the custom encryption class . For client side property files such as sas.client.props and soap.client.props, use the PropFilePasswordEncoder.bat or PropFilePasswordEncode.sh script to enable custom processing. This script must have the two properties configured as system properties on the Java command line of the script. The same tools used for encoding and decoding can be used for encryption and decryption when custom password encryption is enabled.

4. If the custom implementation class defaults to the com.ibm.wsspi.security.crypto.CustomPasswordEncryptionImpl interface, and this class is present in the class path, then encryption is enabled by default. This simplifies the enablement process for all nodes. It is not necessary to define any other properties except for those that the custom implementation requires. To disable encryption, but still use this class for decryption, specify the following class.

   • com.ibm.wsspi.security.crypto.customPasswordEncryptionEnabled=false

What to do next

Whenever a custom encryption class encryption operation is called, and it creates a run-time exception or a defined PasswordEncryptException exception, the WAS runtime uses the {xor} algorithm to encode the password. This encoding prevents the storage of the password in plain text. After the problem with the custom class has been resolved, it automatically encrypts the password the next time the configuration document is saved.

When a RunAs role is assigned a user ID and password, it currently is encoded using the WAS encoding function. Therefore, after the custom plug point is configured to encrypt the passwords, it encrypts the passwords for the RunAs bindings as well. If the deployed application is moved to a cell that does not have the same encryption keys, or the custom encryption is not yet enabled, a login failure results because the password is not readable.

One of the responsibilities of the custom password encryption implementation is to manage the encryption keys. This class must decrypt any password that it encrypted. Any failure to decrypt a password renders that password to be unusable, and the password must be changed in the configuration. All encryption keys must be available for decryption there and no passwords are left using those keys. The master secret must be maintained by the custom password encryption class to protect the encryption keys.

Manage the master secret by using a stash file for the keystore, or by using a password locator that enables the custom encryption class to locate the password so that it can be locked down.

Subtopics

• Plug point for custom password encryption
  A plug point for custom password encryption can be created to encrypt and decrypt all passwords in WAS that are currently encoded or decoded using Base64-encoding.

Related tasks

Develop extensions to the WebSphere security infrastructure

Implement custom password encryption

Enable custom password encryption

Disable custom password encryption