Encrypting Text With PSCipher

This chapter contains an overview and discusses how to:

• Use the PSCipher utility.

• Generate a unique encryption key.

• Update the encryption key on Oracle Application Server.

• Update the encryption key on BEA WebLogic.

• Update the encryption key on IBM WebSphere.

• Secure the external key file.

Understanding the Triple DES Encryption Implementation

The PSCipher utility provides Triple DES encryption (also 3DES) for increased data security. When you install Enterprise PeopleTools on your application servers and web servers, a default, Triple DES encryption key is provided. If your site decides to use the default key, no further configuration of your system is required to implement Triple DES encryption. However, if your site requires or desires a unique encryption key, you can generate a unique key using the PSCipher command line utility as described in this chapter.

The version of the default encryption key is version 1.1, or {V1.1}. If you generate a unique key, the current version used by the system would be {V1.2}. Each time you generate a new key, the system increments the current version number.

Using the PSCipher Utility

The PSCipher feature encrypts and decrypts text used in your PeopleSoft system. System administrators interact with PSCipher through a Java, command line utility located on the web server, which enables you to encrypt text, such as user IDs and passwords, stored in configuration files. PSCipher also involves a runtime element, running on the application server, that decrypts the encrypted text. The runtime element requires no user interaction.

In previous releases, PSCipher was used, for example, to secure the node IDs and node passwords used in conjunction with PeopleSoft Integration Broker configurations. You can now use the PSCipher command line utility to encrypt (with Triple DES) a variety of text values stored in various configuration files throughout your system. In addition, PSCipher also provides:

• Key generation: You can generate unique encryption keys if you do not want to use the default key.

• Version maintenance: The key file maintains a version history of all previous versions of the key file, which enables text encrypted with a previous version to be decrypted.

Note. PSCipher decrypts text encrypted in previous releases. For example, PSCipher in Enterprise PeopleTools 8.49 supports text encrypted with PSCipher in Enterprise PeopleTools 8.46.

To encrypt text, you submit text values in the form of arguments that PSCipher encrypts and then displays in its encrypted form. Suppose you needed to encrypt a user ID of "HRDMO" and a password of "DMOPSWD". You would submit these values to PSCipher as follows:

...\pscipher HRDMO

and

...\pscipher DMOPSWD

PSCipher returns the encrypted form of these submitted text values, which you can then copy to a configuration file to assign to a configuration parameter.

For example, on Oracle Application Server you will need to encrypt the values assigned to the WebUserID and WebPassword properties stored in the configuration.properties file. To do that you would follow these steps.

1. Run <OAS_HOME>\j2ee\<COMPONENT>\applications\<APPLICATION>\PSCipher <WebUserID> to get the encrypted text for WebUserId value.

   For example,

   c:\>cd OraHome_1\j2ee\PeopleSoft\applications\PeopleSoft
   c:\OraHome_1\j2ee\PeopleSoft\applications\PeopleSoft>PSCipher.bat PTWEBSERVER
   Your environment has been set.
   Encrypted text: {V1.1}jId3vgo6Rejke7gsjI4iss==
   

   Note. You need to change to the current directory containing the PSCipher utility before submitting text (as shown in the previous example).

   Note. The value between the brackets indicates the version number of the key file used to encrypt the text. In this case, the version is 1.1.

2. Copy the generated encrypted text to the WebUserID property in the configuration.properties file, overwriting any previous value assigned to the property.

   For example,

   WebUserId={V1.1}jId3vgo6Rejke7gsjI4iss==

3. Run <OAS_HOME>\j2ee\<COMPONENT>\applications\<APPLICATION>\PSCipher <WebPassword> to get the encrypted text for WebPassword value.

   For example,

   c:\>cd OraHome_1\j2ee\PeopleSoft\applications\PeopleSoft
   c:\OraHome_1\j2ee\PeopleSoft\applications\PeopleSoft>PSCipher.bat PTWSpassword
   Your environment has been set.
   Encrypted text: {V1.1}n2IenrGein6ib8/kNvkDdl==
   

4. Copy the generated encrypted text to the WebPassword property in the configuration.properties file, overwriting any previous value assigned to the property.

   For example,

   WebPassword={V1.1}n2IenrGein6ib8/kNvkDdl==

Note. This same procedure will need to be applied whenever you intend to encrypt text using PSCipher. Note that in the following sections of this document it is assumed that you understand how to encrypt the text value.

Generating a Unique Encryption Key

