Plug point for custom password encryption
Problem(Abstract) A plug point for custom password encryption must be created to encrypt and decrypt all passwords in WebSphere Application Server that are currently encoded or decoded using Base64-encoding. The implementation class of this plug point has the responsibility for managing keys, determining the encryption algorithm to use, and for protecting the master secret.
Cause A custom provider of this plug point must implement an interface designed to encrypt and decrypt passwords. The interface is called by the WebSphere Application Server run time whenever the custom plug point is enabled. The custom algorithm becomes one of the supported algorithms when the plug point is enabled. Resolving the problem How to create, enable or disable a plug point for custom password encryption:
Plug point for custom password encryption
A plug point for custom password encryption can be created to encrypt and decrypt all passwords in WebSphere Application Server that are currently encoded or decoded using Base64-encoding. The implementation class of this plug point has the responsibility for managing keys, determining the encryption algorithm to use, and for protecting the master secret. The WebSphere Application Server run time stores the encrypted passwords in their existing locations preceded with {custom:alias} tags instead of {xor} tags. The “custom” part of the tag indicates that it is a custom algorithm. The “alias” part of the tag is specified by the custom implementation, which helps to indicate how the password was encrypted. The implementation can include the key alias, encryption algorithm, encryption mode, or encryption padding.
A custom provider of this plug point must implement an interface designed to encrypt and decrypt passwords. The interface is called by the WebSphere Application Server run time whenever the custom plug point is enabled. The custom algorithm becomes one of the supported algorithms when the plug point is enabled. Other supported algorithms include {xor} (standard base64 encoding) and {os400} (used on the iSeries platform).
The interface example shown below is com.ibm.wsspi.security.crypto.CustomPasswordEncryption:
package com.ibm.wsspi.security.crypto;
public interface CustomPasswordEncryption
{
/**
* The encrypt operation takes a UTF-8 encoded String in the form of a byte[].
* The byte[] is generated from String.getBytes("UTF-8").
* An encrypted byte[] is returned from the implementation in the EncryptedInfo
* object. Additionally, a logically key alias is returned in EncryptedInfo so
* which is passed back into the decrypt method to determine which key was used
* to encrypt this password. The WebSphere Application Server runtime has no
* knowledge of the algorithm or key used to encrypt the data.
*
* @param byte[]
* @return com.ibm.wsspi.security.crypto.EncryptedInfo
* @throws com.ibm.wsspi.security.crypto.PasswordEncryptException
**/
public EncryptedInfo encrypt (byte[] decrypted_bytes) throws PasswordEncryptException;
/**
* The decrypt operation takes the EncryptedInfo object containing a byte[]
* and the logical key alias and converts it to the decrypted byte[]. The
* WebSphere Application Server runtime will convert the byte[] to a String
* using new String (byte[], "UTF-8");
*
* @param com.ibm.wsspi.security.crypto.EncryptedInfo
* @return byte[]
* @throws com.ibm.wsspi.security.crypto.PasswordDecryptException
**/
public byte[] decrypt (EncryptedInfo info) throws PasswordDecryptException;
/**
* This is reserved for future use and is currently not called by the
* WebSphere Application Server runtime.
*
* @param java.util.HashMap
**/
public void initialize (java.util.HashMap initialization_data);
}
The com.ibm.wsspi.security.crypto.EncryptedInfo class contains the encrypted bytes along with the user-defined alias associated with the encrypted bytes. This information is passed back into the encryption method to help to determine how the password was originally encrypted.
package com.ibm.wsspi.security.crypto;
public class EncryptedInfo
{
private byte[] bytes;
private String alias;
/**
* This constructor takes the encrypted bytes and a keyAlias as parameters.
* This is used to pass to or from the WebSphere Application Server runtime to
* enable the runtime to associate the bytes with a specific key used to encrypt
* the bytes.
*/
public EncryptedInfo (byte[] encryptedBytes, String keyAlias)
{
bytes = encryptedBytes;
alias = keyAlias;
}
/**
* This returns the encrypted bytes.
*
* @return byte[]
*/
public byte[] getEncryptedBytes()
{
return bytes;
}
/**
* This returns the key alias. The key alias is a logical string associated
* with the encrypted password in the model. The format is
* {custom:keyAlias}encrypted_password. Typically, just the key alias is placed
* here, but algorithm information can also be returned.
*
* @return String
*/
public String getKeyAlias()
{
return alias;
}
}
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.
To enable custom password encryption, two properties must first be configured:
property com.ibm.wsspi.security.crypto.customPasswordEncryptionClass
Defines the custom class that implements the password encryption interface (com.ibm.wsspi.security.crypto.CustomPasswordEncryption).
com.ibm.wsspi.security.crypto.customPasswordEncryptionEnabled
Defines when the custom class is used for default password processing. When passwordEncryptionEnabled is not specified or set to false, and the passwordEncryptionClass is specified, the decryption method is called whenever a {custom:alias} tag still exists in the configuration repository.
If the custom implementation class defaults to com.ibm.wsspi.security.crypto.CustomPasswordEncryptionImpl, and this class is present in the classpath, 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 the custom implementation requires. To disable encryption, but still use this class for decryption, specify the class com.ibm.wsspi.security.crypto.customPasswordEncryptionEnabled=false.
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 ${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.
For client side property files such as sas.client.props, soap.client.props, use the PropFilePasswordEncoder.bat (Windows) or PropFilePasswordEncoder.sh (UNIX) 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.
Additional information
Whenever a custom encryption class encryption operation is called, and it throws a runtime exception or a defined PasswordEncryptException, the WebSphere Application Server run time uses the (xor} algorithm to encode the password. This prevents the password from being stored in plain text. Once 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 WebSphere Application Server encoding function. Therefore, once 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, it causes a login failure since 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 causes that password to be unusable, and the password must be changed in the configuration. All encryption keys must be made available for decryption until there are no passwords 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.
Enabling custom password encryption
Complete the following steps to enable custom password encryption:
1. Add the following system properties for every server and client process. For server processes, update the server.xml for each process. Add these properties as a genericJvmArgument preceded by a -D prefix.
com.ibm.wsspi.security.crypto.customPasswordEncryptionClass=com.
acme.myPasswordEncryptionClass
com.ibm.wsspi.security.crypto.customPasswordEncryptionEnabled=true
Note: 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 above when the custom implementation has this package and class name. To disable encryption for this class, you must specify com.ibm.wsspi.security.crypto.customPasswordEncryptionEnabled=false as a system property.
2. Add the JAR file containing the implementation class to the ${WAS_INSTALL_ROOT}/classes directory so that it can be loaded by the WebSphere Application Server runtime.
3. Restart all server processes.
4. Edit each configuration document that contains 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. Tags {custom:alias} appear in the configuration documents. The passwords, even though they are encrypted, are still Base64-encoded. They appear similar to encoded passwords except for the tags difference.
5. Any passwords that are in client-side property files must be encrypted using the PropsFilePasswordEncoder.bat (Windows) or PropsFilePasswordEncoder.sh (UNIX) utility. This utility requires that the properties listed above are defined as system properties in the script to encrypt new passwords instead of encoding them.
6. To decrypt passwords from client JVMs, the properties listed above must be added as system properties for each client utility.
7. For Network Deployment (ND) environments, the order in which enablement occurs is important. Ensure that all nodes have the custom encryption classes in their classpaths prior to enabling this function. When adding a new node to a cell that contains password encryption, the new node must contain the custom encryption classes prior to using addNode. Consider the following ND enablement scenarios:
a. StandAloneProfile is encrypting passwords with a different key prior to federation to a deployment manager cell. For this scenario, you must uninstall custom password encryption to ensure that the configuration has {xor} tags preceding the passwords prior to running addNode. The same implementation of the plug point must be in the /classes directory prior to running addNode, and the proper configuration properties are set so that the new node can recognize the encrypted password format of the security.xml after federation has completed.
b. StandAloneProfile does not have password encryption configured prior to federation to a deployment manager cell. The same implementation of the plug point must be in the /classes directory prior to running addNode, and the proper configuration properties are set so that the new node can recognize the encrypted password format of the security.xml after federation has completed.
c. 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 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. Ensure that the passwords are encrypted by looking at security.xml to see if the passwords are preceded by {custom:alias} tags.
d. Run syncNode on each node, and start them up one at a time. If any nodes fail to start, make sure that they have custom password encryption enabled properly in each security.xml and the implementation class is in the /classes directory appropriate for the platform.
Disabling custom password encryption
Complete the following steps to disable custom password encryption:
1. Change the com.ibm.wsspi.security.crypto.customPasswordEncryptionEnabled property to be false in security.xml, but leave the com.ibm.wsspi.security.crypto.customPasswordEncryptionClass property configured. Any passwords in the model which still have the tag {custom:alias} are decrypted by using the customer password encryption class.
2. If an encryption key is lost, any passwords encrypted with that key can not be retrieved. To recover a password, retype the password in the password field in plaintext and save the document. The new password must be written out using encoding with the {xor} tag. This can be performed by using scripting or from the administrative console. com.ibm.wsspi.security.crypto.customPasswordEncryptionClass=com.
acme.myPasswordEncryptionClass
com.ibm.wsspi.security.crypto.customPasswordEncryptionEnabled=false
3. Restart all processes to make the changes effective.
4. Edit each configuration document that contains an encrypted password and save the configuration. All password fields are then run through the WSEncoderDecoder utility, which calls the plug point due to the presence of the {custom:alias} tag. The {xor} tags reappear in the configuration documents after they are saved.
5. Any passwords that are in client-side property files must be decrypted and then encoded using the PropsFilePasswordEncoder.bat (Windows) and PropsFilePasswordEncoder.sh (UNIX) utility. If the encryption class is specified, but custom encryption is disabled, running this utility converts the encryption to encoding and causes the {xor} tags to reappear.
6. Disable custom password encryption from the client Java virtual machines (JVMs) by adding the system properties listed above to all client scripts. This enables the code to decrypt passwords, but it is not used to encrypt them again. The {xor} algorithm becomes the default for encoding. Leave the custom password encryption class defined for a period of time in the event that any encrypted passwords still exist in the configuration.
ref:http://www-01.ibm.com/support/docview.wss?rs=180&uid=swg21210244
