Configuring WebLogics SSL

2017-11-03 09:05:02

Configuring WebLogic s SSL

There are three steps to configuring WebLogic's SSL:

You need to establish the server's identity, by acquiring a private key and digital certificate for the server. You can either use demonstration keys and certificates supplied with WebLogic or generate your own. Alternatively, you can contact a reputed CA for production-quality certificates. You also need to establish trust for the server. This requires you to configure WebLogic with a keystore that holds the certificates of all the CAs that the server is willing to trust.

Once you obtain the server's key and certificate, you need to store them in a keystore[1] before they can be made available to WebLogic.

[1] WebLogic 7.0 requires that the digital certificate remain in a text file.

Finally, you need to fire up the Administration Console and point the server to the appropriate keystore files.

Once you configure the required SSL resources for WebLogic, you need to enable the SSL port. By default, SSL is not enabled for WebLogic because it consumes additional CPU resources when it has to service SSL connection requests. Thus, before you connect to the SSL-enabled port, you must weigh the benefits of secure TCP connections over the overhead of additional CPU processing. Yet secure SSL communication is mandatory in many scenarios. For instance, as we saw in Chapter 13, the Administration Channel requires you to configure SSL support for all servers in the WebLogic domain. In a production environment, SSL connections are essential to protecting access to sensitive application services.

Most SSL configuration takes place on a per-server basis. The Configuration/General and Configuration/Keystores & SSL tabs are the most important when configuring SSL in WebLogic 8.1. WebLogic 7.0 users should use the Connections/SSL and Connections/SSL Ports tabs. After configuring the SSL resources needed by the server, you must ensure that the SSL Listen Port Enabled flag is selected and a suitable port number is specified.

To help assimilate these concepts, we will end this section with examples on how to set up one-way and two-way SSL configurations.

16.2.1 Obtaining Keys and Certificates

Your WebLogic distribution comes shipped with a set of "demonstration" keys and certificates. These can be used while you explore WebLogic's SSL configuration options, but should not be used in a production setting. The demonstration keys and certificates are not signed by a well-known CA. In fact, WebLogic provides you with a self-signed CA certificate that you can use to produce your own keys and certificates. Any demonstration certificate generated in this way is signed by a CA called CertGenCAB.

For production-quality SSL, you should use a certificate signed by a well-known CA, such as Entrust.net or Verisign. For this, you need to send a formal CSR to the CA. WebLogic supplies tools with which to create your own certificates and generate these CSRs.

16.2.1.1 Demonstration keys and certificates

The demonstration keys and certificates are distributed differently in WebLogic 7.0 and WebLogic 8.1. In WebLogic 7.0, they are located in the WL_HOMEserverlib directory. When you create a WebLogic domain using the Domain Configuration Wizard, they are copied into the root directory of the new domain. The files democert.pem and demokey.pem provide the export-strength certificate and private key, while the files democert1024.pem and demokey1024.pem provide the domestic-strength certificate and private key. In WebLogic 8.1, the demonstration key and certificate already are deposited in a keystore located in the WL_HOMEserverlib directory, called DemoIdentity.jks. This doesn't mean that you won't need to manipulate key and certificate files, though.

WebLogic 7.0 is also configured with a default keystore, the cacerts file, which holds the PEM-encoded certificates of all trusted CAs. This keystore is located in the WL_HOMEserverlib directory. In WebLogic 8.1, the default keystore that holds the list of trusted CA certificates is now called DemoTrust.jks and is located in the same directory. In fact, this keystore, which we will call the trust keystore, holds the certificate for the CA called CertGenCAB, which is the same CA that signs the demonstration certificate. Thus, the default trust keystore and the demonstration certificate/key work together. For instance, if a Node Manager needs to communicate with a WebLogic instance using a demonstration certificate, WebLogic can validate only the Node Manager's certificate, provided it can trust the CA that signed the demonstration certificate. This will be possible only if you set up WebLogic SSL using the default trust keystore.

Refer to the sidebar keytool Managing Keystores in this chapter for more information on how to use the keytool utility to manipulate a keystore.

16.2.1.2 The CertGen utility

You can use WebLogic's CertGen utility to generate your own demonstration private keys and certificates, signed by CertGenCAB. The CertgenCA.der and CertGenCAKey.der files, located in the WL_HOMEserverlib directory, represent the digital certificate and the private key, respectively, of the demonstration CA trusted by WebLogic. You can issue the following command to generate a new private key and certificate:

