Setting Up SSLTLS

Setting Up SSL/TLS

WebLogic Server supports secure communications with clients and other servers using either Secure Sockets Layer (SSL) or Transport Layer Security (TLS) connections. We assume that everyone is familiar with SSL; for those not familiar with TLS, all you really need to know is that TLS is essentially the next generation of SSL and that WebLogic Server currently supports TLS version 1.0. For the remainder of this book, we will not bother to make the distinction between SSL and TLS and will simply refer to both as SSL. Should we need to differentiate between the two, we will make it a point to say so explicitly.

In this section, we begin by giving you a brief review of SSL technology. Next, we talk about how to obtain X.509 certificates, private keys, and the CA certificates needed to configure SSL. We end this section with a detailed walkthrough of how to configure WebLogic Server to use SSL.

Reviewing SSL Technology

SSL supports two different connection modes or types. The two types are commonly called one-way and two-way SSL. One-way SSL allows the SSL client to uniquely verify that the SSL server is, in fact, who it claims to be. Two-way SSL extends one-way SSL by allowing the SSL server to uniquely verify that the client is who it claims to be.

These verifications are accomplished through the use of public/private key technology. This technology uses a set of two related keys known as a public key and a private key for encryption and signing purposes. Anything encrypted using the public key can be decrypted only using the private key, and vice versa. As the names suggest, the owner of the private key keeps this key locked away where only the owner has access to it and gives its public key to everyone who might need it. In almost all cases, private key files are additionally encrypted with a passphrase that must be supplied to get the actual private key as an additional safety check against unauthorized use. The standard way of distributing public keys is to use X.509 certificates that contain information about the certificate s owner and public key.

X.509 certificates are issued by different authorities that digitally sign the certificates with their private key to allow verification (through the use of their public key) that they did, in fact, issue the certificate and that it has not been tampered with. In some cases, the signing authority s certificate might have been signed by another authority and so on. This brings about the notion of a certificate chain where the top of the chain is known as the root certificate authority (CA) whose certificate is always self-signed. When you get the CA s certificate, that certificate will generally contain the entire certificate chain back to the root CA. This root CA and/or certificate chain is used by the receiver of the original certificate to determine whether he or she trusts that the certificate is legitimate .

Public/private key technology supports different encryption strengths by supporting keys of different lengths. Up until recently, U.S. software companies were strictly regulated against exporting encryption technology above a certain strength. This gave rise to the labeling of the encryption strengths as either export or domestic . Currently, with the proper paperwork, software companies can legally export domestic-strength encryption to most other countries . WebLogic Server supports both domestic- and export-strength encryption. At the time of writing, you still need a special license key to enable the server to use domestic-strength encryption technology. We expect that this may change by the time you are reading this book.

With one-way SSL, the SSL client uses the server s certificate (actually, the public key contained in the certificate) to encrypt data that can be decrypted only with the server s private key. This is why it is critical for the server to keep its private key safe and its passphrase a secret. With two-way SSL, the SSL server uses that client s certificate to encrypt data that can be decrypted only with the client s private key. The SSL server may use the client s certificate to uniquely identify and authenticate the client in the application layer. In order for the client to trust the certificate provided by the server, it must verify the signing chain of the server s certificate. If the client trusts the server s certificate authority, it can verify the server s certificate and prove that it is real and has not been tampered with. This verification requires the client to have the CA s certificate for the server available locally, as a notion of which certificates the client will trust .

In the case of two-way SSL, the server must use the exact same mechanisms to verify the client s certificate. The server requires the client s root CA s certificate locally for two-way SSL. See Table 10.3 for this listing of required data on either side. Notice the concepts of identity and trust for both the SSL server and the SSL client. The identity is the certificate and private key. The trust is the certificate authority.

Table 10.3:  Required SSL Configuration Data

SSL MODE	CLIENT	SERVER
One-way SSL	Copy of server root CA certificate	Server root CA certificate and chain Server certificate Server private key
Two-way SSL	Copy of server root CA certificate Client root CA certificate and chain Client certificate Client private key	Server root CA and chain Server certificate Server private key Copy of client root CA certificate

Obtaining X.509 Certificates

Now that you understand what you need, we can walk through the process of generating a new certificate and private key for the server. WebLogic Server provides two utilities you can use to generate a new certificate and private key, or you can use the keytool program that comes with the Java 2 SDK. If you want to generate certificates and private keys quickly for demonstration or development purposes, then you can use the utils .CertGen utility. We will use utils.CertGen in the Configuring Two-Way SSL section, so we won t spend any time on it here.

