Creating and installing SSL certificates

The following sections describe how to create and install SSL certificates for use with WebSphere Partner Gateway. Also included is an overview of the SSL handshake process. If your community is not using SSL, neither you nor your participants need an inbound or outbound SSL certificate.

SSL handshake

Each SSL session begins with a handshake.

When a client (the participant or Community Manager) initiates a message exchange, the following steps occur:

  1. The client sends a client "hello" message that lists the cryptographic capabilities of the client (sorted in client preference order), such as the version of SSL, the cipher suites supported by the client, and the data compression methods supported by the client. The message also contains a 28-byte random number.
  2. The server responds with a server "hello done" message that contains the cryptographic method (cipher suite) and the data compression method selected by the server, the session ID, and another random number.
    Note: The client and the server must support at least one common cipher suite, or else the handshake fails. The server generally chooses the strongest common cipher suite.
  3. The server sends its digital certificate.

    Server authentication happens at this step.

  4. The server sends a "digital certificate request" message. In the "digital certificate request" message, the server sends a list of the types of digital certificates supported and the distinguished names of acceptable certificate authorities.
  5. The server sends a server "hello done" message and waits for a client response.
  6. Upon receipt of the server "hello done" message, the client verifies the validity of the server's digital certificate and checks that the server's "hello" parameters are acceptable.
  7. If the server requested a client digital certificate, the client sends a digital certificate, or if no suitable digital certificate is available, the client sends a "no digital certificate" alert. This alert is only a warning, but the server application can fail the session if client authentication is mandatory.
  8. The client sends a "client key exchange" message. This message contains the premaster secret, a 46-byte random number used in the generation of the symmetric encryption keys and the message authentication code (MAC) keys, encrypted with the public key of the server.
  9. If the client sent a digital certificate to the server, the client sends a "digital certificate verify" message signed with the client's private key. By verifying the signature of this message, the server can explicitly verify the ownership of the client digital certificate.
    Note: An additional process to verify the server digital certificate is not necessary. If the server does not have the private key that belongs to the digital certificate, it cannot decrypt the premaster secret and create the correct keys for the symmetric encryption algorithm, and the handshake fails.
  10. The client uses a series of cryptographic operations to convert the premaster secret into a master secret, from which all key material required for encryption and message authentication is derived. Then the client sends a "change cipher spec" message to make the server switch to the newly negotiated cipher suite. The next message sent by the client (the "finished" message) is the first message encrypted with this cipher method and keys.
  11. The server responds with a "change cipher spec" and a "finished" message of its own.

Client authentication requires steps 4, 7, and 9.

The SSL handshake ends, and encrypted application data can be sent.

Inbound SSL certificates

This section describes how to configure server authentication and client authentication for inbound connection requests from participants.

Server authentication

WebSphere Application Server uses the SSL certificate when it receives connection requests from participants through SSL. It is the certificate that the Receiver presents to identify the hub to the participant. This server certificate can be self-signed, or it can be signed by a CA. In most cases you will use a CA certificate to increase security. You might use a self-signed certificate in a test environment. Use iKeyman to generate a certificate and key pair. Refer to documentation available from IBM for more information about using iKeyman.

After you generate the certificate and key pair, use the certificate for inbound SSL traffic for all participants. If you have multiple Receivers or Consoles, copy the resultant key store to each instance. If the certificate is self-signed, provide this certificate to the participants. To obtain this certificate, use iKeyman to extract the public certificate to a file.

Using a self-signed certificate

If you are going to use self-signed server certificates, use the following procedure.

  1. Start the iKeyman utility, which is located in /<ProductDir>/was/bin. If this is your first time using iKeyman, delete the "dummy" certificate that resides in the key store.
  2. Use iKeyman to generate a self-signed certificate and a key pair for the Receiver or Console key store.
  3. Use iKeyman to extract to a file the certificate that will contain your public key.

    Save the key store to a JKS, PKCS12, or JCEK file.

  4. Install the file into the Receiver or Console key store for which it was created.
  5. Distribute the certificate to your participants. The preferred method for distribution is to send the certificate in a zipped file that is password-protected, by e-mail. Your participants must call you and request the password for the zipped file.
Using a CA-generated certificate

If you are going to use a certificate signed by a CA, use the following procedure.

  1. Start the iKeyman utility, which is located in the /<ProductDir>/was/bin directory.
  2. Use iKeyman to generate a certificate request and a key pair for the Receiver.
  3. Submit a Certificate Signing Request (CSR) to a CA.
  4. When you receive the signed certificate from the CA, use iKeyman to place the signed certificate into the key store.
  5. Distribute the CA certificate to all participants.

Client authentication

If you want to authenticate participants who send documents, perform the steps in this section.

Installing the client certificate