java utils.CertGen keypass certfile keyfile [export] [hostname]

Here, keypass is used to specify a password for the private key, while the certfile and keyfile arguments let you specify the names of the files used to store the digital certificate and private key. The CertGen utility generates domestic-strength certificates by default. If the optional export flag is supplied, the tool will generate export-strength certificates. The hostname argument lets you specify the name of the machine for which the certificate will be generated. If the certificate undergoes hostname verification, the hostname attributed to the certificate will be extracted from this field.

If you wish to enable hostname verification, you must generate a separate private key and digital certificate for each server instance that needs to accept SSL connections.

Note that if you do not specify a hostname, the CertGen utility invokes the InetAddress.getLocalHost( ).getHostname( ) method to determine the subject's common name for the certificate. The getHostName( ) method is somewhat platform-dependent because it may return a fully qualified domain name on some platforms, and return a short hostname on other platforms. You need to ensure that the hostname returned by this method matches the subject's common name in the certificate. Otherwise, the certificate will be invalidated because the URL doesn't match the domain name used in the certificate's subject. Later, we'll see how you can configure WebLogic to bypass the server name check and utilize your own hostname verifiers.

CertGen generates two versions of the certificate and private key. It creates two .der files (certfile.der and keyfile.der) and two .pem files (certfile.pem and keyfile.pem). You can use either pair when configuring SSL for WebLogic Server. You also can view the contents of the .der files in your browser and inspect the details of the new certificate. Refer to the sidebar Certificate Formats in this chapter for more information about the certificate formats recognized by WebLogic.

Certificate Formats

WebLogic groks certificates that are in either the .pem or .der format. The .der format is binary and is used to hold only a single certificate. The .pem format is textual; you can recognize a certificate in this format because it looks something like this:

----BEGIN CERTIFICATE---- ... ----END CERTIFICATE----

The PEM format lets you store multiple certificates in the same file. This is ideal for a certificate chain in which a list of certificates needs to be stored in the same file. This list is organized so that each certificate is followed by its CA's public certificate. The last certificate in the list is a self-signed certificate from the root CA. Each certificate in this chain then can be stored in a single .pem file, in this particular order.

Note that private keys must be stored in the PKCS#5/PKCS#8 PEM format. Some tools such as OpenSSL generate certificates with additional text before the "----BEGIN CERTIFICATE----" line. In such cases, you need to remove the text before this line to obtain a valid certificate.

If you have a .der certificate and you need a .pem-style equivalent for example, because you need to add it to a certificate chain you can use WebLogic's der2pem utility. Here's how you would invoke the der2pem tool to handle the conversion:

java utils.der2pem derFile [headerFile] [footerFile]

By default, the certificate header and footer adhere to the standard .pem format. However, if you are creating a key, you need to specify the locations of two separate files that hold the certificate header and footer:

### contents of mypemheader: -----BEGIN RSA PRIVATE KEY----- ### contents of mypemfooter: -----END RSA PRIVATE KEY-----

Make sure to append a newline character at the end of the line in the header and footer files.

Microsoft also can act as a CA, but issues its certificates in a different format: p7b. Certificates issued by Microsoft can be recognized by WebLogic provided you first convert them to the .pem format. You can accomplish this by double-clicking the certificate file in Windows Explorer, and then selecting the Certificates/Certificate Export option from the pop-up window to export the certificate as a Base 64-encoded certificate. This resulting certificate file then can be used as a PEM certificate.

16.2.1.3 The Certificate Request Generator tool

Until now, you've had to persevere with private keys and digital certificates that are not fit for a production environment. Fortunately, WebLogic's Certificate Request Generator tool eases the task of obtaining a production-quality certificate for the private key. It lets you generate a CSR that can be submitted to any trusted CA. A trusted CA then will authenticate the CSR (usually offline) before issuing a signed digital certificate.

The Certificate Request Generator tool, which runs as a servlet on the Administration Server, collects all the necessary data and then generates a private key and certificate request file. Once the trusted CA has authenticated your details, it will return a signed certificate verifying your public key. In some instances, the CA may return a certificate chain, whereby each certificate in the chain authenticates the public key of the signer of the previous certificate in the chain.

You don't necessarily need to use the private key generated by the request generator tool. You can use any other private key as well, so long as it adheres to the PKCS#5/PKCS#8 PEM format.

Because the Certificate Request Generator tool runs as a servlet on WebLogic, you need to first deploy the web application that packages the servlet. You can accomplish this by copying the certificate.war file located in the WL_HOMEserverlib directory to the applications directory under the domain's root directory. The web application will be deployed successfully once you target the web application to the Administration Server.

