Creating and installing certificates

The following sections describe how to create and install certificates that you want to use with WebSphere Business Integration Connect.

Inbound SSL certificates

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

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 keystore 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.

If you are going to use self-signed server certificates, use one of the following procedures.

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 /WBIC_install_root/router/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 keystore.
  5. Distribute the CA certificate to all participants.

Client authentication

For client authentication, use the following procedure:

  1. Obtain your participant's certificate.
  2. Install the certificate into the truststore using ikeyman.
  3. Place the related CA in the CA directory or related keystore.

Note: When you add more participants to your hub community, you can use ikeyman to add their certificates to the truststore. If a participant leaves the community, you can use ikeyman to remove the participant's certificates from the truststore.

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

You must start the WebSphere Application Server receiver for these changes to take effect.

There is an additional feature that can be used with SSL client authentication. This feature is enabled via the Community Console. For HTTPS, WebSphere Business Integration Connect 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. Select the Validate Client SSL Certificate option on the participant's Gateway screen.

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 Business Integration Connect requests a server-side certificate from the participants. If a participant's certificate is self-signed, use the Community Console to import it into the Hub Operator profile and flag it as a Root certificate. If the certificate is CA-signed, you need only import the CA certificate into the Community Console and flag it as a Root certificate.

Note: The same CA certificate can be used for multiple participants. The certificate must be in X.509 DER format.

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 Business Integration Connect. You can generate the certificate using ikeyman or the createCert.sh script. 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.

If you are going to use a self-signed certificate, use one of the following procedures.

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 keystore.
  4. Distribute the signing CA certificate to all participants.

Adding a Certificate Revocation List (CRL)

Business Integration Connect 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 Business Integration Connect.

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. Business Integration Connect uses the setting bcg.http.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.http.CRLDir=/<shared data directory>/security/crl.

Inbound signature certificate

The Document Manager uses the participant's signed certificate to verify the sender's signature when you receive documents. The participants send their self-signed signature certificates in X.509 DER format to you. You, in turn, install the participants' certificates through the Community Console under the respective participant's profile.

To install the certificate, use the following procedure.

  1. Receive the participant's signature certificate in X.509 DER format.
  2. Install the certificates through the Community Console under the participant's profile. Use Account Admin > Profiles > Community Participant, and search for the participant's profile. Click Certificates, and then upload the certificate as a Digital Signature certificate type. Do not forget to enable and save this certificate on the confirmation screen.
  3. If the certificate was signed by a CA and the CA root certificate is not already installed in the Hub Operator profile, install it now. Use Account Admin > Profiles > Certificates to display the Certificates page. Make sure you are logged in to the Community Console as the Hub Operator, and install the certificate in your own profile.
    Note: You do not have to perform the previous step if the CA certificate is already installed.
  4. Enable at the package (highest level), participant, or connection level (lowest level). Your setting can override other settings at the connection level. The connection summary will inform you if any required attribute is missing.

    For example, to alter the attributes of a participant connection, click Account Admin > Participant Connections and then select the participants. Click Attributes and then edit the attribute (for example, AS Signed).

Outbound signature certificate

The Document Manager uses this certificate when it sends outbound, signed documents to participants. The same certificate and key are used for all ports and protocols.

If you are going to use a self-signed certificate, use one of the following procedures.

ikeyman:

  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 zip file that is password protected, by e-mail. Your participants must call you and request the password for the zip 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 private key pair in the form of a PKCS12 file through the Community Console's certificate feature. Use Account Admin > Profiles > Certificates to display the Certificates page. Make sure you are logged in to the Community Console as the Hub Operator, and install the certificate in your own profile. Flag the certificate as type Digital Signature. Make sure you enable and save the certificate on the confirmation screen.

createCert.sh:

  1. Use the createCert.sh script to generate a self-signed certificate in X.509 format, a private key in PKCS 8 format, and a PKCS12 file which contains both the private key and certificate.
  2. Install the self-signed certificate and key through the Community Console's Certificates feature. Use Account Admin > Profiles > Certificates to display the Certificates page. Make sure you are logged in to the Community Console as the Hub Operator, and install the certificate in your own profile. Flag the certificate as type Digital Signature. Make sure you enable and save the certificate on the confirmation screen.
  3. Distribute the certificate to your participants. The preferred method for distribution is to send the certificate in a zip file that is password protected, by e-mail. Your participants must call you and request the password for the zip file.
  4. Enable at the package (highest level), participant, or connection level (lowest level). Your setting can override other settings at the connection level. The connection summary will inform you if any required attribute is missing. For example, to alter the attributes of a participant connection, click Account Admin > Participant Connections and then select the participants. Click Attributes and then edit the attribute (for example, AS Signed).

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

  1. Start the ikeyman utility.
  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 keystore.
  5. Distribute the signing CA certificate to all participants.

Inbound encryption certificate

This certificate is used by the Receiver to decrypt encrypted files received from participants. The Receiver uses your private key to decrypt the documents. Encryption is used to keep anyone other than the sender and intended recipient from viewing documents in transit.

If you are going to use a self-signed certificate, use one of the following procedures.

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

  1. Start the ikeyman utility.
  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 keystore.
  5. Distribute the signing CA certificate to all participants.

Outbound encryption certificate

The outbound encryption certificate is used when the hub sends encrypted documents to participants. Business Integration Connect encrypts documents with the public keys of the participants, and the participants decrypt the documents with their private keys.

  1. Obtain the participant's encryption certificate. The certificate must be in X.509 DER format.
  2. Install the certificate through the Community Console's Certificates feature. You perform this task logged in to the console as the Hub Operator, and install the certificate in the participant's profile. Use Account Admin > Profiles > Community Participant, and search for the participant's profile. Then click Certificates and upload the certificate as an Encryption type certificate. Make sure you enable and save this certificate on the confirmation screen.
  3. If the certificate is signed by a CA, and you do not have the CA's certificate installed in the system, log in to the console as Hub Operator and install this certificate in your own profile. Use Account Admin > Profiles > Certificates to display the Certificates page. Install the certificate in your own profile. You need only load a CA's certificate once.
  4. Enable at package (highest level), participant, or connection level (lowest level). Your setting can override other settings at the connection level. The connection summary will inform you if any required attribute is missing.

    For example, to alter the attributes of a participant connection, click Account Admin > Participant Connections and then select the participants. Click Attributes and then edit the attribute (for example, AS Encrypted).

Copyright IBM Corp. 2003, 2004