If you need certificates for a production server, you will probably want to get your certificates signed by a well-known certificate authority (CA) or use a public key infrastructure (PKI) product. This means that in addition to generating the certificate and the private key, you will need to generate a Certificate Signing Request (CSR) that can be submitted to a certificate authority. If you have done this with a previous version of WebLogic Server, you are probably already familiar with the Certificate Request Generator Servlet . As of WebLogic Server 8.1, this servlet has been deprecated. To use this servlet, you will need to deploy the certificate.war web application to your server and log in as a user with the Admin role get access to the application. Since its deprecation in WebLogic Server 8.1, the certificate.war file that used to be deployed by default to all servers is now located the $WL_HOME/server/lib directory. For more information about the Certificate Request Generator Servlet , please refer to the WebLogic Server documentation at http://edocs.bea.com/wls/docs81/secmanage/ssl.html .

Going forward, BEA recommends using the keytool program that comes with Java 2 SDK. The keytool program can be tedious and unforgiving, so we will walk you through the certificate-generation process step by step. First, you need to generate your self-signed certificate and private key:

 keytool -v -genkey -alias server_cert -keyalg RSA -keysize 1024         -dname CN=www.bigrez.com,OU=Operations,                 O=BigRez.com,L=Dallas,S=Texas,C=US         -keypass secret_key_passphrase         -keystore server_keystore.jks         -storepass secret_store_password 

This command generates a self-signed certificate and private key, whose passphrase is secret_key_passphrase , using a 1024-bit RSA algorithm and stores them in the key store file server_keystore.jks , whose password is secret_store_password , under the alias server_cert . Pay special attention to the key size and CN element of the distinguished name . The hostname you enter for the CN here must be the same as the hostname your SSL clients will use to connect to your SSL server.

Warning  

Set the CN field to the hostname that your SSL clients will ultimately use to reach your server. Failure to do this will result in a certificate that your SSL client may reject because the hostname does not match the IP address the client is using to reach the server.

You should set the key size to the highest value your WebLogic Server license will allow. At the time of writing, WebLogic Server supports 512-, 1024-, and 2048-bit key-lengths; anything over 512-bit key lengths currently requires a domestic-strength SSL license key. We expect that this information may change, so please check the WebLogic Server documentation for more information.

Warning  

Key lengths of less than 1024 bits are generally considered too weak. If SSL is important enough to use in your environment, we recommend obtaining a domestic-strength license from BEA.

The next step is to generate a certificate signing request:

 keytool -certreq -v -alias server_cert          -file www_bigrez_com-request.pem         -keypass secret_key_passphrase         -storepass secret_store_password         -keystore server_keystore.jks 

The result of this command will be a text file called www_bigrez_com-request.pem containing our certificate signing request.

Once we have the CSR, we can go to our certificate authority and request a signed certificate. Several different, well-known certificate authorities will sell you a signed certificate. Some CAs will allow you to use a CSR to get a temporary trial server certificate in about 15 minutes. These can be very useful for development and testing efforts prior to production. VeriSign will give you a 14-day trial certificate when you submit your CSR at https ://digitalid.verisign.com/server/trial/trialStep2.htm. You can get VeriSign s signing chain of certificates for that temporary trial certificate at http://www.verisign.com/server/trial/faq/ . Baltimore Technologies will also provide a 30-day trial certificate at http://www. baltimore .com/servercert/ssltrial.asp .

Depending on your CA, you might get your signed certificate and/or the CA s certificate in one of several different formats. Privacy-Enhanced Mail (PEM) format is the most common and is just a text file containing special beginning and ending delimiters with the certificate information Base64-encoded in between. Look at the www_bigrez_com-request.pem file in the downloadable example code to see what a PEM-formatted certificate looks like. Distinguished Encoding Rules (DER) is the other common format, which is a binary format.

Some certificate authorities might give you a certificate file with a .cer file extension. This is a Microsoft file extension for certificates and can contain either a binary-encoded (DER format) or a Base64-encoded (PEM format) certificate. Some tools may check the file extensions and refuse to recognize the .cer file as a valid certificate. If this happens, open up the file in a text editor to see if the file is Base64-encoded or binary. If it is Base64-encoded, rename the file using a .pem extension; if the file is binary, use a .der extension.

Should you ever need to convert between PEM and DER formats, WebLogic Server provides two utility programs, utils.der2pem and utils.pem2der , that will convert between PEM and DER formats. See http://edocs.bea.com/wls/docs81/toolstable/ToolsTable.html for more information on these utilities.

