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:
-
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.
- 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.
- The server sends its digital certificate.
Server authentication happens at this step.
-
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.
- The server sends a server "hello done" message and waits for
a client response.
- 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.
-
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.
- 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.
-
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.
-
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.
- 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.
-
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.
- Use iKeyman to generate a self-signed certificate and a key
pair for the Receiver or Console key store.
- 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.
- Install the file into the Receiver or Console key store for
which it was created.
-
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.
-
Start the iKeyman utility, which is located
in the /<ProductDir>/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 key store.
-
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:
- Obtain your participant's certificate.
- Install the certificate or certificates into the trust store
using iKeyman.
- 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.
- Navigate to the following directory: /<ProductDir>/bin
- 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.
- Import the client certificate.
- Click Account Admin > Profiles > Community Participant,
and search for the participant's profile.
- Click Certificates.
- Click Load Certificate.
- Select SSL Client as the type of certificate.
- Type a description of the certificate (which is required).
- Change the status to Enabled.
- Click Browse and navigate to the directory
in which you have saved the certificate.
- Select the certificate and click Open.
- If you want to select a gateway type other than Production (the
default), select it from the list.
- Click Upload and then click Save.
- Update the client gateway.
- Click Account Admin > Profiles > Community Participant,
and search for the participant's profile.
- Click Gateways.
- Select the HTTPS gateway you previously created. If you have
not yet created the HTTPS gateway, see Setting up an HTTPS gateway.
- Click the Edit icon to edit the gateway.
- Select Yes for Validate SSL Client Certificate.
- 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:
- Start iKeyman.
- Create a new blank key store or open an existing key store.
- In the Key Database Content, select Signer Certificates.
- Add the ARM certificate using the Add option.
- Extract the same certificate as a Binary DER data using the Extract option.
- 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.
- Click Certificates.
- Click Load Certificates.
- Select Root and Intermediate as the type
of certificate.
- Type a description of the certificate (which is required).
- Change the status to Enabled.
- Click Browse and navigate to the directory
in which you have saved the certificate.
- Select the certificate and click Open.
- 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.
- 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 zipped file
that is password-protected, by e-mail. Your participants must call
you and request the password for the zipped 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.
- 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.
- Click Load PKCS12.
Note: The PKCS12 file being uploaded should contain only
one private key and the associated certificate.
- Select SSL Client as the type of certificate.
- Type a description of the certificate (which is required).
- Change the status to Enabled.
- Click Browse and navigate to the directory
in which you have saved the certificate.
- Select the certificate and click Open.
- Enter the password.
- If you want to select a gateway type other than Production (the
default), select it from the list.
- 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.
- 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:
- 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 key store.
- 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.
