Installing Integration Gateway-Based Digital Certificates

This topic provides an overview of integration gateway-based digital certificates and discusses how to:

  • Generate private and public key pairs.

  • Generate CSRs.

  • Obtain signed root certificates.

  • Import signed root certificates.

  • Specify the keystore location for WS-Security in the wss.properties file..

  • Encrypt keystore passwords for WS-Security.

Use the procedures discussed in this section for generating and installing digital certificates for use with the following security protocols:

  • Integration gateway encryption.

  • Client authentication.

  • WS-Security.

Elements of Integration Gateway-Based Digital Certificates

To set up integration gateway-based digital certificates, use the PSKeyManager utility to install digital certificates in the integration gateway keystore.

The integration gateway requires the following elements:

  • The gateway's private key.

  • A certificate containing the gateway's public key, digitally signed by a trusted CA.

  • A root certificate from the CA that signed the gateway's public key.

Using the PSKeyManager utility, you generate a private-public key pair, which is automatically inserted in the gateway keystore.

You generate a PEM-formatted CSR that contains the gateway's public key. You submit the CSR to the selected CA. The CA creates, digitally signs, and returns your gateway's public key certificate to you. This certificate also contains a signed copy of the CA's root certificate. These certificates may be in standard DER-encoded binary format, or they can be converted to PEM format if necessary.

You then install both signed certificates in the gateway keystore. In addition, you register them and the private key with the web server so that it can recognize and use them.

Keystore Location for Integration Gateway-Based Digital Certificates

The keystore location for integration gateway-based certificates is:

<PIA_HOME>\webserv\peoplesoft\piaconfig\keystore

Integration gateway, client authentication, and WS-Security certificates are stored in this location.

In addition, SSL/TLS digital certificates are also stored in this location.

wss.properties File

The wss.properties file stores keystore location information and password information for WS-Security digital certificates.

When installing digital certificates for WS-Security, you must specify the location of the keystore in this file.

You can also store an encrypted copy of the keystore password in this file.

The location of the file is: 

<PIA_HOME>\webserv\<DOMAIN>\peoplesoft\applications\PSIGW.war\WEB-INF\classes

Use the information provided in the topic “Installing Web Server-Based Digital Certificates” to generate and install integration gateway-based certificates.

Note that for integration gateway encryption if the integration gateway is installed on a web server that has SSL/TLS implemented, the integration gateway and web server can share the same digital certificates. As a result, you do not need to install separate integration gateway certificates. However, if the integration gateway is installed on a web server where SSL/TLS is not implemented, you must generate and install digital certificates on that web server.

After generating and installing integration gateway-based certificates the keystore path and the keystore password must be defined in the integration gateway properties file.

Warning! Integrations will fail if the keystore path and encrypted keystore password are not defined in the integration gateway properties file, integrationGateway.properties.

If you are implementing WS-Security you must specify the keystore location in the wss.properties file. The next section describes how to specify the keystore location in the wss.properties file.

After you install digital certificates for WS-Security, you must specify the keystore location in the wss.properties file.

To specify the keystore location for WS-Security:

  • Open the wss.properties file.

    The location of the file is <PIA_HOME>\webserv\<DOMAIN>\peoplesoft\applications\PSIGW.war\WEB-INF\classes.

  • Set the following property equal to the location and file name of the keystore where you installed the integration gateway-based digital certificates.

    org.apache.ws.security.crypto.merlin.file

    For example:

    org.apache.ws.security.crypto.merlin.file=c:/<PIA_HOME>/<webserv>/
<DOMAIN>/keystore/pskey

    Note: When entering the path to the keystore, you must use either double backslashes (“\\”) or forward slashes (“/”) as path separators. Do not use backslashes (“\”) as path separators for directory names in the wss.properties file. Backslashes are misinterpreted as escape characters by the Java processes that access the file.

  • Save the changes.

This section discusses how to encrypt the password for the keystore that contains digital certificates for WS-Security.

Understanding Encrypting Keystore Passwords for WS-Security

When working with the WS-Security digital certificates, PeopleSoft recommends that you encrypt the keystore password in the wss.properties file using the PSCipher utility.

Encrypting the WS-Security Keystore Password

To encrypt the WS-Security keystore password, making sure to write down the encrypted output.

  1. Encrypt the WS-Security keystore password using the PSCipher utility.

    See Encrypting Passwords Using the PSCipher Java Utility.

  2. Access the wss.properties file.

    The location is <PIA_HOME>\webserv\<DOMAIN>\peoplesoft\applications\PSIGW.war\WEB-INF\classes.

  3. Set the following property equal to the encrypted password you created using the PSCipher utility:

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

    The following example shows an encrypted password entered for this property:

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

  4. Save the changes.