Configuring the Keystore

This topic includes the following sections:

• About the Keystore

• Creating the Domain

• Creating the Keystores and Inserting the Server Certificates

• Configuring the WebLogic Keystore Provider

• Adding Trading Partner Certificates to the Keystore

• Configuring the Domain to Use the Keystore

• Using the Keystore in a Multinode Cluster

For general information about configuring WebLogic Integration B2B, see Basic Configuration Tasks in Administering B2B Integration.

 

---

About the Keystore

A keystore is a protected database that holds keys and certificates. If you have keys and certificates and use message encryption, digital signatures, or SSL, we recommend that you use a keystore for storing those keys and certificates and make the keystore available to applications that may need it for authentication or signing purposes, such as a B2B application. To create a keystore and make it available, you need a keystore provider, which has been introduced in the WebLogic Server 7.0 security architecture.

The WebLogic Keystore provider uses the reference Keystore implementation supplied by Sun Microsystems in the Java Development Kit. The WebLogic Keystore provider:

• Utilizes the JDK bundled Java KeyStore (JKS) provider, which implements the keystore as a file

• Protects each private key with an individual password

• Protects the entire keystore with a password

Keystores You Create

When you set up a WebLogic Integration domain for B2B collaborations, you configure the WebLogic Keystore provider to create the following keystores:

• Private keystore

  Stores the trading partners' certificates and private keys, such as for the client, server, signature, and encryption certificates typically required for B2B collaborations. The B2B engine retrieves private keys and certificates from this keystore to use for SSL, message encryption, and digital signatures. You can use the JavaSoft JDK keytool utility or the WebLogic Server ImportPrivateKey utility to create this keystore and to add private keys and their associated certificates to it.

• Root CA keystore

  Stores the certificates of all the trusted certificate authorities (CAs). The WebLogic Keystore provider creates a trusted CA keystore that WebLogic Server uses by default to locate the trusted CAs used by SSL to verify client, server, signature, and encryption certificates.

Steps for Creating and Configuring Keystores

Complete the following basic steps to create and configure the keystores required for your B2B collaborations:

1. Create the B2B domain.

2. Create the keystores and insert the server certificates and keys required by SSL.

3. Configure the WebLogic Keystore provider.

4. Add trading partner certificates to the keystore.

5. Add trusted certificate authority certificates to the CA keystore.

6. Configure the domain to use the keystores.

This topic also includes a discussion about using keystore files in a multinode cluster.

For background information about keystores, certificates, and keys, see the following:

• For details about the WebLogic Keystore provider, see The WebLogic Security Providers in Introduction to WebLogic Security, available at the following URL:

  http://download.oracle.com/docs/cd/E13222_01/wls/docs70/secintro/model.html

• For details about certificates and keys, see:

  • Security Fundamentals in Programming WebLogic Security, available at the following URL:
    http://download.oracle.com/docs/cd/E13222_01/wls/docs70/security/concepts.html

 

---

Creating the Domain

We recommend that you use the BEA Configuration Wizard to create the WebLogic Integration B2B domain for which you will be configuring security. To create a WebLogic Integration domain, complete the following steps:

1. Start the Configuration Wizard as described in Using the Configuration Wizard, available at the following URL:

   http://download.oracle.com/docs/cd/E13196_01/platform/docs70/confgwiz/index.html

2. Complete the configuration of the WebLogic Integration domain, which can be any of the following:

   • WebLogic Integration BPM Domain

   • WebLogic Integration EAI Domain

   • WebLogic Integration Domain

   Note: Make sure you select a WebLogic Integration template for creating the new domain; do not use a WebLogic Server or a WebLogic Portal template. By using a WebLogic Integration template, you can ensure that the domain created in this step is based on the WebLogic Server 6.x security realm in compatibility mode. The new WebLogic Server 7.0 realm, based on LDAP, is not supported with WebLogic Integration. If you create a new domain by selecting a WebLogic Server template, the new domain uses the new WebLogic Server 7.0 security realm, which is based on LDAP.

3. After you exit from the Configuration Wizard, bring the following file from the newly created custom domain into a text editor:

   DOMAIN_HOME/config.xml

   In the preceding line, DOMAIN_HOME represents the path for the directory containing the custom domain. For example, the value of DOMAIN_HOME on Windows is:

   c:\bea\user_projects\mydomain

4. Disable the automatic deployment of the WebLogic Integration application created in the custom domain. To do so, set the Deployed attribute of the WLIapplication element in the config.xml file to false, as in the following example:

