Using the Secure Sockets Layer (SSL) protocol

WebSphere Partner Gateway - Express uses the Secure Sockets Layer (SSL) protocol to secure inbound and outbound documents. SSL is a commonly used protocol for managing security over the Internet. SSL provides secure connections by enabling two applications linked through a network connection to authenticate the other's identity and by encrypting the data exchanged between the applications.

An SSL connection begins with a handshake. During this stage, the applications exchange digital certificates, agree on the encryption algorithms to use, and generate encryption keys used for the remainder of the session.

The SSL protocol provides the following security features:

The following sections describe how to use SSL for inbound server and client authentication and outbound client authentication.

Using keystores for inbound server authentication

Using truststores for inbound client authentication

Using keypairs for outbound client authentication

Enabling HTTPS

Using keystores for inbound server authentication

A keystore for securing inbound documents over an SSL connection can be generated and uploaded automatically within WebSphere Partner Gateway - Express or uploaded from a location outside the application. The keystore can then be downloaded.

A keystore is a protected database that holds keys and certificates. If your participants have keys and certificates and use SSL, you can use the Inbound page to make the keystore available. The following topics describe how to use keystores for inbound server authentication.

Generating a self-signed SSL keystore

Uploading an SSL keystore

Downloading an SSL keystore

Generating a self-signed SSL keystore

The following procedure describes how to use WebSphere Partner Gateway - Express to generate a self-signed SSL keystore for securing inbound documents. When you generate a self-signed keystore, it is uploaded into WebSphere Partner Gateway - Express automatically.

  1. Click the Security tab to display the Inbound page. If the page does not appear, click Inbound in the navigation bar.
  2. Locate the SSL Connection row, then, in the Generate column, click the Generate Self-Signed Certificate icon. The Inbound Generate Self-Signed SSL Keystore page appears.
  3. Complete the entries in the Inbound page (see Table 11).
  4. Click the Create button. The self-signed keystore is uploaded and appears in the Inbound page.
    Table 11. Inbound page for Generated Self-Signed SSL Keystore
    Parameter Description

    Common Name

    Enter the server host name.

    Organization

    Enter the name of the participant's company.

    Organizational Unit

    Enter the name of the department where the participant works.

    Locality

    Enter the locale or city where the participant works.

    State

    Enter the state or province where the participant works.

    Country

    Enter the country where the participant works.

    E-mail Address

    Enter the participant's e-mail address.

    Certificate Validity

    Enter the number of days for which the keystore is valid.

    Keystore Password

    Enter the keystore password.

    Private Key Password

    Enter the private key password.

Uploading an SSL keystore

If you have an SSL keystore you want to upload into WebSphere Partner Gateway - Express, use the following procedure.

  1. Click the Security tab to display the Inbound page. If the page does not appear, click Inbound in the horizontal navigation bar.
  2. Locate the SSL Connection row, then, in the Upload column, click the Add/Update Certificate/Key icon. The Inbound page appears.
  3. Complete the entries in the Inbound page (see Table 12).
  4. Click the Submit button. The keystore is uploaded and appears in the Inbound page.
    Table 12. Inbound page for Uploaded SSL Keystore
    Parameter Description

    Keystore File

    Enter the path and name of the keystore file you want to upload. Alternatively, click the Browse button to select the keystore file you want to upload.

    Keystore Password

    Enter the keystore password for the keystore you want to upload.

    Key Password

    Enter the key password for the keystore you want to upload.

Downloading an SSL keystore

After you upload an SSL keystore into WebSphere Partner Gateway - Express, you can use the following procedure to download the public certificate encapsulated in the keystore database.

  1. Click the Security tab to display the Inbound page. If the page does not appear, click Inbound in the horizontal navigation bar.
  2. Locate the SSL Connection row, then, in the Download column, click the Download Public Certificate icon. A "file-download" page appears.
    Note:
    Depending on your browser version and firewall settings, the dialogue box may prompt you to select either opening the file or saving it to disk. If this occurs select the "save" option.
  3. Click Save (or equivalent) to display the Save As dialog box, select a location where you want to download the certificate, and click Save.