Now you can invoke the Certificate Request Generator tool from your browser by navigating to the following URL: http://adminserver:port/certificate/. Use the login credentials of WebLogic's administration user account to gain entry. You then need to fill out a form with all the necessary information required by the digital certificate. Most importantly, you must specify the fully qualified hostname that clients will use to access the server. The tool then generates three files:

hostname-key.der

This represents the Base 64-encoded server's private key. Retain this private key for subsequent SSL configuration.

hostname-request.dem

This represents the CSR in binary format.

hostname-request.pem

This represents a .pem-formatted CSR file that must be submitted to a CA. It holds the same data as the .der file but is encoded in ASCII. You can copy and paste the contents of this CSR file into an HTML form or an email.

The servlet can also submit the request file to a CA either VeriSign or Baltimore Technologies. You don't have to use these CAs you could quite easily email the .pem file to any preferred CA. If you do submit the CSR manually, make sure that you select BEA WebLogic Server as the Server type. The trusted CA can then ensure that the signed certificate is compatible with WebLogic Server.

16.2.2 Storing Private Keys and Certificates

At this point, we assume that you have obtained the server's identity (private key and digital certificate) and the certificates of a number of CAs that you trust. The final task before you can configure WebLogic's SSL is to place these items in the appropriate keystores. For this, you need to understand how to create and populate a keystore with private keys and trusted CA certificates. WebLogic's ImportPrivateKey utility can be used to import private keys and trusted CA certificates into a keystore. For instance, the following command shows how to import an existing public/private key pair into the default keystore:

java utils.ImportPrivateKey myIdentity.jks mykeystorepass myalias mykeypass mycert.pem mykey.pem

In this case, we've imported the .pem-encoded private key and digital certificate into the keystore named myIdentity.jks, and created an alias, myalias, that references the new entry in the keystore. You could have easily imported .der files holding the private key and digital certificate. Remember, you need to specify a password both for the keystore itself and for the key entry within the keystore. Refer to the sidebar keytool Managing Keystores in this chapter for more information on the structure of a keystore.

Trusted CA certificates are essential when WebLogic needs to validate any incoming certificates. The following command shows how to use the keytool utility to load a trusted CA certificate into a keystore:

keytool -import -trustcacerts -alias arbuniquealias -file y:serverlibcertgenca.der -keystore myTrust.jks -storepass 12341234

Remember, all private key entries in a keystore are accessed via their unique alias. Even though WebLogic never uses the alias to access a trusted CA certificate from the keystore, you still need to specify the alias when using keytool to import a trusted CA certificate into a keystore.

keytool Managing Keystores

Your JDK installation comes equipped with the keytool utility for managing a keystore of private keys, digital certificates, and trusted CA certificates. The WL_HOMEserverlibcacerts file is an example of a JKS keystore that holds the certificates of all root CAs trusted by WebLogic.

A keystore can hold two kinds of entries: a key entry that holds the private key and the associated certificate, or a certificate entry that holds a trusted CA certificate. Each keystore entry may be accessed via a unique, case-insensitive alias. The entire keystore is protected with its own password, and each entry in the keystore is protected by its own password. In this way, the keystore provides a secure, tamper-proof repository for private keys, certificate chains, and trusted CA certificates.

The keytool utility is the standard way to manipulate entries within a keystore. For instance, the keytool utility can generate a private key and a self-signed certificate, and then create a keystore entry using this public/private key pair. Here a single-element certificate chain consisting of a self-signed certificate is linked to the private key. The keytool utility can also create a CSR, which then can be submitted to any trusted CA. The new certificate you procure can replace the existing self-signed certificate in the keystore. If you use the keytool utility to load any trusted CA certificates into the keystore, ensure that the trusted CA certificates are genuine.

To list all the entries in a keystore, use the following command:

keytool -list -keystore mykeystore.jks

If you run this command on the cacerts file, it lists all the trusted CA certificates, including certificates of the demonstration CAs. To create a new keystore, use the following command:

keytool -genkey -keystore mykeystore.jks -storepass mykeystorepass

To generate a new private key and a matching self-signed certificate, use the following command:

keytool -alias myalias -genkey -keypass mykeypass -keystore mykeystore.jks -storepass mykeystorepass

To replace a self-signed certificate with a production-quality certificate or to import a trusted CA certificate into a keystore, run the following command:

keytool -import -alias myalias -file mycert.pem -keypass mykeypss -keystore mykeystore.jks -storepass mykeystorepass

If you intend to import a trusted CA certificate, no existing entry for myalias should be in the keystore. Otherwise, the keytool utility simply replaces the self-signed certificate for the private key with the specified certificate file. Refer to your JDK documentation for more information on how to use the keytool utility to manage keystores.

16.2.3 Configuring SSL for WebLogic 8.1

WebLogic 8.1 requires you to set up a keystore to hold the server's identity (private key and public certificate), as well as a keystore to hold all the trusted CA certificates. Once you prepare the identity and trust keystores, you simply need to point WebLogic to the location of these keystores, specify the alias for the private key, and then enable SSL.

16.2.3.1 Configuring the identity and trust keystores

You can set up the keystores for a server by selecting the server node from the left frame of the Administration Console and then navigating to the Configuration/Keystores & SSL tab. Here, you can select the Change option next to the Keystore Configuration title to specify the locations of the keystores. You will be presented with four options for the identity and trust keystores:

Demo Identity and Demo Trust

Instructs WebLogic to use the demonstration identity and trust keystores, DemoIdentity.jks and DemoTrust.jks, which are installed in the WL_HOMEserverlib directory. In addition, the server uses the alias DemoIdentity to access the private key and digital certificate stored in the identity keystore.

Custom Identity and Java Standard Trust

Lets you configure the server to use your own identity keystore, and the standard list of trusted CA certificates that are provided by your JDK i.e., JAVA_HOMEjrelibsecuritycacerts. When you configure a custom identity keystore for the server, you must supply the name of the keystore file, the type of the keystore (for example, jks), and the pass phrase that should be used to access the keystore.

Custom Identity and Custom Trust

Lets you configure the server to use your own identity and trust keystores. For each keystore, you will have to supply the name of the keystore file, the type of the keystore (for example, jks), and the pass phrase that should be used to access the keystore.

Custom Identity and Command Line Trust

Lets you set up the server to use your own identity keystore only, and assumes that you will specify the location of the trust keystore from the command line.

Use the -Dweblogic.security.SSL.trustedCAKeyStore option to set up the server's trust keystore from the command line:

java -Dweblogic.security.SSL.trustedCAKeyStore=c: rustedStore.jks ... weblogic.Server

16.2.3.2 Setting up the server identity

Once you've configured the identity keystore for WebLogic, you still need to associate the server with its private key and digital certificate. By default, when you configure WebLogic with the demonstration identity keystore (DemoIdentity.jks), it uses the alias DemoIdentity to access the private key and public certificate. For a custom identity keystore, however, you must supply the alias and pass phrase assigned to the key entry within the keystore. Only then can WebLogic access the private key and certificate from the identity keystore.

Although the server's identity is established when you configure the keystores for the server, you can change the server's identity from the Configuration/Keystores & SSL tab as well. Simply choose the Change option next to the SSL Configuration title to specify a new alias and pass phrase for an entry within the keystore.

For backward-compatibility, this option also lets you configure a file-based server identity, whereby you can supply the names of the files that hold the private key and public certificate.

16.2.3.3 Enabling SSL

The final step in the server's SSL configuration is to enable SSL. Select the Configuration/General tab and tick the SSL Listen Port Enabled option. In addition, choose a suitable value for the SSL Listen Port option to determine the server's SSL port. After a server restart, you should have a fully operational SSL listen port.

16.2.4 Configuring SSL for WebLogic 7.0

Once you've obtained the server's identity (private key and public certificate) and a keystore that holds all trusted CA certificates, you need to point the server to the location of the private key, the public certificate, and the trust keystore, and then enable SSL on the desired ports. As mentioned earlier, any public certificate used to configure SSL on WebLogic 7.0 always must be stored in a file. However, the server's private key and trusted CA certificates can be stored either in a file or in a JKS keystore. In the following section, we look at how to configure WebLogic with keystores that hold the private keys and trusted CA certificates (which we recommend you do). If you need to store the private key and trusted CA certificates in plain files instead, you should skip ahead to Section 16.2.4.3.

16.2.4.1 Configuring a Keystore Provider

Most of the SSL configuration options are available on the Connections/SSL tab for the selected server. Select the Configure Keystore Providers link to equip WebLogic with keystores that hold the server's private key and trusted CA certificates.