<Application Deployed="false" Name="WLIApplication"
Path="<%WLI_HOME%\lib>" TwoPhase="true">

 

---

Creating the Keystores and Inserting the Server Certificates

This section explains how to create the private keystores for storing the server certificates and keys required to use SSL, and the associated CA keystores for CA certificates. For a description of how to add trading partner certificates to the private keystores, see Adding Trading Partner Certificates to the Keystore.

We strongly recommend that you use SSL for trading partner authentication. If you do so, however, you should also configure SSL for each machine in your B2B domain. When you configure SSL, you need to provide a certificate and private key for the local instance of WebLogic Server. This certificate is known as the server certificate. We recommend that you store the server certificate and private key for the local server in the keystore. This section explains how to add the server certificate and private key to the keystore.

During the trading partner authentication and authorization process, the SSL layer in the relevant WebLogic Server instance uses the keystores for obtaining the following:

• The local server's certificate and private key from the private keystore

• The trusted CA certificates from the root CA keystore

For instructions on configuring WebLogic Server to use SSL, see Configuring the SSL Protocol and Mutual Authentication.

Because the WebLogic Integration security service is built on WebLogic Server, only JKS-provider based keystores are currently certified for use with WebLogic Integration. To create the keystores you need for B2B collaborations, you can use either of the following utilities:

• JavaSoft JDK keytool utility

  For information about this utility, see keytool—Key and Certificate Management Tool, published by Sun Microsystems, at the following URL:

  http://java.sun.com/products/jdk/1.2

• WebLogic Server ImportPrivateKey utility

  For information about this utility, see Using the WebLogic Java Utilities in the WebLogic Server Administration Guide, at the following URL:

  http://edoc.bea.com/wls/docs70/adminguide/utils.html

To create the keystore required for your WebLogic Integration B2B domain, complete the following steps:

1. Open a command window.

2. Go to the root directory of the domain. For example, on Windows:

   c:\> cd bea\user_projects\b2bdomain

3. Obtain or create the following files:

   • Server certificates and private keys

     A server certificate and private key is required by SSL for authentication and authorization. You can create a server certificate and private key using the CertGen utility. We recommend that you use certificates and keys created by CertGen for testing purposes only; they are not meant to be used in a production environment. For more information about the CertGen utility, see Using the WebLogic Java Utilities in the WebLogic Server Administration Guide, at the following URL:

     http://download.oracle.com/docs/cd/E13222_01/wls/docs70//adminguide/utils.html

   • Root CA certificate and private key

     If necessary, you can use the CA keystore from the JDK bundled with WebLogic Server. This keystore, cacerts, resides in the following location:

     JAVA_HOME/jre/lib/security

4. Use either the keytool or ImportPrivateKey utility to create the private keystore, inserting the server certificate(s) and private key(s).

   Note: The command for creating a keystore is the same as that for inserting a certificate and key. If the keystore does not exist when you insert a certificate and key, it is created when you enter the command.

   The ImportPrivateKey command for creating a private keystore has the following syntax:

java utils.ImportPrivateKey keystoreName keystorepass alias 
keypass certfile keyfile

Note: When you run the ImportPrivateKey command, make sure that BEA WebLogic Platform is included in your classpath.

The following table describes the arguments available for the ImportPrivateKey utility.

Table 3-1 ImportPrivateKey Command Arguments  

Command Argument	Description
keystoreName	Defines the name of the keystore file. A new keystore is created if one does not exist.
keystorepass	Defines the password needed to open the keystore file.
alias	Defines the name used to look up the certificate and key in the keystore. Note: We recommend you note the strength of the encryption used in the alias: domestic or export.
keypass	Defines the password used to unlock the private key file and to protect the private key in the keystore. If you created the server certificate using CertGen, this is the password with which you created it.
certfile	Defines the name of the certificate associated with the private key
keyfile	Define the name of the file holding the protected private key. Note: We recommend that you include the encryption strength in the name of the keyfile. For example: keyDomestic.pem or keyExport.pem.

 

Execute the ImportPrivateKey or keytool command for each server certificate and key you want to add to the private keystore.

5. Create the root CA keystore. The root CA keystore is created at the time you insert the initial CA certificate (just as it is created when you create the private keystore).

   To create the root CA keystore, run the keytool command with the following arguments:

keytool -import -keystore keystoreName -trustcacerts -alias
aliasName -file cert_file -storepass keystorepw -noprompt

The following table describes the arguments available for the keytool utility.

