Package examples.security.sslclient

These examples demonstrate how to make an outbound SSL connections and two-way SSL connections from a WebLogic Server that is acting as a client to another WebLogic Server or application server.

See:
Description

Class Summary

MyListener	MyListener implements the interface javax.net.ssl.HandshakeCompletedListener and shows the user how to receive notifications about the completion of an SSL protocol handshake on a given SSL connection.
NulledHostnameVerifier	HostnameVerifierJSSE provides a callback mechanism so that implementers of this interface can supply a policy for handling the case where the host that's being connected to and the server name from the certificate SubjectDN must match.
NulledTrustManager	Given the partial or complete certificate chain provided by the peer, build a certificate path to a trusted root and return true if it can be validated and is trusted for client SSL authentication.
SSLClient	SSLClient is a short example of how to use the SSL library of WebLogic to make outgoing SSL connections.
SSLClientServlet	SSLClientServlet is a simple servlet wrapper of examples.security.sslclient.SSLClient
SSLSocketClient	A Java client demonstrates connecting to a JSP served by WebLogic Server using the secure port and displays the results of the connection.

Package examples.security.sslclient Description

These examples demonstrate how to make an outbound SSL connections and two-way SSL connections from a WebLogic Server that is acting as a client to another WebLogic Server or application server. In the SSLClient example, the connection is made using the URL specified in a WebLogic Server application programming interface (API) in the client code. In addition, the examples use a Host Name verifier to validate that the host to which the SSL connection is made is the intended or authorized party, and private keys and certificates to validate that the peer can be trusted for SSL communication.

NOTE: JVM Support - The sslclient code example requires the JDK 1.3.1 Java Virtual Machine (JVM). It does not support the JRocket JVM.

The following table describes the files used in the sslclient examples.

Example File Summary

build.xml	The build script for the SSLClient example.
CertGenCA.der	Certgen Certificate Authority's (CA's) certificate in Definite Encoding Rules (DER) format.
CertGenCA.pem	Certgen CA's certificate in Privacy Enhanced Mail (PEM) format.
CertGenCAKey.der	The private key of the CertGenCA.

Description

SSLClient Example

The sslclient example demonstrates connecting to a JSP served by WebLogic Server. This connection is established using the weblogic.net.http.HttpsURLConnection class. The SSLClient makes connections using HTTP and HTTPS and can be run using either ant or from the command line. Use of certificates can be turned on using the Administration Console. The sslclient example also includes a dummy implementation of the weblogic.security.SSL.HostnameVerifierJSSE class to verify that the server the example connects to is running on the desired host.

The files in the sample application should be run in the following combinations:

Client API	Server
	WebLogic Server
WebLogic Server	ant run_sslclient

The sslclient code example provides an SSLClient, a Java client that can be run using either ant or from the command line.

The ant run_client commands include target parameters which specify the following information:

• The WebLogic API used to connect to the server.
• The server to which to connect.
• A non-secure port and secure port on the server.
• A target object to which to connect (SnoopServlet)(optional).

SSLSocketClient Example

The SSLSocketclient example demonstrates initializing an SSLContext with client identity, a HostnameVerifierJSSE, and a NulledTrustManager, using an SSLSocketFactory, and using HTTPs to connect to a JSP served by WebLogic Server. The SSLSocketclient example also includes a dummy implementation of the weblogic.security.SSL.HostnameVerifierJSSE class to verify that the server the example connects to is running on the desired host.

The files in the sample application should be run in the following combinations:

Client API	Server
	WebLogic Server
WebLogic Server	ant run_sslsocketclient

The ant run_sslsocketclient includes target parameters which specify the following information:

• The server to which to connect.
• An HTTPs port on the server.

Building and Running the Examples

Perform the following steps to build and run the examples:

1. Build the SSLClient, SSLSocketClient, and SSLClientServlet examples
2. Run the SSLClient example
3. Run the SSLSocketClient example
4. Run the SSLClientServlet example