Once you have your signed certificate and the CA s certificate chain available in either PEM or DER format, you will need to import your signed certificate into the key store. Because the keytool program will not allow you to import a certificate for which it cannot verify the certificate s signing chain, you need to import the CA s certificate chain as a trusted CA certificate before importing the signed certificate:

 keytool -import -v noprompt trustcacerts -alias cacert          -file getcacert.der -keystore server_keystore.jks          -storepass secret_store_password 

Now you are ready to import the signed certificate that will replace the self-signed certificate you created earlier:

 keytool -import -v -alias server_cert         -file www_bigrez_com-cert.pem         -keystore server_keystore.jks         -keypass secret_key_passphrase         -storepass secret_store_password 

At this point, you have a key store that contains the server s signed certificate, the server s private key, and the trusted CA certificate, which should include the entire certificate chain. All you need to do now is to configure the server and provide the client with the trusted CA certificate, if the client doesn t already have it.

Configuring One-Way SSL

You finished all of the hard configuration work in the last section; now we ll help you set up the server to use your key store. All you need to do is to edit the server s configuration using the server s Keystores & SSL Configuration tab in the WebLogic Console. First, change the key store information by selecting the Change link in the Keystore Configuration heading at the top of this page. Because you are going to supply a new certificate but use the Java 2 SDK-supplied key store, select the Custom Identity and Standard Java Trust option for the Keystore attribute.

Now, you simply fill in the file name, key store type, and key store password for the Custom Identity Keystore and the password for your standard Java key store. The standard Java key store is always found at $JAVA_HOME/jre/lib/security/cacerts and has a default key store password of changeit . You can change the password of this key store using the keytool “storepasswd command; however, we recommend that you do not modify this file. If you are not comfortable with having this trust key store with this well-known password, we recommend copying this key store to another location, resetting the password, and switching to use a custom trust key store. This makes it easier to upgrade your WebLogic Server software without running the risk of losing your customized trust key store.

Best Practice  

Never modify the standard Java trust key store directly. If you want to use it as a starting point and customize it, make a copy of it into someplace that is associated with your application configuration and modify the copy.

The downloadable example places the identity key store file in the domain s root directory. You can place the file anywhere you want but remember that this file must be protected so we recommend keeping it close to the rest of your server s configuration files. Any relative path that you enter for the key store file name is relative to the domain s root directory. The key store type is JKS (short for Java key store), and the value of the Key Store Pass Phrase attribute is simply the key store s password you used when creating the key store ” secret_store_password in our example.

Next, we need to provide information that allows the server to retrieve the private key from the key store, which includes the private key s alias in the key store and its passphrase. The private key alias you should use in this example is the alias for the server s certificate: server_cert . Once this is finished, simply restart the server for your changes to take effect. Don t forget to enable the SSL Listen Port.

Finally, you need to make the server s CA certificate chain available to the client. If you are using real certificates from well-known authorities, your client will probably already have the certificate chain in its trusted CA certificates store. If not, you will need to make the CA s certificate chain available to the client.

For browser-based clients, the browser will simply prompt the user to ask whether he or she wants to trust this certificate, as well as giving the user an option to install it. You can also proactively install the trusted CA certificate chain on the client. For Internet Explorer, you need to install the trusted CA certificate chain in the operating system. Please talk to your Windows administrator or refer to the MSDN article on how to manage end-user certificates at http://www.microsoft.com/technet/prodtechnol/windows2000serv/howto/enducert.asp . For Netscape or other browsers, please refer to the browser documentation.

For Java-based clients, you can either add the new certificates to the Java 2 SDK s $JAVA_HOME/jre/lib/security/cacerts key store or create a new client trust key store. If you create a new client trust key store, you need to tell your Java client to use it. Depending on whether you are using WebLogic SSL or JSSE, you do this by setting the Java system property weblogic.security.SSL.trustedCAKeyStore or javax.net.ssl.trustStore to point at your new trust key store file before any SSL connection is made. We will talk more about how to do this in the Writing Java Clients That Use SSL section later in this chapter.

Configuring Two-Way SSL

Now that you have seen how to configure the server for one-way SSL, getting to two-way SSL is pretty simple. In this section, you will use the utils.CertGen utility that comes with WebLogic Server to generate client certificates. Remember that utils_.CertGen is not intended for use in production environments. You could just as easily use the same keytool-based process used to generate certificates for the server to generate the client certificates. Our primary motivation for using utils.CertGen here is to show you how you can use it to generate certificates for demonstrations or development environments without incurring the cost of buying real certificates for every demo/development machine.

