Security terms and concepts

This section provides a general overview of the types of security, the tools used to generate and upload certificates, and the types of data stores installed by WebSphere Partner Gateway.

Security mechanisms and protocols used in WebSphere Partner Gateway

This section provides information about SSL, digital signatures, and encryption.

SSL

WebSphere Partner Gateway can use SSL to secure inbound and outbound documents. An inbound document is one that is sent to the hub. An outbound document is one that is sent from the hub.

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 each other's identity and to ensure data confidentiality and data integrity.

A HTTP-based SSL connection is always initiated by the client using a URL starting with https:// instead of http://. 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.

Notes:
  1. WebSphere Partner Gateway supports the RC2 and TripleDES algorithms. It does not support the RC5 algorithm. If you were using the RC5 algorithm in an earlier release, switch to one of the supported algorithms.
  2. WebSphere Partner Gateway also supports the AES and DES algorithms. You can set these algorithms in the bcg.properties file or with the SecurityService API. Refer to the Administrator Guide for information about the bcg.properties file. Refer to the Programmer Guide for information about SecurityService.

The SSL protocol provides the following security features:

Digital signature

Digital signing is the mechanism for ensuring non-repudiation. Non-repudiation means that a participant cannot deny having originated and sent a message. It also ensures that the participant cannot deny having received a message.

A digital signature allows an originator to sign a message so that the originator is verified as the person who actually sent the message. It also ensures that the message has not been modified since it was signed.

WebSphere Partner Gateway supports PKCS#7 SignedData detached digital signature formats as per the business protocols.

Encryption

WebSphere Partner Gateway uses a cryptographic system known as public key encryption to secure the communication between participants and the hub. Public key encryption uses a pair of mathematically related keys. A document encrypted with the first key must be decrypted with the second, and a document encrypted with the second key must be decrypted with the first.

Each participant in a public key system has a pair of keys. One of the keys is kept secret; this is the private key. The other key is distributed to anyone who wants it; this is the public key. WebSphere Partner Gateway uses a participant's public key to encrypt a document. The private key is used to decrypt a document.

The iKeyman utility

As described in the sections that follow, you use the IBM Key Management Tool (iKeyman) to create key databases, public and private key pairs, and certificate requests. You can also use iKeyman to create self-signed certificates. The iKeyman utility is included in the /<ProductDir>/was/bin directory, which WebSphere Partner Gateway creates during installation.

You can also use iKeyman to generate a request for a certificate to a Certifying Authority (CA).

Community Console

You use the Community Console to install all the required client, signature, and encryption certificates for WebSphere Partner Gateway storage. You can also use the Community Console to install Root and Intermediate CA (Certifying Authority) certificates.

Note: When a participant's certificate expires, it is the participant's responsibility to obtain a new certificate. The Community Console's Alert feature includes certificate expiration alerts for certificates stored in WebSphere Partner Gateway.

Key stores and trust stores

When you install WebSphere Partner Gateway, a key store and trust store for the Receiver and Console are installed.

By default, the two key stores and two trust stores are created in the <ProductDir>/common/security/keystore directory. The names are:

Changing the default password

The default password for accessing all four stores is WebAS. The embedded WebSphere Application Server is configured to use these four stores. You can use the iKeyman utility to change the password. Alternatively, you can use the following UNIX command to change the password of the key store file:

/<ProductDir>/console/was/java/bin/keytool
 -storepasswd -new $NEW_PASSWORD$ -keystore $KEYSTORE_LOCATION$
 -storepass $CURRENT_PASSWORD$ -storetype JKS

If the key store passwords are changed, each WebSphere Application Server instance configuration must also be changed. This can be done using the bcgChgPassword.jacl script. For the Console instance, navigate to the following directory:

/<ProductDir>/bin

and issue the following command:

./bcgwsadmin.sh -f /<ProductDir>/scripts/
bcgChgPassword.jacl -conntype NONE

Repeat this command for the WebSphere Application Server instances of the Receiver and Document Manager.

Note: For Windows installations, use bcgwsadmin.bat instead of ./bcgwsadmin.sh.

You will be prompted for the new password.

Replacing an expired certificate

If a certificate in a trust store has expired, you must add a new certificate to replace it by using the following procedure:

  1. Start iKeyman, if it is not already running.
  2. Open the trust store file.
  3. Type the password and click OK.
  4. Select Signer Certificates from the menu.
  5. Click Add.
  6. Click Data type and select a data type, such as Base64-encoded ASCII data.

    This data type must match the data type of the importing certificate.

  7. Type a certificate file name and location for the CA root digital certificate or click Browse to select the name and location.
  8. Click OK.
  9. Type a label for the importing certificate.
  10. Click OK.

Certificate chains

A certificate chain is made up of a participant's certificate and any certificates used to authenticate the participant's certificate. For example, if a CA was used to create the participant's certificate, that CA might itself have been certified by another CA. The chain of trust begins at the root CA (the trust anchor). The root CA's digital certificate is self-signed; that is, the certificate authority uses its own private key to sign the digital certificate. Any certificates between the trust anchor and the participant's certificate (the target certificate) are intermediate certificates.

For any CA-issued certificates, all certificates in the chain must be added. For example, in a certificate chain in which A (the trust anchor) is the issuer of B and B is the issuer of C (the target certificate), certificates A and B must be uploaded as CA certificates.

WebSphere Partner Gateway treats all self-signed certificates as trust anchors. The self-signed certificate can be of a certifying authority (CA), or it can be a self-signed certificate generated by the participant.

Primary and secondary certificates

You can create more than one certificate of a particular type and designate one as the primary certificate and one as the secondary certificate. If the primary certificate expires or is otherwise unable to be used, WebSphere Partner Gateway switches to the secondary certificate. You specify, on the Community Console, which certificate is primary and which is secondary.

The ability to provide primary and secondary certificates is available for the following certificates:

Changing the encryption strength

Note the following important restrictions about the use of encryption certificates. The Java Runtime Environment (JRE) that ships with WebSphere Partner Gateway enforces restrictions regarding the cryptographic algorithms and maximum cryptographic strengths available for use. For example, restricted policy specifies limits on the allowable length, and, as a result, strength of encryption keys. These restrictions are specified in files called jurisdiction policy files. The maximum allowable length is 2048 bytes. If you want to support certificates with a key size greater than 2048 bytes, use the unrestricted or unlimited strength version of the jurisdiction policy files. You can specify that you want to use stronger, unrestricted policy by installing new policy files to a subdirectory of the installed JRE. There are also encryption restrictions on the symmetric key algorithms, such as DES3. If you need a strong symmetric key algorithm, replacing the jurisdiction policy files will also remove the restrictions for the symmetric keys.

To install unlimited jurisdiction policy files in WebSphere Partner Gateway, perform the following steps:

  1. Download the unlimited jurisdiction strength policy files from the IBM SDK Policy files link at the following Web site: http://www.ibm.com/developerworks/java/jdk/security/142/.
  2. Unzip the downloaded file to a temporary folder
  3. Copy local_policy.jar and US_export_policy.jar from the temporary folder.
  4. Change to the folder <ProductDir>\was\java\jre\lib\security.
  5. Rename the existing local_policy.jar and US_export_policy.jar to local_policy.jar.bak and US_export_policy.jar.bak
  6. Paste the jar files copied in step 3 to the folder <ProductDir>\was\java\jre\lib\security.
  7. Restart the server.

These steps apply to all the WebSphere Application Server instances configured.

Copyright IBM Corp. 2003, 2005