Using truststores for inbound client authentication

A truststore is used for client authentication, when WebSphere Partner Gateway - Express wants to verify the certificate provided by the server. From a truststore, the system can ascertain whether to trust a client and allow the client access to the site.

Using the Inbound page, you can upload a truststore for client authentication. The truststore can then be deleted when it is no longer required.

If the truststore you want to upload has not been created, you can use keytool to create it. The following section describes this procedure.

Important:
To enable client authentication, you must first run the bcgClientAuth.jacl script, located at <ProductDir>/jaclScripts. Instructions for invoking the script are in the script itself.

Using keytool

Keytool is a key and certificate management utility. It lets you create keys for use in self-authentication (where WebSphere Partner Gateway - Express authenticates itself to other entities and services) or data integrity and authentication services, using digital signatures. It also lets you cache the public keys (in the form of certificates) of their communicating peers.

Keytool stores the certificates in a truststore. The default truststore implementation implements the keystore as a file. Once you create the file, you can use the procedure under Uploading a truststore for client authentication to upload the file into WebSphere Partner Gateway - Express.

The following procedures describe how to use keytool to create a truststore, list certificates in a truststore, add certificates to a truststore, and delete certificates from a truststore. The commands used to perform these procedures can be executed from any system that has Java installed. For convenience, keytool is provided in the was\java\jre\bin directory of the WebSphere Partner Gateway - Express CD.

Note:
You can also use ikeyman, a GUI bundled with WebSphere Partner Gateway - Express that allows you to manage certificates in a truststore. The ikeyman executables are located in the was\bin directory.
Creating a truststore

To create a truststore, use the following procedure.

  1. Open a command prompt window and set the current directory to the location of the keytool.exe file.
  2. Execute the following command:
    keytool -genkey -keystore <truststore filename> -storetype PKCS12
Listing certificates in a truststore

To list certificates in a truststore, use the following procedure.

  1. Open a command prompt window and set the current directory to the location of the keytool.exe file.
  2. Execute the following command:
    keytool -list -v -keystore <truststore>
  3. When keytool prompts you for a truststore password, enter the appropriate password to list the certificates in the truststore.
Adding a certificate to a truststore

To add a certificate to a truststore, use the following procedure.

  1. Open a command prompt window and set the current directory to the location of the keytool.exe file.
  2. Execute the following command. In this command, the alias option lets you assign a name to the certificate that is easy to remember. This will allow you to identify the truststore entries easily when you list it in the future.
    keytool -import -keystore <truststore> -file <certificate file> -trustcacerts -alias <cert name>
  3. When keytool prompts you for a truststore password, enter the appropriate password to add the certificates to the truststore.
Removing a certificate from a truststore

To remove a certificate from a truststore, use the following procedure.

  1. Open a command prompt window and set the current directory to the location of the keytool.exe file.
  2. Execute the following command.
    keytool -delete -alias <cert name> -keystore truststore
  3. When keytool prompts you for a truststore password, enter the appropriate password to remove the certificate from the truststore.
Uploading a truststore for client authentication

After a truststore has been created, use the following procedure to upload it for client authentication of inbound documents.

  1. Click the Security tab to display the Inbound page. If the page does not appear, click Inbound in the navigation bar.
  2. From the Selected Participant drop-down menu, select the participant for whom you want to upload the truststore.
  3. Locate the Client Auth row, then, in the Upload column, click the Add/Update Certificate/Key icon. The Inbound Upload Truststore for Client Authentication page appears.
  4. Complete the entries in the page (see Table 13).
  5. Click the Submit button. The truststore is uploaded and appears in the Inbound page.
    Table 13. Inbound page for Uploaded Truststore for Client Authentication
    Parameter Description

    Truststore File

    Enter the path and name of the truststore file you want to upload. Alternatively, click the Browse button to select the truststore file you want to upload.

    Truststore Password

    Enter the truststore password.