First, let s generate the client certificate, private key, and key store. utils.CertGen is a simple utility that can be used to generate export- or domestic-strength certificates (512- or 1024-bit key lengths, respectively). The syntax of the command is as follows :

 java utils.CertGen <key_passphrase> <cert_file_name>                    <key_file_name> [exportdomestic] [hostname] 

In this example, we want to generate a domestic-strength certificate for a machine called bauersc.bigrez.com so that we can run the following command on any machine. The output of this command is four files containing the certificate and the primary key in both PEM and DER formats:

 java utils.CertGen client_key_passphrase bauersc_bigrez_com-cert      bauersc_bigrez_com-key domestic bauersc.bigrez.com 

You can find the CA certificate used to sign all certificates generated by utils.CertGen at $WL_HOME/server/lib/CertGenCA.der .

You will need to make the client s CA certificate available to the server. Because your server is currently configured for one-way SSL and using the standard Java Trust key store, you either need to add the client CA cert to the standard Java key store or create a new server trust key store. Recall that we don t recommend modifying the standard Java trust key store. We recommend copying the standard Java trust key store because it already contains most of the root CA certificates you will need. If your application is an internal application, you may want to start with a new key store and add only the CA certificates approved for use within your organization.

Tip  

For sites using two-way SSL with external clients, starting with the standard Java trust key store will ensure that most clients will be able to connect using their existing certificates.

Start by copying the standard Java trust key store to a file called server_trust_keystore.jks in the domain s root directory and changing its password:

 keytool -storepasswd -new secret_trust_password          -keystore server_trust_keystore.jks -storepass changeit 

Then, import the client s CA certificate, just as you did before, using the keytool “import “trustecacerts command:

 keytool -import -v noprompt -trustcacerts -alias cacert3          -file %WL_HOME%\server\lib\CertGenCA.der          -keystore server_trust_keystore.jks          -storepass secret_trust_password 

Now, you need to reconfigure the server to use this new trust key store. Simply go back to the server s Keystores & SSL Configuration tab in the WebLogic Console and select the Change link in the Keystore Configuration heading. Now, select the Custom Identity and Custom Trust option for the Keystores attribute. Next, set the trust key store name, type, and passphrase to the appropriate values ( server_trust_keystore.jks , JKS , and secret_trust_password , respectively). You can leave everything else unchanged and finish applying the changes. Before restarting the server, let s go ahead and make the other SSL changes to enable two-way SSL.

Back on the Keystores & SSL Configuration tab, scroll down to the bottom of the page and select the Show link in the Advanced Options heading. There are two settings of interest to our current discussion. First, you need to change the Two Way Client Cert Behavior attribute that tells the server how to handle client certificates. Setting it to a value of Client Certs Requested But Not Enforced will turn on two-way SSL, but the SSL connection process will continue even if the client does not provide a certificate. If you want to require two-way SSL, then set the value to Client Certs Requested And Enforced . We will use the last setting because we want to verify that two-way SSL is working properly.

The other attribute of interest is Hostname Verification , which controls the behavior that the server uses when validating a certificate sent to it. This applies when the server is acting as a client to another SSL server. By default, this is set to the value BEA Hostname Verifier , which tells the server to use the internal implementation for verifying that the hostname in the certificate matches the destination from which the certificate originated. In some cases, you might want to change this setting to None to allow the use of certificates that do not match while in development. Never use this setting in a production environment. In extreme circumstances, you might need to provide your own implementation of the hostname verifier. You can do this by setting the value to Custom Hostname Verifier and setting the Custom Hostname Verifier attribute to the fully qualified class name of a class that implements the weblogic.security.SSL.HostnameVerifier interface.

It is also possible to disable all hostname verification completely in any WebLogic SSL client or server by setting the Java system property weblogic.security.SSL.ignoreHostnameVerification to true . Of course, another way to do this would be to provide your own hostname verifier class that always returns true. Either way, this is extremely dangerous because it disables all verification that the certificate being used is actually from the other process supplying it. It can be useful, though, in a development or demonstration environment when you simply want to use the demonstration certificates that come with WebLogic Server. Do not forget to re-enable hostname verification when migrating your configuration to a production environment.

Best Practice  

Disabling hostname verification can make things simpler in a development or demonstration environment; always re-enable hostname verification for your production environments.

If you are using browser-based clients, you will need to install the client certificates used by the browsers. Of course, these client-side, brower-based certificates will likely be user-specific certificates, so make sure to install them appropriately. If you intend to use two-way SSL as an application authentication mechanism, make sure that each user s certificate contains his or her WebLogic Server username somewhere in the distinguished name. We will talk more about application authentication after we discuss configuring Java clients.

