x

1. Modify the WFENCR context parameter in the Web application (for example, in the ibi\WebFOCUS77\config\webconfig.xml file or using your Application Server Administration interface). The value of this parameter should be the name of one of the following encryption classes (including the Java package):

   Algorithm	External Key	Class Name
   AES128	No	ibi.webfoc.wfsecurity.encryption.wireaes. WFWireAES128
   AES192	No	ibi.webfoc.wfsecurity.encryption.wireaes. WFWireAES192
   AES256	No	ibi.webfoc.wfsecurity.encryption.wireaes. WFWireAES256
   DES	No	ibi.webfoc.wfsecurity.encryption.wiredes. WFWireDES
   Triple DES	No	ibi.webfoc.wfsecurity.encryption.wiretripledes. WFWireTripleDES

2. Reload the WebFOCUS Web application for the new setting to take effect.

x

1. Modify the WFENCR context parameter in the Web application (for example, in the \ibi\WebFOCUS77\config\webconfig.xml file or using your Application Server Administration interface). The value of this parameter should be the name of one of the following encryption classes (including the Java package):

   Algorithm	External Key	Class Name
   AES128	Yes	ibi.webfoc.wfsecurity.encryption.wireaes. WFWireAES128KeyFile
   AES192	Yes	ibi.webfoc.wfsecurity.encryption.wireaes. WFWireAES192KeyFile
   AES256	Yes	ibi.webfoc.wfsecurity.encryption.wireaes. WFWireAES256KeyFile
   DES	Yes	ibi.webfoc.wfsecurity.encryption.wiredes. WFWireDESKeyFile
   Triple DES	Yes	ibi.webfoc.wfsecurity.encryption.wiretripledes. WFWireTripleDESKeyFile

2. To use an encryption key stored in an external file, you must also modify the context parameter WFENCR_KEY_INFO within webconfig.xml. The value of this parameter is the fully qualified path of the plain text file containing the external key data (for example: c:\ibi\keyfile.dat).
3. Create the key file on disk and input 8, 16, 24, or 32 hexadecimal bytes, depending on the encryption algorithm. For more information on hexadecimal keys, see Key File Format.

   Save the key file as a plain text file.

4. Reload the WebFOCUS Web application for the new settings to take effect.

x

The resulting code in your deployment descriptor should look like this:

<context-param>
<param-name>WFENCR</param-name>
<param-value> 
ibi.webfoc.wfsecurity.encryption.wiretripledes.WFWireTripleDESKeyFile 
</param-value>
</context-param>
<context-param>
<param-name>WFENCR_KEY_INFO</param-name>
<param-value>c:\ibi\keyfile.dat</param-value>
</context-param>

x

The encryption key information is stored in a plain text file and is represented by a sequence of bytes in hexadecimal notation. A hexadecimal byte is represented by two digits. Each digit is either a number (0-9) or a letter (A-F).

The following table specifies the number of hexadecimal bytes required for encryption keys for the AES, DES, and Triple DES algorithms.

Number of hexadecimal bytes	Sample string	Algorithm
8	2011ADFB98765421	DES
16	5468658A6C617A795468658A6C617A79	AES128
24	5468658A6C617A7920646F67206A756D7073206F76 65723F	AES192, Triple DES
32	5468658A6C617A7920646F67206A756D7073206F76 65723F5468658A6C617A79	AES256

It may seem that more data is specified in the key file than is required (8 bits per byte times 24 bytes is 192 bits, which is greater than the 168 bits usually required for Triple DES). The reason is that the Triple DES algorithm only uses 168 bits (3 keys of 56 bits) and the remaining 3 bytes (24 bits) are used for parity and not used for encryption.

x

WFENCR is used to encrypt both transient data (WebFOCUS cookies and Managed Reporting sign-on tickets) and persisted data (Managed Reporting passwords). Changing an encryption algorithm or an encryption key renders persisted data unreadable. If you are using the built-in Managed Reporting Repository for authentication or are storing Dashboard credentials for the Public View or for WebFOCUS Reporting Server authentication, you must reset those passwords after adding or changing a WFENCR or WFENCR_KEY_INFO setting.

To reset passwords in the built-in Managed Reporting user directory (user.htm) after changing WebFOCUS encryption settings, do the following:

1. Make a backup copy of basedir/user.htm.
2. Edit user.htm and locate the anchor tag for a Managed Reporting Administrator account. For example, the line beginning with: <A HREF='admin.htm' NAME='admin'.
3. On this line, remove the PASSWORD=encrypted_string keyword/value from the anchor line.
4. Save the file and reload your WebFOCUS Web application.
5. Now log in as the administrator whose password you just removed.
6. Use the Managed Reporting User Administration tool to assign a password to the currently logged in administrator account. This password will now be written to user.htm in encrypted form using the current WebFOCUS encryption settings.
7. Next, reset the password of each user to an initial value.
8. Instruct your users to change their passwords as appropriate, from the Managed Reporting or Dashboard logon page.

This process is tedious so consider your implementation choices carefully. For example, configure WebFOCUS with a strong encryption provider from the start so you do not have to change it later. Consider also using the Managed Reporting Realm Driver to authenticate users to an external directory such as Active Directory or LDAP. In this case, passwords are not maintained in the user.htm file.

Note: In a future release, Information Builders plans to create separate settings for encrypting transient and persisted data. This will allow for the possibility of a dynamically generated internal key, external key store, and key rotation.

x

The DES and Triple DES algorithms were developed with Sun Java Cryptography Extension (JCE) framework and currently implement only the Sun JCE provider class. The cipher specification for DES is DES/CBC/PKCS5Padding and for Triple DES is DESede/CBC/PKCS5Padding. Review the following scenarios to verify support for your Application server:

• If you are running WebFOCUS inside a Java Application server (or servlet engine) that runs on Sun J2SDK 1.4.1 or higher, you do not need to take any action. The Sun JCE provider is included.
• If you are running J2SDK 1.4.1 or higher of another vendor, check their documentation to see if the Sun JCE provider is available in that implementation. For example, WebSphere 5.1 for HP-UX ships with a version of HP J2SDK 1.4.1 that has both the Sun and IBM JCE providers. However, WebSphere 5.1 for AIX ships with an IBM J2SDK 1.4.1 that has only the IBM JCE provider and is therefore not currently supported by the optional encryption providers supplied by Information Builders.
• If your Java Application server is running on J2SDK 1.3.x (from any vendor), you must download and configure Sun JCE 1.2.2. For example, WebSphere 5.0 on AIX ships with IBM J2SDK 1.3.1, which is only supported when you download and configure the Sun JCE.

  You can obtain the Sun JCE 1.2.2 software and installation documentation by accessing the JCE Downloads section on Sun Java Technology Web site.

To run AES192 or AES256 under the Sun JVM, you must install the unlimited strength JCE policy files, or else the key length will not be supported. These may be downloaded from the JCE Downloads section on the Sun Java Technology Web site.

x

• To build the alternate encryption provider, you must add the \ibi\WebFOCUS77\webapps\webfocus\WEB-INF\lib\webfoc.jar file to the build classpath for your WebFOCUS Servlet Alternate Encryption project.
• To enable the alternate encryption provider, add WFENCR as a context parameter to the WebFOCUS Web application so that it will be available for WebFOCUS, Managed Reporting, and Dashboard. The change is made to the deployment descriptor file, \ibi\WebFOCUS77\webapps\webfocus\WEB-INF\web.xml:

  <web-app>  ...  ...  <context-param>  <param-name>WFENCR</param-name>  
  <param-value>ENCRYPTION EXIT CLASS NAME GOES HERE</param-value> </context-param>

Top of page

Example: Using Your Alternate Encryption Provider

The following sample code overrides WebFOCUS built-in encryption and encodes the WebFOCUS cookie. This sample does not provide any encryption algorithm.

package exits.wf;
import ibi.webfoc.wfutil.WFEncryptionInterface;
 
public class WfEncryptionExit implements WFEncryptionInterface
{
/**
 * Constructor for WfEncryptionExit.
 */
public WfEncryptionExit()
{
super();
}
 
/**
 * Apply custom encryption algorithm.
 * @param cookie
 * @return Encrypted cookie string
 */
 
public String encrypt(String cookie)
{String rCookie;
rCookie= java.net.URLEncoder.encode(cookie);
return rCookie;
}
/**
 * Apply custom decryption algorithm,
 * @param cookie
 * @return Decrypted cookie string
 */

public String decrypt(String cookie)
{
String rCookie;
rCookie= java.net.URLDecoder.decode(cookie);
return rCookie;
}
 
/**
 * Determines if a EBCIDIC to ASCII translation is performed.
 * @param cookie
 * @param convert
 * @return String
 */
public String decrypt(String cookie, boolean convert)
{
String rCookie;
rCookie= java.net.URLDecoder.decode(cookie);
return rCookie;
}
}