Build the SSLClient, SSLSocketClient, and SSLClientServlet examples

1. Set up your development shell as described in Setting up your environment.

2. Compile the example by executing an ant build script.

   An ant build script is available in the SAMPLES_HOME\server\src\examples\security\sslclient directory. Enter the following command to execute the build script:

   ant

   The ant command builds, creates and deploys the files needed by the SSLClient, SSLSocketClient, and SSLClientServlet examples as follows:

   • Runs Clean to remove from the local directory any keystore and certs that were created in previous builds.
   • Compiles server classes and client classes into the SAMPLES_HOME\server\stage\examples\serverclasses and clientclasses directories respectively.
   • Deploys the SnoopServlet.jsp and ShowDate.jsp files to the SAMPLES_HOME\server\stage\examples\examplesWebApp directory.
   • The target mycerts creates certificates in the local directory which are used by the SSLCLient & SSLClientServlet examples.
   • Creates mykeystore in local directory.
   • Deploys the client2certs.pem and clientkey.pem files to the SAMPLES_HOME\server\config\examples directory. The SSLClientServlet example uses them.

Run the SSLClient Example

You can run the SSLClient example in either of two modes, one-way authentication or mutual authentication. In one-way authentication, the server presents a certificate to the client to identify itself. With mutual authentication, both the server and the client present certificates to each other to identify themselves. A separate procedure is provided for each mode.

• Run the SSLClient example with one-way authentication
• Run the SSLClient example with mutual authentication

When the SSLClient runs, it constructs a URL with which to make the connection. First the client will try to connect to the non-secure port (i.e., 7001 on WebLogic Server) on the server and then the client will try to connect using a secure port (i.e., 7002 on WebLogic Server). The response to the connection is displayed on the screen.

The SSLClient displays the following data on the screen or in the browser:

• The protocol handling package (i.e., the SSL package being used to make the secure connection). The SSL package is dependent upon the API being used. In the SSLClient, wls is specified, so the WebLogic SSL implementation is used.

• The registered providers (i.e., the security providers registered with the Java Security object).

• A message stating the HTTP connection attempt to the non-secure port and the result of that attempt. A successful attempt result shows the URL the client connected to, the response status code and messages, and the name of the class which serviced the request.

• A message stating the HTTPS connection attempt to the secure port and the result of that attempt. A successful attempt result shows the URL the client connected to, the response status code and messages, and the name of the class which serviced the request.

Additionally, when you run the SSLClient example in the mutual authentication mode, it demonstrates how the certificates that were generated using CertGen are presented to the server as the Client's identity.

Run the SSLClient Example with One-way Authentication

To run the SSLClient with one-way authentication on WebLogic Server using the WebLogic Server API, execute the following command

ant run_sslclient

Here is a sample output.

C:\bea\weblogic700\samples\server\src\examples\security\sslclient>ant run_sslclient
Buildfile: build.xml

run_sslclient:
     [java] ----
     [java]  JDK Protocol Handlers and Security Providers:
     [java]    java.protocol.handler.pkgs - weblogic.net
     [java]    provider[0] - SUN - SUN (DSA key/parameter generation; DSA signing;
	  SHA-1, MD5 digests; SecureRandom; X.509 certificates; JKS keystore)
     [java]    provider[1] - SunRsaSign - SUN's provider for RSA signatures
     [java]
     [java]  Trying a new HTTP connection using WLS client classes -
     [java]     http://localhost:7001/examplesWebApp/SnoopServlet.jsp
     [java]             200 -- OK
     [java]             weblogic.net.http.KeepAliveStream
     [java]  Trying a new HTTPS connection using WLS client classes -
     [java]     https://localhost:7002/examplesWebApp/SnoopServlet.jsp
     [java]             200 -- OK
     [java]             weblogic.net.http.KeepAliveStream
     [java] ----

BUILD SUCCESSFUL

Total time: 7 seconds

Run the SSLClient Example with Mutual Authentication

