WebSphere Application Server Network Deployment, Version 6.0.x     Operating Systems: AIX, HP-UX, Linux, Solaris, Windows

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 is 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 that is 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} which is used on the iSeries platform.

The following example illustrates the com.ibm.wsspi.security.crypto.CustomPasswordEncryption interface:

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 logical key alias is returned in the EncryptedInfo
* objectwhich is passed back into the decrypt method to determine which key was
* used to encrypt this password. The WebSphere Application Server run time has
* no knowledge of the algorithm or the 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 run time converts 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;

/**
* The following is reserved for future use and is currently not
* called by the WebSphere Application Server run time.
*
* @param java.util.HashMap
**/
public void initialize (java.util.HashMap initialization_data);
}

The com.ibm.wsspi.security.crypto.EncryptedInfo class contains the encrypted bytes with the user-defined alias that is associated with the encrypted bytes. This information is passed back into the encryption method to help 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 constructor is used to pass to or from the WebSphere Application Server
* runtime to enable the runtime to associate the bytes with a specific key that
* is used to encrypt the bytes.
*/

public EncryptedInfo (byte[] encryptedBytes, String keyAlias)
{
bytes = encryptedBytes;
alias = keyAlias;
}

/**
* This command returns the encrypted bytes.
*
* @return byte[]
*/
public byte[] getEncryptedBytes()
{
return bytes;
}

/**
* This command returns the key alias. The key alias is a logical string that is
* 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, you must 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.

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 class: com.ibm.wsspi.security.crypto.customPasswordEncryptionEnabled=false.

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.

For client side property files such as sas.client.props and soap.client.props, use the PropFilePasswordEncoder.bat(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 that are 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 creates a run-time exception or a defined PasswordEncryptException exception, the WebSphere Application Server run time 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 WebSphere Application Server 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 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
Enabling custom password encryption
Disabling custom password encryption

Concept topic    

Terms of Use | Feedback

Last updated: Dec 11, 2005 4:07:15 PM CST
http://publib.boulder.ibm.com/infocenter/wasinfo/v6r0/index.jsp?topic=/com.ibm.websphere.nd.doc/info/ae/ae/csec_plugpoint_custpass_encrypt.html

© Copyright IBM Corporation 2005. All Rights Reserved.
This information center is powered by Eclipse technology. (http://www.eclipse.org)