For Java clients, you need to create identity and trust key stores for the client to use. Again, these key stores can be the same or different key stores. In this example, you will use two separate key stores to help you understand what needs to go in each key store. The identity key store needs to contain the client s certificate and private key. To create this client key store, you will use another WebLogic Server-provided utility called utils.ImportPrivateKey , whose syntax is as follows:

 java utils.ImportPrivateKey <keystore_file> <keystore_password>      <certificate_alias_to_use> <private_key_passphrase>      <certificate_file> <private_key_file> [<keystore_type>] 

If the keytool program provided an easy way to import an existing private key from a file, you would not need this utils.ImportPrivateKey utility. Because it doesn t, use the following command to create your identity key store and import your existing certificate and primary key:

 java utils.ImportPrimaryKey client_keystore.jks      client_store_password client_cert client_key_passphrase      bauersc_bigrez_com-cert.pem bauersc_bigrez_com-key.pem 

Notice that by using the utils.ImportPrivateKey utility you did not have to import the CA certificate chain first.

Next, you need to create your trust key store. Because Java client programs are not typically talking with a large number of servers controlled by different organizations, we have chosen to create a new trust key store rather than starting with the one included with the Java 2 SDK. You will place both the client s and the server s CA certificate chain in the trust key store. Once again, you can use the keytool program to create the new store and import both certificate chains:

 keytool import v -noprompt trustcacerts alias client_cacert         -file %WL_HOME%\server\lib\CertGenCA.der         -keystore trust_store_keystore.jks         -storepass _trust_store_password keytool import v -noprompt trustcacerts alias server_cacert         -file getcacert.der -keystore trust_store_keystore.jks         -storepass _trust_store_password 

Finally, you just need to get your Java client programs to use these new key stores. You can use the Java system property weblogic.security.SSL.trustedCAKeyStore to tell your client which trust key store to use. As you will see later in the Writing Java Clients That Use SSL section, the identity key store to use is referenced directly from within the client-side Java code.

The last thing we need to discuss is how to use two-way SSL as an application authentication mechanism. To use client certificates to authenticate your client users, you need to configure the server to support this. If you want to require users to be authenticated without prompting them for a username and password, make sure that you set the Two Way Client Cert Behavior attribute to Client Certs Requested And Enforced . Otherwise, WebLogic Server will treat any client that does not present a certificate as a one-way SSL client, and accessing a protected resource will cause them to be prompted for a username and password. Next, you need to create WebLogic Server users for mapping to client certificates. We will talk more about user management in the Setting Up WebLogic Application Security section later in this chapter. Finally, you need to configure the DefaultIdentityAsserter to support X.509 token types and set up the username mapper to extract the mapping information from the certificate and return the username, as previously discussed in the Identity Assertion section.

In this example, because the CN of our utils.CertGen -created client certificates contains the fully qualified hostname, you should set the Default User Name Mapper to extract the user information from the CN field and use the . character as the delimiter to map the hostname bauersc.bigrez.com properly to the WebLogic Server user bauersc . Once you have everything configured correctly, you should be able to use normal J2EE and/or WebLogic Server security mechanisms with your users without requiring them to log in or supply a password.

Debugging SSL Problems

Debugging problems with SSL configurations can be a frustrating task because most of the real work happens during the initial SSL handshake, before the server application code is ever invoked. Fortunately, WebLogic Server has some debugging flags that cause the server to print out very detailed information during the handshake. Without this sort of information, it is almost impossible for you (or BEA technical support) to debug the problem. To turn on this debugging output, you must use the Java command-line options to set both the ssl.debug and weblogic.StdoutDebugEnable Java system properties to true for the WebLogic Server, the Java-based application client, or both. This will cause the debugging information to be written to stdout .

Be aware that in some previous versions of WebLogic Server, Java-based WebLogic Server application clients using SSL cannot have the Sun s Java Secure Sockets Extension (JSSE) implementation in their classpath. Because the Java 2 SDK 1.4.x ships this implementation in the $JAVA_HOME/jre/lib/jsse.jar file, this can often be a problem. If this is, in fact, a problem with your particular situation, moving this file to a directory outside of the classpath will resolve the problem. WebLogic Server 8.1 clients do not suffer from this limitation. Please check the release notes for the WebLogic Server version you are using to see if this could be related to your problem.

Tip  

When having SSL problems, first check the release notes for any known problems that may apply to your particular configuration. Turning on the SSL debugging flags can make debugging SSL configuration problems much simpler.