Table 3-2 keytool Command Arguments  

Command Argument	Description
-import	Reads the certificate or certificate chain with the alias aliasName from the file cert_file, and stores it in the keystore keystoreName.pem.
-keystore keystoreName	Identifies the pathname of the keystore.
-trustcacerts	Specifies the trusted certificates in a file named cacerts, which resides in the JAVA_HOME/jre/lib/security directory.
-alias aliasName	Specifies the alias for the certificate.
-file cert_file	Specifies the file, represented here as cert_file, that contains the certificate for the root CA.
-storepass keystorepw	Specifies the password, represented here as keystorepw, for the root CA keystore.
-noprompt	Disables the keytool utility from prompting for additional command arguments.

 

6. Repeat steps 4 and 5 for each machine in the domain, using the same filenames and relative paths.

   Note: To make sure that SSL authentication and authorization work properly, be sure that you use the same filenames and paths for the keystores, certificates, keys, and so on, on each machine.

7. If you are deploying your B2B domain in a multinode cluster, configure the Node Manager, as explained in Managing Server Availability with Node Manager in Creating and Configuring WebLogic Server Domains, at the following URL:

   http://download.oracle.com/docs/cd/E13222_01/wls/docs70/admin_domain/nodemgr.html

 

---

Configuring the WebLogic Keystore Provider

To configure the WebLogic Keystore provider with the keystores you created in Creating the Keystores and Inserting the Server Certificates, complete the following steps:

1. Start WebLogic Server in the newly-created custom domain. For example, on Windows, choose Start—>BEA WebLogic Platform7.0—>UserProjects—>domain—>servername.

2. Start the WebLogic Server Administration Console, as described in "Starting the WebLogic Server Administration Console" in WebLogic Integration Administration and Design Tools in Starting, Stopping, and Customizing BEA WebLogic Integration.

3. In the navigation pane on the left, choose Security—>Realms—>CompatibilityRealm—>Providers—>Key Stores.

   Figure 3-1 Choosing Keystores in the Navigation Pane

   
    

   The WebLogic Server Administration Console displays a window in which you can configure a new default keystore, as shown in the following figure.

   Figure 3-2 Configuring a New Default Keystore

   
    

4. Click Configure a new Default Key Store.

   The General tab, in which you can configure the keystore, is displayed as shown in the following figure.

   Figure 3-3 General Tab for Configuring a Default Keystore

   
    

5. On the General tab, specify pathnames for the following:

   • The private keystore file

   • The root CA keystore file

6. Click Create.

7. Shut down WebLogic Server and restart it.

 

---

Adding Trading Partner Certificates to the Keystore

To populate the keystore with trading partner certificates, complete the steps described in this section. For complete details about each trading partner certificate, see Configuring Trading Partner Certificates.

Notes: Even if your keystores are already populated with required certificates and private keys, you still need to perform the following tasks to populate the WebLogic Integration repository with the necessary information.

WebLogic Integration does not validate any of the trading partner certificates against a trusted Certificate Authority as you load them into the keystore.

1. Enable automatic deployment of the WebLogic Integration application created in the B2B domain by setting the Deployed attribute of the WLI application element in the config.xml file to true, as in the following example:

   <Application Deployed="true" Name="WLI" Path="<%WLI_HOME%\lib>" TwoPhase="true">

2. Start the B2B Console, as described in "Starting the B2B Console" in WebLogic Integration Administration and Design Tools in Starting, Stopping, and Customizing BEA WebLogic Integration.

This section presents the following procedures for populating the private keystore for B2B collaborations:

• Adding the Certificates and Private Keys for a Local Trading Partner

• Adding the Certificates for a Remote Trading Partner

• Bulk Loading and Importing Certificates into the Keystore

• Removing Certificates and Private Keys from the Keystore

Adding the Certificates and Private Keys for a Local Trading Partner

A local trading partner requires the following certificates and private keys:

• Client certificate and private key

• Encryption certificate and private key

• Signature certificate and private key

To add these certificates and private keys to the private keystore, complete the steps described in this section.

Note: Do not configure a server certificate for a local trading partner. Although the encryption and signature certificates are optional, the client certificate is required if you are using SSL with mutual authentication. For complete details about local trading partner certificates, see Configuring Trading Partner Certificates. For information about using server-side, or one-way authentication, which does not require the use of a client certificate, see Configuring Server-Side Authentication.

1. In the navigation pane on the left, choose B2B—>Trading Partners.