For client authentication, use the following procedure:

  1. Obtain your participant's certificate.
  2. Install the certificate or certificates into the trust store using iKeyman.
  3. Place the related CA or CAs in the related key store.

Note: When you add more participants to your hub community, you can use iKeyman to add their certificates to the trust store. If a participant leaves the community, you can use iKeyman to remove the participant's certificates from the trust store.
Setting up client authentication

After installing the certificate or certificates, configure WebSphere Application Server to use client authentication by running the utility script bcgClientAuth.jacl.

  1. Navigate to the following directory: /<ProductDir>/bin
  2. To turn on client authentication, call the script as follows:
    ./bcgwsadmin.sh -f /<ProductDir>/scripts/bcgClientAuth.jacl
       -conntype NONE set 
    Note: To turn off client authentication, call the script as follows:
    ./bcgwsadmin.sh -f /<ProductDir>/receiver/scripts/bcgClientAuth.jacl 
      -conntype NONE clear

You must restart the bcgreceiver server for these changes to take effect.

Validating the client's certificate

There is an additional feature that can be used with SSL client authentication. This feature is enabled through the Community Console. For HTTPS, WebSphere Partner Gateway checks certificates against the Business IDs in the inbound documents. To use this feature, create the participant's profile, import the client certificate, and flag it as SSL.

  1. Import the client certificate.
    1. Click Account Admin > Profiles > Community Participant, and search for the participant's profile.
    2. Click Certificates.
    3. Click Load Certificate.
    4. Select SSL Client as the type of certificate.
    5. Type a description of the certificate (which is required).
    6. Change the status to Enabled.
    7. Click Browse and navigate to the directory in which you have saved the certificate.
    8. Select the certificate and click Open.
    9. If you want to select a gateway type other than Production (the default), select it from the list.
    10. Click Upload and then click Save.
  2. Update the client gateway.
    1. Click Account Admin > Profiles > Community Participant, and search for the participant's profile.
    2. Click Gateways.
    3. Select the HTTPS gateway you previously created. If you have not yet created the HTTPS gateway, see Setting up an HTTPS gateway.
    4. Click the Edit icon to edit the gateway.
    5. Select Yes for Validate SSL Client Certificate.
    6. Click Save.

Outbound SSL certificate

If your community is not using SSL, you do not need an inbound or outbound SSL certificate.

Server authentication

When SSL is being used to send outbound documents to your participants, WebSphere Partner Gateway requests a server-side certificate from the participants. The same CA certificate can be used for multiple participants. The certificate must be in X.509 DER format.

Note: You can convert the format with the iKeyman utility. Follow these steps to use iKeyman to convert the format:
  1. Start iKeyman.
  2. Create a new blank key store or open an existing key store.
  3. In the Key Database Content, select Signer Certificates.
  4. Add the ARM certificate using the Add option.
  5. Extract the same certificate as a Binary DER data using the Extract option.
  6. Close iKeyman.

Install the participant's self-signed certificate into the Hub Operator profile. If the certificate was signed by a CA and the CA root certificate and any other certificates that are part of the certificate chain are not already installed in the Hub Operator profile, install the certificates in the Hub Operator profile.

  1. Click Certificates.
  2. Click Load Certificates.
  3. Select Root and Intermediate as the type of certificate.
  4. Type a description of the certificate (which is required).
  5. Change the status to Enabled.
  6. Click Browse and navigate to the directory in which you have saved the certificate.
  7. Select the certificate and click Open.
  8. Click Upload and then click Save.

Note: You do not have to perform the previous steps if the CA certificate is already installed.

Client authentication

If SSL client authentication is required, the participant will, in turn, request a certificate from the hub. Use the Community Console to import your certificate into WebSphere Partner Gateway. You can generate the certificate using iKeyman. If the certificate is a self-signed certificate, it must be provided to the participant. If it is a CA-signed certificate, the CA root certificate must be given to the participants, so that they can add it to their trusted certificates.

You can have more than one SSL certificate. One is the primary certificate, which is the one used by default. The other is a secondary certificate, which is used if the primary certificate expires or is otherwise unable to be used.

Using a self-signed certificate