You use the PSCipher Java utility's buildkey command to build new Triple DES encryption keys. The buildkey command adds a new Triple DES encryption key stored in the psvault file (the key file). If you generate new versions of the key file, the system appends the new version of the key to the end of the key file.

To invoke the command on a Windows server, change to the directory where PSCipher resides and enter:

...\pscipher -buildkey

To invoke the command on UNIX, change to the directory where PSCipher resides and enter:

.../PSCipher.sh -buildkey

Select one web server in your system to generate the new version of the key file. The pscipher.bat and PSCipher.sh utilities only run in the Java environment of the web server. After you have created the new key file, you then copy the new version of psvault from the initial server to the appropriate directories on all the appropriate servers in your system. The psvault file is stored in different directories depending on your web server vender (as described in the following sections). On the application server the psvault file resides in <PS_HOME>\secvault.

Note. If you are not using the default encryption key and you have generated a unique encryption key, note that each time you add a new server to your system, you will need to copy the key file to the appropriate location on that server. For example, if you are using the default key version ({V1.1}), any server you add to the system and install PeopleTools 8.49 on will also have the default key version ({V1.1}). As such, no further steps are required. However, if you have generated a new key, giving the version number a value of {V1.2} or greater, then you need to make sure to copy that key file to the added server(s). Also, each time you update the key, you need to ensure that the new version of the key file is copied to the additional servers in your system.

Warning! When you upgrade to new PeopleTools releases, as in PeopleTools 8.47 to PeopleTools 8.49, you will need to backup any modifications you have made to the key file using PSCipher in the previous release and reapply that same key file to the appropriate servers onto which you have installed the new PeopleTools release.

Updating the Encryption Key on Oracle Application Server

On the Oracle Application Server PSCipher.bat and the psvault key file are stored in the following location:

<OAS_HOME>\j2ee\<COMPONENT>\applications\<APPLICATION>.

Generating the Encryption Key on Oracle Application Server

To update the encryption key on Oracle Application Server:

1. Run <OAS_HOME>\j2ee\<COMPONENT>\applications\<APPLICATION>\PSCipher –buildkey to create a new key in the key file.

   For example,

   C:\>cd OraHome_1\j2ee\PeopleSoft\applications\PeopleSoft
   c:\OraHome_1\j2ee\PeopleSoft\applications\PeopleSoft>PSCipher.bat -buildkey
   Your environment has been set.
   A new key of version {V1.2} is generated successfully
   

2. Copy <OAS_HOME>\j2ee\<COMPONENT>\applications\<APPLICATION>\psvault to the equivalent location on all other web server hosts and to <PS_HOME>\secvault\psvault on all application servers in your system.

3. Modify the encrypted text fields as described in the following sections.

Updating the Web Profile

The configuration.properties file is located in the following directory:

<OAS_HOME>\j2ee\<COMPONENT>\applications\<APPLICATION>\PORTAL\WEB-INF\psftdocs\ps

The following encrypted text values in the configuration.properties file need to updated:

WebUserId={V1.1}et5LM5/C2fQPVWt5cztapg==
WebPassword={V1.1}et5LM5/C2fQPVWt5cztapg==

Submit the values for these properties to PSCipher, and copy the generated encrypted text to the WebUserID and WebPassword properties in the configuration.properties file, overwriting any previous value assigned to the property.

Updating the Integration Gateway

On the Integration Gateway, you need to modify the following files:

• gatewayUserProfile.xml

• integrationGateway.properties

The gatewayUserProfile.xml file is located in the following directory:

<OAS_HOME>\j2ee\<COMPONENT>\applications\<APPLICATION>\PSIGW\WEB-INF

In the gatewayUserProfile.xml file, update the following text value:

<password>{V1.1}GD9klUFw8760HVaqeT4pkg==</password>

Note. There can be more than one password field in this file. There could be different <password></password> entries for different users. You should use PSCipher to encrypt all <password></password> entries.

Submit the values for these properties to PSCipher, and copy the generated encrypted text to the <password></password> entry in the gatewayUserProfile.xml file, overwriting any previous value.

The integrationGateway.properties file is located in the following directory:

<OAS_HOME>\j2ee\<COMPONENT>\applications\<APPLICATION>\PSIGW\WEB-INF

Update the following text values stored in the integrationGateway.properties file.

Note. If you are not currently assigning a value to one of the following properties, you don't need to supply a value.

• ig.isc.password=

• ig.isc.$NODENAME.password=

• #ig.certificatePasswd=

• secureFileKeystorePasswd=

• #ig.jms.JMSTargetConnector.JMSProvider.Password=

• # ig.jms.Queue1.Password=