2. Click the name of the local trading partner for whom you are adding certificates. The General configuration tab is displayed.

   Figure 3-4 General Configuration Page for a Local Trading Partner

   
    

3. Select the Certificates tab. The Certificates configuration page is displayed.

   Figure 3-5 Certificates Configuration Page for a Local Trading Partner

   
    

4. Click Create a Certificate Entry. The console displays a page on which you can specify details about the certificate you are adding for your local trading partner.

   Figure 3-6 Creating a Certificate Entry for a Local Trading Partner

   
    

5. For each trading partner certificate, enter the following information:

   • A name or alias for the certificate. If the keystore has already been populated with this certificate, the alias that you specify must match the one used for this certificate's initial entry in the keystore.

   • The certificate type. For a local trading partner, valid types are Client Certificate, Signature Certificate, and Encryption Certificate.

   • The certificate's location. If you are deploying WebLogic Integration on a cluster, the location you specify needs to be the same on each machine.

   • The location of the private key associated with the certificate. If you are deploying WebLogic Integration on a cluster, the location you specify needs to be the same on each machine.

   • The password for the private key. This password is used by the server when it reads the contents of the private key and when it stores the private key in the keystore. The password itself is not stored or retained anywhere in the system. If the keystore has already been populated, the password that you specify must match the one used to store the private key in the keystore.

   Note: When importing a plain-text (or unprotected) private key using the B2B Console, specify the password of the private keystore in the field labeled Private Key Password.

6. Click Add to add the certificate and private key to the WebLogic Integration repository.

7. Select the Save Certificate to Keystore check box to add the certificate and private key to the private keystore.

Adding the Certificates for a Remote Trading Partner

A remote trading partner has the following certificates:

• Client certificate

• Encryption certificate

• Signature certificate

• Server certificate

Note: Do not specify private keys for remote trading partner certificates. Although the encryption and signature certificates are optional, the client and server certificates are required for using mutual authentication with SSL. For complete details about remote trading partner certificates, see Configuring Trading Partner Certificates. For information about using server-side, or one-way authentication, which does not require the use of a client certificate, see Configuring Server-Side Authentication.

To add these certificates to the private keystore, complete the following steps:

1. Start the B2B Console, if necessary.

2. In the navigation pane on the left, choose B2B—>Trading Partners.

3. Click the name of the remote trading partner for whom you are adding certificates. The General configuration tab is displayed.

4. Select the Certificates tab. The Certificates configuration page is displayed.

5. Click the Create a Certificate Entry link. The console displays a page on which you can specify details about the certificate you are adding for your remote trading partner.

   Figure 3-7 Creating a Certificate Entry for a Remote Trading Partner

   
    

6. Enter the name, location, and type of each certificate you are adding for the remote trading partner.

7. Click Add to add the certificate to the WebLogic Integration repository.

8. Select the check box labeled Save Certificate to Keystore to add the certificate to the private keystore.

Bulk Loading and Importing Certificates into the Keystore

When you use the Bulk Loader utility (from either the B2B Console or the command line) to configure certificates in the WebLogic Integration repository, trading partner certificates are not imported into the keystore. However, the repository contains configuration information about the certificates so that it can import the certificates into the keystore during startup of the B2B engine.

Before the B2B engine can import trading partner certificates into the keystore, you must have automatic migration enabled in the startWeblogic script. To enable automatic migration, complete the following steps:

1. Shut down the WebLogic Server instance in the B2B domain created in Creating the Domain. You can do so by executing the stopWeblogic script, which is located in the B2B domain's root directory. For example:

   • Windows:

     cd DOMAIN_HOME
     stopWeblogic.cmd

   • UNIX:

     cd DOMAIN_HOME
     stopWebLogic.sh

   In the preceding examples, DOMAIN_HOME is the root directory of the B2B domain.

2. Add the Java system property wli.keystore.automigrate to the Java command line in the startWeblogic script, and set the property value to true, as shown in the following listing. The wli.keystore.automigrate property is shown in bold.

%JAVA_HOME%\bin\java %DB_JVMARGS% -Xmx256m -classpath %WLISERVERCP%
-Dbea.home=%BEA_HOME% -Dwli.bpm.server.evaluator.supportsNull=false
-Dweblogic.Domain=mydomain -Dweblogic.Name=myserver
-Dweblogic.management.username= -Dweblogic.management.password=
-Dweblogic.ProductionModeEnabled=true -Dweblogic.management.discover=false
-Djava.security.policy==%WL_HOME%\lib\weblogic.policy weblogic.Server
-Dwli.keystore.automigrate=true