Using keypairs for outbound client authentication

For outbound documents, client authentication is where WebSphere Partner Gateway - Express identifies itself to a remote server. The following topics describe how to use keypairs for outbound client authentication.

Generating a self-signed SSL client certificate keypair

Uploading a client authentication keypair

Downloading the client certificate for client authentication

Generating a self-signed SSL client certificate keypair

The following procedure describes how to use WebSphere Partner Gateway - Express to generate a self-signed SSL client certificate keypair. When you generate a self-signed SSL client certification keypair, it is uploaded into WebSphere Partner Gateway - Express automatically.

  1. Click the Security tab, then click Outbound in the navigation bar. The Outbound page appears.
  2. From the Selected Participant drop-down menu, select the participant for whom you want to generate the self-signed keypair.
  3. Locate the Client Auth row, then, in the Generate column, click the Generate Self-Signed Certificate icon. The Outbound page appears.
  4. Complete the entries in the Outbound page (see Table 14).
  5. Click the Create button. The self-signed keystore is uploaded and appears in the Outbound page.
    Table 14. Outbound page for Generated Self-Signed
    SSL Client Certificate Keypair
    Parameter Description

    Common Name

    Enter the server host name.

    Organization

    Enter the name of the participant's company.

    Organizational Unit

    Enter the name of the department where the participant works.

    Locality

    Enter the locale or city where the participant works.

    State

    Enter the state or province where the participant works.

    Country

    Enter the country where the participant works.

    E-mail Address

    Enter the participant's e-mail address.

    Certificate Validity

    Enter the number of days for which the keypair is valid.

    Private Key Password

    Enter the private key password.

Uploading a client authentication keypair

To upload a client authentication keypair identifying this client to a remote SSL-enabled host, use the following procedure.

  1. Click the Security tab, then click Outbound in the navigation bar. The Outbound page appears.
  2. From the Selected Participant drop-down menu, select the participant for whom you want to upload the keypair.
  3. Locate the Client Auth row, then, in the Upload column, click the Add/Update Certificate/Key icon. The Outbound Upload Client Certificate Keypair page appears.
  4. Complete only the Public Certificate entry in the Outbound page (see Table 15).
  5. Click the Submit button. The keypair is uploaded and appears in the Outbound page.
    Table 15. Outbound page for Client Authentication Keypair
    Parameter Description

    Public Certificate

    Enter the path and name of the public certificate file you want to upload. Alternatively, click the Browse button to select the public certificate file you want to upload.

Downloading the client certificate for client authentication

After you upload a keypair into WebSphere Partner Gateway - Express, you can use the following procedure to download the public certificate. This public certificate can be e-mailed to the partner for inclusion within the partner's truststore.

  1. Click the Security tab, then click Outbound in the navigation bar. The Outbound page appears.
  2. From the Selected Participant drop-down menu, select the participant whose keypair you want to download.
  3. Locate the Client Auth row, then, in the Download column, click the Download Public Certificate icon. A "file-download" page appears.
    Note:
    Depending on your browser version and firewall settings, the dialogue box may prompt you to select either opening the file or saving it to disk. If this occurs select the "save" option.
  4. Click Save (or equivalent) to display the Save As dialog box, select a location where you want to download the keypair, and click Save.

Enabling HTTPS

The following steps describe how to enable HTTPS.

  1. Click the Configuration tab, then click My Profile in the navigation bar. The Manage My Profile page appears.
  2. Click the Edit button to open the Manage My Profile editing page.
  3. In the Secure field (under Domain) of the Receipt Address section, enter a domain name, then enter an available HTTPS port number in the corresponding Port field.
  4. If appropriate or necessary, fill in fields under Company AS2 ID and Company Details, then click Save.
  5. Click the Configuration tab, then click Manage Participants in the navigation bar. The Manage Participants page appears.
  6. Click Edit for the participant whose HTTPS you want to enable. The Edit Participant page appears.
  7. Select the HTTPS check box, then click Save.

Copyright IBM Corp. 2003, 2005