A Keystore Provider provides domain-wide access to JKS keystores for the private keys and trusted CA certificates. You can access the Keystore Provider either from the Configure Keystore Providers option on the SSL tab or from under the Security/Realms/Providers/Keystores node in the left frame of the Administration Console. By default, a WebLogic domain is configured with a Keystore Provider called DefaultKeyStore. On the General tab, you then can adjust the following SSL attributes to allow WebLogic to access the keystores holding the private keys and trusted CA certificates:

Private Key Store Location

Use this option to specify the location of the keystore that holds the private key. You may specify a location relative to the domain's root directory. By default, the Keystore Provider is configured to use a keystore named wlDefaultKeyStore.jks.

Private Key Store Pass Phrase

Use this option to specify the password you assigned to the keystore.

Root CA Key Store Location

Use this option to specify the location of the keystore that holds the certificates of CAs trusted by WebLogic. You don't need to configure this attribute if the same keystore is used to store both the private keys and trusted CA certificates.

Root CA Key Store Pass Phrase

Use this option to specify the password (if any) assigned to the keystore holding the trusted CA certificates.

Because the Keystore Provider is configured for the entire domain, the keystore file(s) must be placed in the same location for all servers in the domain. Otherwise, the server instance will be unable to locate the configured keystore.

You can use the -Dweblogic.security.SSL.trustedCAKeyStore option to configure the trust keystore from the command line when starting up the server:

java -Dweblogic.security.SSL.trustedCAKeyStore=c: rustedStore.jks ... weblogic.Server

Here, c: rustedStore.jks refers to the location of the keystore holding your trusted CA certificates. In fact, if you create a WebLogic domain using the Domain Configuration Wizard, the startWebLogic scripts also configures WebLogic to use the default keystore for the trusted CA certificates:

-Dweblogic.security.SSL.trustedCAKeyStore=WL_HOMEserverlibcacerts

Remember, you need to configure the Keystore Provider only if you do not intend to store the private keys and trusted CA certificates in ordinary files.

A keystore for trusted CA certificates is particularly important if you intend to configure two-way SSL for the server. Because you can specify the keystore for the trusted CA certificates in several ways, WebLogic adopts the following sequence when looking for a trusted CA that can vouch for the authenticity of a client's certificate:

If you used the weblogic.security.SSL.trustedCAKeyStore option from the command line when starting up WebLogic Server, it looks in the keystore specified by this option. By default, WebLogic's startup scripts use the trusted CA certificates in the WL_HOMEserverlibcacerts keystore.

If you didn't use this command-line option to specify the keystore location, WebLogic uses the Root CA Key Store Location and Root CA Key Store Pass Phrase attributes of the configured Keystore Provider to access the keystore for the trusted CA certificates. If both private keys and trusted CA certificates are stored in the same keystore, WebLogic uses the Primary Key Store Location and Primary Key Store Pass Phrase attributes to access the keystore.

If you haven't configured a Keystore Provider for the domain, WebLogic has no choice but to inspect the default keystore file that is shipped with your JDK i.e., the JAVA_HOMEjrelibsecuritycacerts keystore.

Remember, a Keystore Provider offers domain-wide access to keystores that hold the private keys and trusted CA certificates. A keystore, on the other hand, is configured on a per-machine basis. Thus, if your domain has multiple security realms or multiple servers running on the same machine, they all can be configured to use the same keystore.

16.2.4.2 Setting up the server identity

Once you configure the Keystore Provider, you need to return to the Connections/SSL tab for the selected server. Here you must supply values for the following SSL attributes in order to complete the SSL configuration for the server's identity:

Server Private Key Alias

Use this option to specify the alias for the server's private key in the keystore.

Server Private Key Passphrase

Use this option to specify the password that was used to protect the server's private key.

Server Certificate File Name

Use this attribute to configure the location of the server's digital certificate (e.g., democert.pem). Remember, WebLogic insists that you store the server's digital certificate in an ordinary file (and not in a keystore).

WebLogic then can use the configured Keystore Provider to access the keystore holding the server's private key. It can also use the configured alias and pass phrase to look up the private key from the keystore.

16.2.4.3 Using plain files for the private key and trusted CA certificates

If you intend to store the private key and trusted CA certificates in ordinary files, you need to configure the following SSL attributes:

Server Key File Name

Use this setting to specify the location of the server's private key (e.g., democert1024.pem). If the private key has been protected via a password, you also must specify the weblogic.management.pkpassword argument from the command line when starting up WebLogic.

Trusted CA File Name

Use this attribute to specify the name of the file that holds the PEM-encoded certificates of all trusted CAs. (e.g., trusted-ca.pem).