• # ig.jms.Topic1.Password=

• #ig.jms.Topic1.NodePassword=

Submit the values for these properties to PSCipher, and copy the generated encrypted text to the corresponding entries in the integrationGateway.properties file, overwriting any previous value.

Updating WSRP/WSS

You need to update the wss.properties file used for Web Services Remote Portal (WSRP) and Web Services Security (WSS).

The wss.properties file needs to be updated in the following locations:

• <OAS_HOME>\j2ee\<COMMPONENT>\applications\<APPLICATION>\PORTAL\WEB-INF\classes

• <OAS_HOME>\j2ee\<COMPONENT>\applications\<APPLICATION>\pspc\WEB-INF\classes

Update the following text entry in the wss.properties file in both locations:

org.apache.ws.security.crypto.merlin.keystore.password=

Submit each password value to PSCipher, and copy the generated encrypted text to the corresponding entries in the wss.properties file, overwriting any previous value.

Updating the Encryption Key on IBM WebSphere

On IBM WebSphere, PSCipher.bat and psvault key file are stored in the following location:

<PS_HOME>\webserv\<Node_Server>\<APPLICATION>.ear

Generating the Encryption Key on IBM WebSphere

To update the encryption key:

1. Run <PS_HOME>\webserv\<Node_Server>\<APPLICATION>.ear PSCipher –buildkey to create a new key in the key file.

   For example,

   c:\>cd pshome\webserv\DS9Node_DS9Node_server1\peoplesoft.ear 
   c:\pshome\webserv\DS9Node_DS9Node_server1\peoplesoft.ear>PSCipher.bat -buildkey
   Your environment has been set.
   A new key of version {V1.2} is generated successfully
   

2. Copy <PS_HOME>\webserv\<Node_Server>\<APPLICATION>.ear\psvault to the equivalent location on all other web server hosts and to <PS_HOME>\secvault\psvault on all application servers in your system.

3. Modify the encrypted text fields as described in the following sections.

Updating the Web Profile

The configuration.properties file is located in the following directory:

<PS_HOME>\webserv\<Node_Server>\<APPLICATION>.ear\PORTAL\WEB-INF\psftdocs\ps\

The following encrypted text values in the configuration.properties file need to updated:

WebUserId={V1.1}et5LM5/C2fQPVWt5cztapg==
WebPassword={V1.1}et5LM5/C2fQPVWt5cztapg==

Submit the values for these properties to PSCipher, and copy the generated encrypted text to the WebUserID and WebPassword properties in the configuration.properties file, overwriting any previous value assigned to the property.

Updating the Integration Gateway

On the Integration Gateway, you need to modify the following files:

• gatewayUserProfile.xml

• integrationGateway.properties

The gatewayUserProfile.xml file is located in the following directory:

<PS_HOME>\webserv\<Node_Server>\<APPLICATION>.ear\PSIGW\WEB-INF\

In the gatewayUserProfile.xml file, update the following text value:

<password>{V1.1}GD9klUFw8760HVaqeT4pkg==</password>

Note. There can be more than one password field in this file. There could be different <password></password> entries for different users. You should use PSCipher to encrypt all <password></password> entries.

Submit the values for these properties to PSCipher, and copy the generated encrypted text to the <password></password> entry in the gatewayUserProfile.xml file, overwriting any previous value.

The integrationGateway.properties file is located in the following directory:

<PS_HOME>\webserv\<Node_Server>\<APPLICATION>.ear\PSIGW\WEB-INF\

Update the following text values stored in the integrationGateway.properties file.

Note. If you are not currently assigning a value to one of the following properties, you don't need to supply a value.

• ig.isc.password=

• ig.isc.$NODENAME.password=

• #ig.certificatePasswd=

• secureFileKeystorePasswd=

• #ig.jms.JMSTargetConnector.JMSProvider.Password=

• # ig.jms.Queue1.Password=

• # ig.jms.Topic1.Password=

• #ig.jms.Topic1.NodePassword=

Submit the values for these properties to PSCipher, and copy the generated encrypted text to the corresponding entries in the integrationGateway.properties file, overwriting any previous value.

Updating WSRP/WSS

You need to update the wss.properties file used for Web Services Remote Portal (WSRP) and Web Services Security (WSS).

The wss.properties file needs to be updated in the following locations:

• <PS_HOME>\webserv\<Node_Server>\<APPLICATION>.ear\PORTAL\WEB-INF\classes

• <PS_HOME>\webserv\<Node_Server>\<APPLICATION>.ear\pspc\WEB-INF\classes