3. Save your changes.

When WebLogic Server is restarted in the domain, the certificates and keys are imported.

Removing Certificates and Private Keys from the Keystore

When you remove a certificate, and, if applicable, a private key, using the B2B Console, references to that certificate and private key are removed from the WebLogic Integration repository. You can also remove the certificates and their associated keys from the private keystore at the same time.

To remove a certificate, complete the following steps:

1. Start the B2B Console, if necessary.

2. In the navigation pane on the left, choose B2B—>Trading Partners.

3. Click the name of the trading partner for whom you are removing a certificate and private key. The General configuration tab is displayed.

4. Select the Certificates tab. The Certificates configuration page is displayed.

   Figure 3-8 Removing a Certificate from the Keystore

   
    

5. Choose the type of certificate you want to remove.

6. Select the alias for the certificate in the list box.

7. Click Remove to remove the certificate and, if applicable, private key, from the WebLogic Integration repository.

8. To remove the certificate and private key from the keystore, as well as from the repository, make sure the box labeled Remove Certificate from Keystore is checked, and click Remove.

 

---

Configuring the Domain to Use the Keystore

To configure your B2B domain to use the keystores you have created, you need to modify the startWeblogic script that resides in the root directory for your domain. To modify this script, complete the following steps:

1. Go to the root directory for the domain, as shown in the following examples.

   • Windows:

     c:\bea\user_projects\domain

   • UNIX:

     /usr/bin/bea/user_projects/domain

   In the preceding pathnames, domain represents the name of your B2B domain.

2. In a text editor, open the startWebLogic.cmd script (for Windows) or the startWebLogic.sh script (for UNIX).

3. Locate the line on which the java command is issued to start WebLogic Server, as shown in the following example.

%JAVA_HOME%\bin\java %DB_JVMARGS% -Xmx256m -classpath %WLISERVERCP%
-Dbea.home=%BEA_HOME% -Dwli.bpm.server.evaluator.supportsNull=false
-Dweblogic.Domain=mydomain -Dweblogic.Name=myserver
-Dweblogic.management.username= -Dweblogic.management.password=
-Dweblogic.ProductionModeEnabled=true -Dweblogic.management.discover=false
-Djava.security.policy==%WL_HOME%\lib\weblogic.policy weblogic.Server

4. To this java command, add the system property that specifies the private key passwords for the signature and message encryption certificates, using the following syntax:

   -DKey.certificate-name.password=key_password * 

   In the preceding syntax:

   • certificate-name represents the name or alias of the certificate that is added to the keystore in Adding Trading Partner Certificates to the Keystore.

   • key_password represents the private key password specified for the certificate when the certificate is added to the keystore. Note that you do not need to specify a password for plain-text private keys; the B2B engine uses the password of the keystore to retrieve such private keys.

5. Also to this java command, add the system properties that specify the passwords for the private keystore and the root CA keystore, using the following syntax:

   -Dwli.privateKeystore.password=keystore_pass
   -Dwli.caKeystore.password=caKeystore_pass

   In the preceding syntax:

   • privateKeystore represents the private keystore created as described in Creating the Keystores and Inserting the Server Certificates.

   • keystore_pass represents the password for the private keystore.

   • caKeystore represents the root CA keystore, created as described in Creating the Keystores and Inserting the Server Certificates.

   • caKeystore_pass represents the password for the root CA keystore.

Note: We recommend that you set passwords in environment variables, rather than hard-coding the passwords into scripts such as startWeblogic. When environment variables are used, scripts can obtain the values for passwords from the environments in which the scripts run.

 

---

Using the Keystore in a Multinode Cluster

If you are deploying your B2B domain on a multinode cluster, you need to do the following:

1. Replicate the private and root CA keystores on each machine in the cluster. These keystores must be in the same relative location on every machine.

2. Make sure that the server certificate is stored in the same relative location on every machine. To meet the requirements of SSL support, the server certificate location must be identified in the domain's config.xml file.

3. Configure the private and root CA keystores with the WebLogic Keystore provider on the administration server, as described in Configuring the WebLogic Keystore Provider.

4. Make sure that the server certificate is configured on the administration server, as described in Configuring the SSL Protocol and Mutual Authentication.

As each managed server in the domain is started, with the help of the administration server, the WebLogic Keystore provider configuration is automatically propagated to it.

For more information about managing B2B security in a multinode cluster, see Deploying BEA WebLogic Integration Solutions.