Once again, these SSL attributes are available from within the Connections/SSL tab, after selecting the desired server from the left pane of the Administration Console.

These SSL options, which let you refer to keys and certificates stored in ordinary files, are deprecated and exist only for compatibility with previous versions. Even though they provide a quick and easy way to set up WebLogic SSL for instance, when you need to use demonstration keys and certificates during development/testing we recommend that you store the private keys and trusted CA certificates in keystores.

16.2.4.4 Enabling SSL

The final step in the configuration is to enable SSL. Select the Connections/SSL Ports tab and tick the Enable SSL Listen Port option. In addition, choose a suitable value for the SSL Listen Port option to determine the server's SSL port. After a server restart, you should have a fully operational SSL listen port.

16.2.5 Other SSL Configuration Issues

This section looks at other issues of WebLogic's SSL setup, including how to configure two-way SSL, disable hostname verification, and choose the appropriate level of certificate validation. These configuration issues are available from the Administration Console for the selected server, under the Advanced options of the Keystores & SSL tab in WebLogic 8.1, and in the Connections/SSL tab in WebLogic 7.0.

16.2.5.1 Two-way SSL

In WebLogic 8.1, you can use the "Two way client Certificate behavior" option[2] under the Advanced options in the Keystores & SSL tab, to configure two-way SSL for the server. The default value for this setting is "Client Certificates not requested," which means that by default, two-way SSL is not enabled for the server. Thus, WebLogic does not request a client to present a certificate when it establishes an SSL connection. However, you can enable two-way SSL by choosing from two other possible values for the "Two way client Certificate behavior" setting.

[2] In WebLogic 7.0, the Connection/ SSL tab provides analogous settings for configuring two-way SSL i.e., the Client Certificate Enforced and Client Certificate Requested But Not Enforced flags. By default, both flags are disabled, which means that two-way SSL is disabled for the server.

Client Certificates requested and enforced

If you select this option, all clients are forced to authenticate themselves to the server. This means that the client must also present its public certificate to the server when initiating an SSL connection. If the client fails to do so, the SSL connection request is refused.

Client Certificates requested but not enforced

If you select this option, WebLogic still requests the client for its digital certificate. However, unlike the previous case, WebLogic does not terminate the connection if the client fails to furnish a certificate and decides to remain anonymous. However, if the client does submit a certificate as proof of its identity, and the server is unable to validate the certificate for some reason, the SSL connection request is refused.

Remember, if you do enable two-way SSL for the server, you must also equip the server with a trust keystore.

16.2.5.2 Hostname verification

WebLogic performs hostname verification whenever it needs to validate a certificate. A hostname verifier compares the hostname within the certificate's SubjectDN with the hostname of the other party that is involved in the SSL connection. If the two hostnames do not match, the SSL connection is aborted. This is the behavior of the default hostname verifier installed with WebLogic. A WebLogic server will need to validate a certificate whenever it is acting as an SSL client during an SSL handshake. This will happen, for example, whenever one WebLogic instance communicates with another using two-way SSL.

In WebLogic 8.1, you can use the Hostname Verification setting within the Advanced options of the Keystores & SSL tab to adjust the hostname verification behavior. The default value for this setting is BEA Hostname Verifier, which means that the hostname verifier works in the way that we've just described. If you choose None as the value for this setting, you disable hostname verification altogether. This means WebLogic does not verify whether the hostname URL matches the hostname embedded within the SubjectDN field of the digital certificate sent back by the other party. Hostname verification should be disabled only during development and testing for instance, when clients access your server using its internal IP address instead of its URL in the certificate. You can disable hostname verification from the command line as well, by setting the following property when you run an SSL client:

java -Dweblogic.security.SSL.ignoreHostnameVerification=true ... com.oreilly.wlguide.sslclients.MyClientA

If you need to replace the default hostname verifier with your own custom hostname verifier, choose the Custom Hostname Verifier option as the value of the Hostname Verifier setting.[3] In this case, you must specify the fully qualified name of a Java class that implements the weblogic.security.SSL.HostnameVerifier interface. You can specify the custom hostname verifier from the command line as well, by setting the following option when running an SSL client:

[3] In WebLogic 7.0, the Connections/SSL tab provides settings that let you turn off hostname verification for the selected server, and also override the default behavior with a custom hostname verifier.

java -Dweblogic.security.SSL.HostnameVerifier=classname ... com.oreilly.wlguide.sslclients.MyClientA