Update the following text entry in the wss.properties file in both locations:

org.apache.ws.security.crypto.merlin.keystore.password=

Submit each password value to PSCipher, and copy the generated encrypted text to the corresponding entries in the wss.properties file, overwriting any previous value.

Updating the Encryption Key on BEA WebLogic

On BEA WebLogic PSCipher.bat and psvault are stored in the following location:

<PS_HOME>\webserv\<DOMAIN>

Generating the Encryption Key on BEA WebLogic

To update the encryption key:

1. Run <PS_HOME>\webserv\<DOMAIN>\PSCipher –buildkey to create a new key in the key file.

   For example,

   c:\cd PS_HOME\webserv\peoplesoft
   c:\PS_HOME\webserv\peoplesoft>PSCipher.bat -buildkey
   Your environment has been set.
   A new key of version {V1.2} is generated successfully
   

2. Copy <PS_HOME>\webserv\<DOMAIN>\psvault to the equivalent location on all other web server hosts and to <PS_HOME>\secvault\psvault on all application servers in your system.

3. Modify the encrypted text fields as described in the following sections.

Updating the Web Profile

The configuration.properties file is located in the following directory:

<PS_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PORTAL\WEB-INF\psftdocs

The following encrypted text values in the configuration.properties file need to updated:

WebUserId={V1.1}et5LM5/C2fQPVWt5cztapg==
WebPassword={V1.1}et5LM5/C2fQPVWt5cztapg==

Submit the values for these properties to PSCipher, and copy the generated encrypted text to the WebUserID and WebPassword properties in the configuration.properties file, overwriting any previous value assigned to the property.

Updating the Integration Gateway

On the Integration Gateway, you need to modify the following files:

• gatewayUserProfile.xml

• integrationGateway.properties

The gatewayUserProfile.xml file is located in the following directory:

<PS_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PSIGW\WEB-INF\

In the gatewayUserProfile.xml file, update the following text value:

<password>{V1.1}GD9klUFw8760HVaqeT4pkg==</password>

Note. There can be more than one password field in this file. There could be different <password></password> entries for different users. You should use PSCipher to encrypt all <password></password> entries.

Submit the values for these properties to PSCipher, and copy the generated encrypted text to the <password></password> entry in the gatewayUserProfile.xml file, overwriting any previous value.

The integrationGateway.properties file is located in the following directory:

<PS_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PSIGW\WEB-INF

Update the following text values stored in the integrationGateway.properties file.

Note. If you are not currently assigning a value to one of the following properties, you don't need to supply a value.

• ig.isc.password=

• ig.isc.$NODENAME.password=

• #ig.certificatePasswd=

• secureFileKeystorePasswd=

• #ig.jms.JMSTargetConnector.JMSProvider.Password=

• # ig.jms.Queue1.Password=

• # ig.jms.Topic1.Password=

• #ig.jms.Topic1.NodePassword=

Submit the values for these properties to PSCipher, and copy the generated encrypted text to the corresponding entries in the integrationGateway.properties file, overwriting any previous value.

Updating WSRP/WSS

You need to update the wss.properties file used for Web Services Remote Portal (WSRP) and Web Services Security (WSS).

The wss.properties file needs to be updated in the following locations:

• <PS_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PORTAL\WEB-INF\classes\

• <PS_HOME>\webserv\<DOMAIN>\applications\peoplesoft\pspc\WEB-INF\classes\

Update the following text entry in the wss.properties file in both locations:

org.apache.ws.security.crypto.merlin.keystore.password=

Submit each password value to PSCipher, and copy the generated encrypted text to the corresponding entries in the wss.properties file, overwriting any previous value.

Securing the External Key File

The encryption key used by PSCipher is stored in a key file named psvault. This file is critical to your system security. It is very important to protect this file using at least the concepts discussed in this section.

Setting up Operating System File Security

The key file should be secured and protected by your operating system with the appropriate file access permissions on all platforms. The recommended file access permissions are:

• File ‘read’ access for only the administrators that need to run the PSCipher command-line utility to encrypt text.

• File ‘read’ access for the only the administrators that need to start the application servers and web servers.

• File ‘write’ access for only the administrators that need to run PSCipher –buildkey to create a new PSCipher key.

Backing Up the Key File

It will be a time-consuming task to recover your system if you accidentally damage or delete the key file. Therefore, it is important to save a backup of your key file. It is recommended that every time you build a new key that you backup your latest key file to a safe location.

Note. You only need to keep the latest version of your key file for your backup. The latest version contains a version history of previous keys.