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.
- ikeyman:
- Start the ikeyman utility, which is located in /WBIC_install_root/router/was/bin.
If this is your first time using ikeyman, delete the "dummy" certificate
that resides in the keystore.
- Use ikeyman to generate a self-signed certificate and a key
pair for the Receiver or Console keystore.
- Use ikeyman to extract to a file the certificate that will contain
your public key.
- Install the pkcs12 file into the Receiver or Console keystore
for which it was created.
- 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.
- createCert.sh:
- Use the createCert.sh script, located in the /WBIC_install_root/router/was/bin
directory, 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.
- Install the pkcs12 file into the Receiver or Console keystore
for which it was created.
- 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.
If you are going to use a certificate signed by a CA, use the
following procedure.
- Start the ikeyman utility, which is located in the /WBIC_install_root/router/was/bin
directory.
- Use ikeyman to generate a certificate request and a key pair
for the Receiver.
- Submit a Certificate Signing Request (CSR) to a CA.
- When you receive the signed certificate from the CA, use ikeyman
to place the signed certificate into the keystore.
- Distribute the CA certificate to all participants.
Client authentication
For client authentication, use the following procedure:
- Obtain your participant's certificate.
- Install the certificate into the truststore using ikeyman.
- 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.
- Navigate to the following directory: /WBIC_install_root/receiver/was/bin
- To turn on client authentication, call the script as follows:
./wsadmin.sh -f /WBIC_install_root/receiver/scripts/bcgClientAuth.jacl
-conntype NONE set
- To turn off client authentication, call the script as follows:
./wsadmin.sh -f /WBIC_install_root/receiver/scripts/bcgClientAuth.jacl
-conntype NONE clear
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.
- ikeyman:
- Start the ikeyman utility.
- Use ikeyman to generate a self-signed certificate and a key
pair.
- Use ikeyman to extract to a file the certificate that will contain
your public key.
- 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.
- Use ikeyman to export the self-signed certificate and private
key pair in the form of a PKCS12 file.
- Install the self-signed certificate and key through the Community
Console. Use Account Admin > Profiles > Certificates to
display the Certificates page. Make sure you are logged in to the
Community Console as the Hub Operator. Install the certificate in
your own profile and flag it as an SSL type
certificate.
- createCert.sh:
- 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.
- Install the self-signed certificate and key through the Community
Console. Use Account Admin > Profiles > Certificates to
display the Certificates page. Make sure you are logged in to the
Community Console as the Hub Operator. Install the certificate in
your own profile and flag it as an SSL type
certificate.
- Send your self-signed certificate or CA root certificate to
all participants so they can add it as a trusted certificate.
If you are going to use a certificate signed by a CA, use the
following procedure:
- Use ikeyman to generate a certificate request and a key pair
for the Receiver.
- Submit a Certificate Signing Request (CSR) to a CA.
- When you receive the signed certificate from the CA, use ikeyman
to place the signed certificate into the keystore.
- 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.
- Receive the participant's signature certificate in
X.509 DER format.
- 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.
- 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.
- 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:
- Start the ikeyman utility.
- Use ikeyman to generate a self-signed certificate and a key
pair.
- Use ikeyman to extract to a file the certificate that will contain
your public key.
- 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.
- Use ikeyman to export the self-signed certificate and private
key pair in the form of a PKCS12 file.
- 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:
- 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.
- 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.
- 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.
- 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:
- Start the ikeyman utility.
- Use ikeyman to generate a certificate request and a key pair
for the Receiver.
- Submit a Certificate Signing Request (CSR) to a CA.
- When you receive the signed certificate from the CA, use ikeyman
to place the signed certificate into the keystore.
- 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.
- ikeyman:
- Start the ikeyman utility.
- Use ikeyman to generate a self-signed certificate and a key
pair.
- Use ikeyman to extract to a file the certificate that will contain
your public key.
- Distribute the certificate to your participants. They are required
to import the file into their B2B product for use as an encryption
certificate. Advise them to use it when they want to send encrypted
files to the Community Manager. If your certificate is CA-signed,
provide the CA certificate as well.
- Use ikeyman to export the self-signed certificate and private
key pair in the form of a PKCS12 file.
- Install the self-signed certificate and private key pair in
the form of a PKCS12 file through the Community Console. 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 an Encryption type
and make sure you enable and save the installed certificate on the
confirmation screen.
- 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).
- createCert.sh:
- 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.
- Install the self-signed certificate and key through the 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 an Encryption type.
Make sure you enable and save the installed certificate on the confirmation
screen.
- Distribute the certificate to your participants. They are required
to import the file into their B2B product for use as an encryption
certificate. Advise them to use it when they want to send encrypted
files to the Community Manager.
- 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).
If you are going to use a certificate signed by a CA, use the
following procedure:
- Start the ikeyman utility.
- Use ikeyman to generate a certificate request and a key pair
for the Receiver.
- Submit a Certificate Signing Request (CSR) to a CA.
- When you receive the signed certificate from the CA, use ikeyman
to place the signed certificate into the keystore.
- 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.
- Obtain the participant's encryption certificate. The certificate
must be in X.509 DER format.
- 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.
- 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.
- 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).