To run the SSLClient with mutual authentication on WebLogic Server using the WebLogic Server API, proceed as follows:

1. Bring up the Administration Console in a browser, click on the examples->server->examplesServer in the left-hand pane to display the examplesServer control panel in the right-hand pane, select the Connections tab, select the SSL sub-tab, click on the Client Certificate Enforced check box to select it, and click on Apply.
2. Also on the Administration Console, click on Security->Realms->myrealm->Providers->KeyStores->DefaultKeyStore to display the DefaultKeystore control panel in the right-hand pane, enter %WL_HOME%/server/lib/cacerts in the Root CAKey Store Location field, and click on Apply.
3. Stop and restart the server so the changes take effect.
4. Execute the following command:

   ant run_sslclient

5. The sample output is the same as for one-way authentication.

Note: Because the CA (certificate authority) that issued the client certs should be one that the server trusts, you are required to set the Root CAKeyStore Location field as described in step 2 above. The cacerts has the CertGenCA certificate in it.

Run the SSLSocketClient Example

To run the SSLSocket Client, execute the following command

ant run_sslsocketclient

The SSLSocketClient constructs a URL with which to make the secure connection. The response to the connection is displayed on the screen.

The SSLSocketClient displays the following data on the screen:

• A description of the SSLSocket creation process, which includes creating the SSLContext, initializing the SSLContext with client identity (certificates and private key), HostnameVerifierJSSE, and NulledTrustManager, creating a new SSLSocketFactory with SSLContext, and creating and opening a new SSLSocket with SSLSocketFactory.

• The output from the ShowDate.jsp.

Here is a sample output.

C:\bea\weblogic700\samples\server\src\examples\security\sslclient>ant run_sslsocketclient
Buildfile: build.xml

run_sslsocketclient:
     [java]
     [java] https://localhost:7002
     [java]  Creating the SSLContext
     [java]  Initializing the SSLContext with client
     [java]   identity (certificates and private key),
     [java]   HostnameVerifierJSSE, AND NulledTrustManager
     [java]  Creating new SSLSocketFactory with SSLContext
     [java]  Creating and opening new SSLSocket with SSLSocketFactory
     [java]  SSLSocket created
     [java]  --- Do Not Use In Production ---
     [java]   By using this NulledTrustManager, the trust in the server's identity
	  is completely lost.
     [java]  --------------------------------
     [java]  certificate 0 -- Serial number: 33
     [java] Issuer:C=US, ST=California, L=San Francisco, O=BEA WebLogic, OU=Security,
	  CN=Demo Certificate Authority, EMAIL=support@bea.com
     [java] Subject:C=US, ST=California, L=San Francisco, O=BEA WebLogic, CN=weblogic.bea.com, 
	  EMAIL=support@bea.com
     [java] Not Valid Before:Tue May 30 21:38:01 EDT 2000
     [java] Not Valid After:Thu May 13 21:38:01 EDT 2004
     [java] Signature Algorithm:MD5withRSA
     [java]
     [java]  certificate 1 -- Serial number: 0
     [java] Issuer:C=US, ST=California, L=San Francisco, O=BEA WebLogic, OU=Security, 
	  CN=Demo Certificate Authority, EMAIL=support@bea.com
     [java] Subject:C=US, ST=California, L=San Francisco, O=BEA WebLogic, OU=Security, 
	  CN=Demo Certificate Authority, EMAIL=support@bea.com
     [java] Not Valid Before:Tue May 30 21:37:44 EDT 2000
     [java] Not Valid After:Fri May 14 21:37:44 EDT 2004
     [java] Signature Algorithm:MD5withRSA
     [java]
     [java] Handshake Completed with peer 127.0.0.1:7002
     [java]    cipher: TLS_RSA_WITH_RC4_128_MD5
     [java]    peer certificates:
     [java]       certs[0]: Serial number: 33
     [java] Issuer:C=US, ST=California, L=San Francisco, O=BEA WebLogic, OU=Security, 
	  CN=Demo Certificate Authority, EMAIL=support@bea.com
     [java] Subject:C=US, ST=California, L=San Francisco, O=BEA WebLogic, CN=weblogic.bea.com, 
	  EMAIL=support@bea.com
     [java] Not Valid Before:Tue May 30 21:38:01 EDT 2000
     [java] Not Valid After:Thu May 13 21:38:01 EDT 2004
     [java] Signature Algorithm:MD5withRSA
     [java]
     [java] HTTP/1.0 200 OK
     [java] Date: Fri, 08 Mar 2002 19:31:47 GMT
     [java] Server: WebLogic WebLogic Server 7.0 beta Thu Mar 7 22:34:51 PST 2002 170092
     [java] Content-Length: 494
     [java] Content-Type: text/html
     [java] Refresh: 5
     [java] Set-Cookie: JSESSIONID=8JRk2lZLbcNVSqqMXI5r1WYl7DxjbwG8eEr3IUDuozkAIx5yS1Wq!1675777731; path=/
     [java] Cache-control: no-cache="set-cookie"
     [java] Connection: Close
     [java]
     \\
     \\The output of the ShowDate.jsp is shown here. The text is formatted in HTML for browser display. 
     \\See your output for actual text.
     \\
     [java]  SSLSocket closed