If you are going to use a self-signed certificate, use the following procedure.

  1. Start the iKeyman utility.
  2. Use iKeyman to generate a self-signed certificate and a key pair.
  3. Use iKeyman to extract to a file the certificate that will contain your public key.
  4. Distribute the certificate to your participants. The preferred method for distribution is to send the certificate in a zipped file that is password-protected, by e-mail. Your participants must call you and request the password for the zipped file.
  5. Use iKeyman to export the self-signed certificate and private key pair in the form of a PKCS12 file.
  6. Install the self-signed certificate and key through the Community Console.
    1. Click Account Admin > Profiles > Certificates to display the Certificate List page.

      Make sure you are logged in to the Community Console as the Hub Operator.

    2. Click Load PKCS12.
      Note: The PKCS12 file being uploaded should contain only one private key and the associated certificate.
    3. Select SSL Client as the type of certificate.
    4. Type a description of the certificate (which is required).
    5. Change the status to Enabled.
    6. Click Browse and navigate to the directory in which you have saved the certificate.
    7. Select the certificate and click Open.
    8. Enter the password.
    9. If you want to select a gateway type other than Production (the default), select it from the list.
    10. If you have two SSL certificates, indicate whether this is the primary or secondary certificate by selecting Primary or Secondary from the Certificate Usage list.
    11. Click Upload and then click Save.

If you are uploading primary and secondary certificates for both SSL client authentication and digital signature and you are uploading the primary certificates as two separate entries, make sure that the corresponding secondary certificates are uploaded as two different entries.

Using a CA-signed certificate

If you are going to use a certificate signed by a CA, use the following procedure:

  1. Use iKeyman to generate a certificate request and a key pair for the Receiver.
  2. Submit a Certificate Signing Request (CSR) to a CA.
  3. When you receive the signed certificate from the CA, use iKeyman to place the signed certificate into the key store.
  4. Distribute the signing CA certificate to all participants.

Adding a Certificate Revocation List (CRL)

WebSphere Partner Gateway includes a Certificate Revocation List (CRL) feature. The CRL, issued by a Certificate Authority (CA), identifies participants who have revoked certificates before their scheduled expiration date. Participants with revoked certificates will be denied access to WebSphere Partner Gateway.

Each revoked certificate is identified in a CRL by its certificate serial number. The Document Manager scans the CRL every 60 seconds and refuses a certificate if it is contained within the CRL list.

CRLs are stored in the following location: /<shared_data_directory>/security/crl. WebSphere Partner Gateway uses the setting bcg.CRLDir in the bcg.properties file to identify the location of the CRL directory.

Create a .crl file containing the revoked certificates and place it in the CRL directory.

For example, in the bcg.properties file, you would use the following setting:

bcg.CRLDir=/<shared_data_directory>/security/crl

Enabling access to CRL distribution points

CAs maintain and update the CRLs. These CRLs are typically stored in a CRL distribution point. CRLs are used while doing revocation checks for the certificates to determine whether the certificate is revoked.

The bcgSetCRLDP.jacl script can be used to enable or disable CRL distribution point checking when the revocation check is performed. If you need the CRL distribution points to be accessed when revocation checking of a certificate is performed, enable the use of CRL distribution points. If the certificates you have installed contain a CRL DP extension, you can enable the use of CRL distribution points so that the distribution points are accessed when the revocation check is performed. If you have downloaded all the required CRLs in the directory set in bcg.properties for the property bcg.CRLDir, you might not want to enable the use of CRL distribution points. If the current CRLs are not likely to be available in the bcg.CRLDir directory, you should enable the use of CRL distribution points.

The CRL distribution points accessible via HTTP and LDAP are supported. You can also configure proxies to access the CRL distribution points.

Note: For Windows installations, use bcgwsadmin.bat instead of ./bcgwsadmin.sh in the commands listed in this section.

To enable the use of CRL distribution points, run the following command from the <ProductDir>/bin directory:

./bcgwsadmin.sh -f <ProductDir>/scripts/bcgSetCRLDP.jacl install
 <nodename> <serverName> CRLDP

where:

<server_root>
The root directory of the server (for example, /opt/ibm/receiver/was/profiles/bcgreceiver)
<serverName>
Can be bcgdocmgr, bcgreceiver, or bcgconsole. The command needs to be run from the corresponding <server_root>.

To disable the use of CRL distribution points, run the following command from the <ProductDir>/bin directory:

./bcgwsadmin.sh -f <ProductDir>/scripts/bcgSetCRLDP.jacl uninstall 
<nodename> <serverName> CRLDP

To enable the use of CRL distribution points with a proxy, run the following command from the <ProductDir>/bin directory:

./bcgwsadmin.sh -f <ProductDir>/scripts/bcgSetCRLDP.jacl install
 <nodename> <serverName> CRLDP <proxyHost> <proxyPort>

To specify that you do not want to use a proxy, run the following command from the <ProductDir>/bin directory:

./bcgwsadmin.sh -f <ProductDir>/scripts/bcgSetCRLDP.jacl
 uninstall <nodename> <serverName> PROXY

If you are using a Receiver user exit and if the user exit uses the SecurityService API, the above settings are applicable for the bcgreceiver server also. To run the above commands for the Receiver, replace bcgdocmgr with bcgreceiver.

Copyright IBM Corp. 2003, 2005