Introduction

The USxS SOAP SIF agents use a dedicated keystore to communicate using SSL (HTTPS:). This keystore is used both for communication with the ZIS and the SOAP Services, assuming you are using SSL. Therefore, in order to use SSL, you must import both your ZIS certificate and your SOAP server certificates(s) into the Agent's Trusted keystore.

By default, the agents use Trusted.ks in the agent's install directory to load trusted certificates. However, the Agent's can be configured to use a shared keystore. Using a shared keystore will allow you to import the certificates once and avoid difficulties during upgrades.

The SSDT recommends you configure your agents using a shared keystore, assuming they are installed on the same server. The rest of this page will describe how to configure an absolute path to a keystore and share it between agents.

Configure an absolute path for Trusted.ks

If you use an absolute path for the trust store, then you can share the store with all agents on the same machine and you can avoid problems with the Console's working directory problem.

Due to this, create a directory to contain the keystores (outside the SIF Agent's install directories), for example: /data/SIFAgents/keystores or C:\sif\keystores. If you have a Trusted.ks already containing your certificates, then copy it to this directory.

Next, edit the agent.cfg for each SIF Agent and change the line:

<property value="Trusted.ks" name="trustStore"></property>

To contain the full path to the file:

<property name="trustStore" value="/data/SIFAgents/keystores/Trusted.ks"></property>

You can do the above with the GUI console under Agent Settings->Transports if you prefer. Stop and restart the agents.

With this done, all the Agents and Consoles on the same machine will share the same keystore and you can use any of the Agent Consoles to import SSL certificates.

Importing SOAP Certificates

Once you have a shared Trusted.ks configured, then you must import your SOAP server(s) certificate using an Agent Console's Certificate Manager (Agent Settings->Transports->Certificate Manager). When importing the certificate, be sure to import it as a "Server Certificate" (not an "Agent Certificate"). If your SIF agents communicate with more than one SOAP service, that is, you have separate SOAP servers for USPS and USAS, you should import a cert for each server.

You have three choices when picking which certificate to import depending on what type of certificate is on your SOAP server:

• You can load the server's public key certificate directly. This works for all certificates but is the only choice for self-signed certificates.
• If the certificate is signed by a trusted CA, you can import the certificate of the signing CA.
• If your ITC runs it's own local CA, you can load the certificate of the local CA.

The advantage of loading the CA's cert is you only need to do it for once for all certs signed by the same CA.

Importing a server certificate into the shared keystore will make the certificate available to all clients sharing the keystore. However, agent must be restarted for the change to take effect.

Import ZIS Certificates

See Pearson's documentation for downloading the ZIS SSL certificate using the SIFWorks Administration interface. Use the Agent Console as described above to import the certificate. If your agents register with multiple ZIS's, then import a certificate for each ZIS.

Getting the SOAP Servers Public Key

The easiest way to get a server's certificate or signing CA cert is to use Firefox. Just browse to your web server, inspect certificate (double-click the "Lock" icon in the status bar), view the certificate details. Select the server certificate or the signing CA cert and then use the Export button to export it as an X.509 certificate. The resulting file may be copied to the Agent server and imported into the Trusted.ks using an Agent's Console, Java's keytool or a utility such as Portecle.

MCOECN Hosted USxS-R Instances

If you are utilizing MCOECN hosted USxS-R instances, it will be necessary to obtain the MCOECN's public key and import it into the SIF Agents Trusted.ks.
MCOECN Host - Public Key Procedure.pdf

Importing Multiple Trusted Certificates

When both the ZIS and SOAP service are using HTTPS, it is necessary to import both the ZIS and SOAP server certificate into the agents.

The instructions below assume you have placed the Trusted.ks file and placed the public key(s) to be loaded in the same directory (e.g. "zis.cer" and "soap.cer").

USxS-R With Let's Encrypt

Because the Let's Encrypt certificates are signed, instead of loading the specific certificate, you should be able to load the signing certificates as a trusted CA. If you load the CA certs in the chain, the Agents should trust any certs signed by them. You should not need to load the signed cert into the Agent. The signed Let's Encrypt certificates will expire routinely, but the CA signing certs are long lived.

Using Keytool

The Java runtime provides a command line utility to manage keystores. Before you begin, ensure that "keytool" is a valid command on your system.  If not, ensure the Java home "bin" directory is in your path (see your operating systems instructions for modifying the path) or you may use the full specification of your java installation (ie. /usr/java/jre1.6.0_10/bin/keytool).

 Using the command line, navigate to the directory containing the Trusted.ks and certs, then enter the following command:

> keytool -importcert -trustcacerts -file {filename}.cer -alias {alias} -keystore Trusted.ks -storepass changeit 

Replace "\{filename\}" with the name of the public cert and "\{alias\}" with a short name for representing the certificate (e.g. "zis" or "uspssoap").   After executing the command, keytool will display the certificate details and ask you to confirm loading of the cert. To verify the certificate as loaded:

> keytool -list -keystore Trusted.ks -storepass changeit

Repeat the commands for each certificate which needs to be loaded.  if you need to remove a certificate, first use the above command to determine the cert's "alias", then use:

> keytool -delete -alias zis -keystore Trusted.ks -storepass changeit

Using Portecle

If you prefer to use a GUI to manage the key store, an open source (GPL) product called Portecle provides a useful option.  From a GUI connection (RDC or VNC) on your server, using a Java enabled browser, navigate to the Portecle web site and use the "Launch" button to start the application via Java Webstart.  Alternatively, you may download and install Portecle on your server.

Use Portecle's "File->Open Keystore File" to open the Trusted.ks keystore.   If the Trusted.ks file does not yet exist, you can create it using Portecle "File->New Keystore". If you create a new file, be sure to use the "JKS" format. 

Once the file is open, simply use "Tools->Import Trusted Certificate" to import each certificate. 

SSL Errors

If you are encountering an SSL handshake error, it may be a compatibility issue with Java 6. We have found that some SSL ciphers are not compatible with Java 6.  Updating to Java 7, 32 bit may resolve this issue.

Troubleshooting SSL

To gain more information on the SSL error being encountered, turn on SSL debugging by adding the following option to JVM parameters in the .conf file of the agent.

wrapper.java.additional.1=-Djavax.net.debug=ssl:handshake:verbose

If wrapper.java.additional.1 is already being used in your .conf , simply add another wrapper.java.additional  using the next available number ie. wrapper.java.additional.2