BUILD SUCCESSFUL

Total time: 6 seconds

Run the SSLClientServlet Example

To run the SSLClientServlet, perform either of the following procedures:

Perform either this procedure:

1. Start the weblogic Server with the following environment variables defined on the command line, that is, edit the startWLS.cmd file and add the following variable to the start server command (weblogic.server) that follows the :runadmin and @echo on lines:

   -Dweblogic.security.SSL.trustedCAKeyStore="WL_HOME\server\lib\cacerts"

   This modification is necessary because by default the server uses the cacerts from the JAVA_HOME\jre\lib\security directory.

2. Bring up the Administration Console in a browser.

3. Configure the NulledHostnameVerifer as follows:
   1. Select the examplesServer node in the left-hand pane. The examples>Servers>examplesServer window is displayed in the right-hand pane.

   2. Click on the Connections tab, scroll down to the Hostname Verifier field and enter examples.security.sslclient.NulledHostnameVerifier.

   3. Click Apply.

4. Stop and restart the server so the changes take effect.

Or this procedure:

Start the weblogic Server with the following environment variables defined on the command line, that is, edit the startWLS.cmd file and add the following variables to the start server command (weblogic.server) that follows the :runadmin and @echo on lines:

-Dweblogic.security.SSL.hostnameVerifier="examples.security.sslclient.NulledHostnameVerifier"
-Dweblogic.security.SSL.trustedCAKeyStore="WL_HOME\server\lib\cacerts"

After performing one of the above procedures:

Point your browser to: http://localhost:7001/examplesWebApp/SSLClientServlet

Here is a sample of the output displayed in the browser:

wls ssl client classes

java SSLClient wls localhost 7001 7002 /examplesWebApp/SnoopServlet.jsp

 JDK Protocol Handlers and Security Providers:
   java.protocol.handler.pkgs - weblogic.utils|weblogic.utils|weblogic.net|weblogic.management
   provider[0] - SUN - SUN (DSA key/parameter generation; DSA signing; SHA-1, MD5 digests; SecureRandom; X.509 certificates; JKS keystore)
   provider[1] - SunRsaSign - SUN's provider for RSA signatures

 Trying a new HTTP connection using WLS client classes - 
        http://localhost:7001/examplesWebApp/SnoopServlet.jsp
                200 -- OK
                weblogic.net.http.KeepAliveStream
 Trying a new HTTPS connection using WLS client classes - 
        https://localhost:7002/examplesWebApp/SnoopServlet.jsp
                200 -- OK
                weblogic.net.http.KeepAliveStream

There's More...

Read more about:

• SSL programming in Writing Secure Applications that Use SSL.
• The SSL protocol in Programming WebLogic Security.