A custom hostname verifier is ideal if you need to modify the default behavior in any way. To prevent man-in-the-middle attacks, we recommend that you do not disable hostname verification in a production environment. When enabling hostname verification, you should ensure that all certificates use the correct hostnames and not IP addresses, and that all URLs use hostnames rather than IP addresses.

16.2.5.3 Certificate validation options

A trusted CA may issue a certificate chain, starting with the digital certificate that holds the public key, followed by the public certificate of the CA that signed the certificate before it, and so on, ending with a self-signed certificate from a trusted CA. Previous versions of WebLogic did not properly validate whether a CA issued each certificate in the chain. As a result, WebLogic was unable to detect certificates in a chain that potentially were signed by parties using their own personal certificate. The current WebLogic release requires that each certificate in the chain have its Basic Constraint property set to CA, thereby ensuring that all certificates in the chain are issued by a CA. By default, any certificate in the chain that doesn't meet this criterion is rejected. In fact, the IETF RFC 2459 standard that the industry is converging on goes a step further and asks that the extension be marked "critical" as well.

You can choose from several certificate validation levels. You can adjust the level of certificate validation via the command-line option specified when starting up WebLogic Server:

java -Dweblogic.security.SSL.enforceConstraints=option ... weblogic.Server

WebLogic supports the following levels of certificate validation:

strong or true

Use this option to ensure that each certificate in the chain has its Basic Constraint property set to CA. WebLogic uses this level of certificate validation by default.

strict

Use this option to enforce the IETF RFC 2459 standard. This level provides the most secure certificate validation strategy, and ensures that the Basic Constraint extension is set to CA and marked as "critical." This option isn't configured to be the default because many CA certificates currently don't adhere to the standard.

off

Use this option to disable all certificate validation. We don't recommend that you turn off certificate validations in a production environment.

If possible, set the certificate validation level to strict, as it offers maximum security. WebLogic also provides a utility for checking whether a certificate chain will be rejected by the server. The utility can take as an argument either a Java keystore or a PEM-encoded file:

java utils.ValidateCertChain -pem mycertfile.pem

The tool will notify you of any CA certificates in the chain that are not valid. In case the certificate chain is invalid, you can either adjust the validation constraints, or more beneficially, apply for CA certificates that do adhere to the standard.

16.2.5.4 SSL debugging

SSL debugging provides you with more detailed information about the events that transpire during an SSL handshake. You can enable SSL debug tracing for applications involved in SSL communication. These debugging options can be supplied from the command line before starting WebLogic Server:

-Dssl.debug=true -Dweblogic.StdoutDebugEnabled=true

You can configure the same command-line options for a Java client using WebLogic's SSL implementation.

16.2.5.5 Export key lifespan and SSL login timeout

WebLogic lets you adjust the values of several other miscellaneous SSL configuration options. These options assume default values that you don't generally need to change.

Export Key Lifespan

Use this attribute to specify the number of times the server can use an exportable key between a domestic server and an exportable client before generating a new key. The more secure you want the server to be, the fewer times the key should be used before generating a new key.

SSL Login Timeout

Use this attribute to set the maximum duration allowed for a login sequence. The login sequence times out when its duration exceeds the value of this setting. By default, the SSL login sequence times out after 25 seconds. A value of 0 disables the SSL login timeout.

If your clients have a high network latency, perhaps due to a congested pipe leading into your server, you may want to raise this timeout value. The timeout option is available in the Advanced section of the network channel Configuration screen in WebLogic 8.1. In WebLogic 7.0, use the Connections/Tuning tab.

16.2.5.6 Using SSL in a cluster

Because SSL configuration takes place on a server-by-server basis, you must ensure that each server has its own copy of the private key and digital certificate. Likewise, if you've configured a Keystore Provider, you must ensure the keystores are placed in the same locations on each server. If you've configured Node Managers to run on the different machines in the domain, you also must ensure that each Node Manager has access to the relevant SSL resources.

16.2.6 SSL Configuration Scenarios

As an example, we will use CertGen to create our own private key and digital certificate, and then use these SSL resources to configure the Administration Server to use a domain-wide administration port. As explained in Chapter 13, this creates a dedicated administration channel, which always requires the use of SSL. Then, we extend this setup by configuring two-way SSL. To access the Administration Console under these conditions, you will have to configure your browser with a certificate that it can present to WebLogic.

16.2.6.1 One-way SSL

Let's start by creating the digital certificate and private key. You can accomplish this by invoking the CertGen utility:

java utils.CertGen mypassword mycertfile mykeyfile export

This generates an export-strength digital certificate mycertfile.pem, and a private key mykeyfile.pem. Of course, if you received your certificate and private key from a proper CA, you can skip this step and use your production items instead. Now, import the private key into a JKS keystore. The following command shows how to load the private key in a new keystore file myIdentityStore.jks:

java utils.ImportPrivateKey myIdentityStore.jks mykeystorepass myalias mypassword mycertfile.pem mykeyfile.pem

Notice how we've assigned a pass phrase to the keystore, the alias myalias for the private key, and a pass phrase to protect the key entry.

Now you need to configure WebLogic to use this keystore. Select the server from the left pane of the Administration Console, and then select the Configuration/Keystores & SSL tab. Select the Change option under the Keystore Configuration. Here you can simply choose the "Custom Identity and Java Standard Trust" option. Set the keystore filename to myIdentityStore.jks, the keystore type to jks, and the pass phrase to mykeystorepass. Finally, set the private key alias to myalias, and the key pass phrase to mypassword.

Now, in order to enable the domain wide administration port, click the top-level Domain node in the left pane of the Administration Console and then tick the Enable Administration Port option. The domain-wide administration port defaults to port 9002.

This completes the SSL configuration for the Administration Server, so you can reboot the Administration Server after applying all the changes to the server's setup. Once the Administration Server is up and running, you can access the Administration Console by pointing a browser to the following URL: https://hostname:9002/console. Because you've forced all the administration traffic over the SSL-enabled administration channel, the Administration Console is no longer available over the plain HTTP port.

The first time you access the site, your browser will pop up a message indicating that a certificate has been sent from the server (i.e., the server has presented its digital certificate to prove its identity). Because we've configured a digital certificate signed by a dummy CA, the browser warns that this is the case and gives you the opportunity to view the certificate. If you do view the certificate, notice that the certificate has been issued by a demonstration CA called CertGenCAB. At this stage, you can be assured that the one-way SSL configuration for the Administration Server is well and operational.

If a Java client needs to communicate with the Administration Server over SSL port 9002, the client must be able to validate the digital certificate sent back by the Administration Server. As you have learned already, this is possible if you configure a keystore that holds a list of trusted CA certificates. For instance, if you intend to use the weblogic.Admin tool to update the domain's configuration, the SSL connection to the Administration Server succeeds only if you also set the list of trusted CA certificates for the tool:

java -Dweblogic.security.TrustKeyStore=DemoTrust weblogic.Admin -url t3s://10.0.10.10:9002/ -username system -password pssst VERSION

In WebLogic 7.0, use the following options:

java -Dweblogic.security.SSL.trustedCAKeyStore=x:/server/lib/cacerts weblogic.Admin -url t3s://10.0.10.10:9002/ -username system -password pssst VERSION

16.2.6.2 Two-way SSL

Setting up two-way SSL for the server should not be a problem. Because you are using demonstration certificates, you simply need to configure WebLogic to use the demonstration trust keystore. Choose the Configuration/Keystores & SSL tab again. Select the Change option under Keystore Configuration, and this time select the "Custom Identity and Custom Trust" option. Leave the details of the custom identity keystore unchanged, and modify only the details for the custom trust keystore. Enter the absolute path to the DemoTrust.jks keystore (or copy it into the domain directory and use a relative path). This keystore isn't protected by any password, so you can leave the pass phrase field blank.

In the Advanced options of the Configuration/Keystores & SSL tab, set the two-way SSL behavior to "Client Certs Requested and Enforced." By enabling two-way SSL for the server, any client that needs to create an SSL connection must present a certificate to the server as proof of its identity. This requirement is especially crucial to the Node Manager because it relies on two-way SSL to protect communications with the Administration Server and all Managed Servers running on its machine. Restart the Administration Server for the changes to take effect.

If you now try to access the Administration Console using a browser, you will fail unless your browser has been populated with a certificate that it can present to the server. As a test, you can populate your browser with the certificate you created earlier. The only hitch is that most browsers want the certificate in the PKCS/12 format. To achieve this, we can use the freely available openssl tool to convert the certificate into a format understood by Mozilla and IE:

openssl pkcs12 -inkey mykeyfile.pem -in mycertfile.pem -out myCert.p12 -export

Now simply import the generated certificate myCert.p12 into your browser. The next time you access the Administration Console, your browser will send its certificate to WebLogic, and you should successfully reach the login page.