Enable a plugpoint for custom password encryption
Two properties govern the protection of passwords. By configuring these two properties, you 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.
Overview
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.
Procedure
- To enable custom password encryption, configure two properties:
- property 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.
- To configure custom password encryption, configure both of these properties in the security.xml file. The custom encryption class (com.acme.myPasswordEncryptionClass) must be placed in a Java archive (JAR) file in the ${WAS_INSTALL_ROOT}/classes directory in all WebSphere Application Server processes. Every configuration document that contains a password (security.xml and any application bindings that contain RunAs passwords), must be saved before all of the passwords become encrypted with the custom encryption class.
- 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.
You can 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.
Related tasks
Implementing custom password encryption
Enabling custom password encryption
Disabling custom password encryption
Developing extensions to the WebSphere security infrastructure