Outbound and Two-way SSL

Files Prepare Run Troubleshooting Related Topics

About the Example

These examples demonstrate how to make 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 verify 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.

These examples are self-contained and can be run on a single host machine. The ssl client will resolve to the localhost to commuicate with a WebLogic server running on the same computer as the client.

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 ant run.sslclient commands include target parameters which specify the following information:

The WebLogic API used to connect to the server.
The server to which to connect. (Change this to target a different server than the localhost)
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 a 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 ant run.sslsocketclient includes target parameters which specify the following information:

The server to which to connect. (Change this to target a different server than the localhost)
An HTTPs port on the server.

Files Used in the Example

Directory Location:

MW_HOME/wlserver_10.3/samples/server/examples/src/examples/security/sslclient/

(where MW_HOME is the directory containing your WebLogic Server installation)

File
Click source files to view code.

Description
build.xml The ant build file that contains targets for building and running the example.
MyListener.java 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.java HostnameVerifier provides a callback mechanism so that implementions 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.java This module is given the partial or complete certificate chain provided by the peer and builds a certificate path to a trusted root and returns true if it can be validated and is trusted for client SSL authentication. This is a null implemention which always returns true after printing the certificate chain to System.out
SnoopServlet.jsp This servlet returns information about the HTTP request itself. You can modify this servlet to take this information and store it elsewhere for your HTTP server records. This servlet is also useful for debugging.
SSLClient.java SSLClient is a short example of how to use the SSL library of WebLogic to make outgoing SSL connections. It shows both how to do this from a stand-alone application as well as from within WebLogic (in a Servlet).
SSLClientServlet.java SSLClientServlet is a simple servlet wrapper of examples.security.sslclient.SSLClient
SSLSocketClient.java This class demonstrates connecting to a JSP served by WebLogic Server using the secure port and displays the results of the connection.

File Click source files to view code.	Description
build.xml	The ant build file that contains targets for building and running the example.
MyListener.java	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.java	HostnameVerifier provides a callback mechanism so that implementions 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.java	This module is given the partial or complete certificate chain provided by the peer and builds a certificate path to a trusted root and returns true if it can be validated and is trusted for client SSL authentication. This is a null implemention which always returns true after printing the certificate chain to System.out
SnoopServlet.jsp	This servlet returns information about the HTTP request itself. You can modify this servlet to take this information and store it elsewhere for your HTTP server records. This servlet is also useful for debugging.
SSLClient.java	SSLClient is a short example of how to use the SSL library of WebLogic to make outgoing SSL connections. It shows both how to do this from a stand-alone application as well as from within WebLogic (in a Servlet).
SSLClientServlet.java	SSLClientServlet is a simple servlet wrapper of examples.security.sslclient.SSLClient
SSLSocketClient.java	This class demonstrates connecting to a JSP served by WebLogic Server using the secure port and displays the results of the connection.

Prepare the Example

Prerequisites

Before working with this example:

Install WebLogic Server, including the examples.
Start the Examples server.
Set up your environment.

Configure WebLogic Server

In order to use the SSLSocketClient example, enable the the SSLSocket listener for your WebLogic server (It is disabled by default). To activate it, perform the following steps:

Bring up the Administration Console in your browser.
Click to expand the Environment -> Servers nodes in the left pane.
Select the examplesServer link from the Servers table in the right pane.
In the Configuration: General tab, click on the check-box for SSL Listen Port Enabled and verify that the SSL Listen Port is set to 7002.
Click the Save button to save the changes.

Build and Deploy the Example

Change to the SAMPLES_HOME\server\examples\src\examples\security\sslclient directory, where SAMPLES_HOME refers to the main WebLogic Server examples directory, such as d:\Oracle\Middleware\wlserver_10.3\samples.
Execute the following command:

ant build

This command compiles and stages the example.
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\examples\build\serverclasses and clientclasses directories respectively.
- Deploys the SnoopServlet.jsp to the SAMPLES_HOME\server\examples\build\examplesWebApp directory.
- The target mycerts creates certificates in the local directory which are used by the SSLCLient and SSLClientServlet examples.
- Creates mykeystore in local directory.
- Deploys the client2certs.pem and clientkey.pem files to the SAMPLES_HOME\domains\examples directory. The SSLClientServlet example uses them.

Run the Example

In this example, you run the SSL Client with one-way authentication. With one-way authentication, the server presents a certificate to the client to identify itself.

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:

D:\Oracle\Middleware\wlserver_10.3\samples\server\examples\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; SH
A-1, MD5 digests; SecureRandom; X.509 certificates; JKS keystore; PKIX CertPathValida
tor; PKIX CertPathBuilder; LDAP, Collection CertStores)
     [java]    provider[1] - SunJSSE - Sun JSSE provider(implements RSA Signatures, P
KCS12, SunX509 key/trust factories, SSLv3, TLSv1)
     [java]    provider[2] - SunRsaSign - SUN's provider for RSA signatures
     [java]    provider[3] - SunJCE - SunJCE Provider (implements DES, Triple DES, Bl
owfish, PBE, Diffie-Hellman, HMAC-MD5, HMAC-SHA1)
     [java]    provider[4] - SunJGSS - Sun (Kerberos v5)
     [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.HttpURLConnection$1
     [java]  Trying a new HTTPS connection using WLS client classes -
     [java]     https://localhost:7002/examplesWebApp/SnoopServlet.jsp
     [java]             200 -- OK
     [java]             weblogic.net.http.HttpURLConnection$1
     [java] ----

BUILD SUCCESSFUL

Total time: 14 seconds

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 SnoopServlet.jsp.

The output is similar to the following:

D:\Oracle\Middleware\wlserver_10.3\samples\server\examples\src\examples\security\sslclient>ant run.ssl
socketclient
Buildfile: build.xml

run.sslsocketclient:
     [java] https://localhost:7002
     [java]  Creating the SSLContext
     [java]  Initializing the SSLContext with client
     [java]   identity (certificates and private key),
     [java]   HostnameVerifier, 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'sidentity is completely lost.
     [java]  --------------------------------
     [java]  certificate 0 -- Serial number: -100408331910175262804647534905568003903
     [java] Issuer:C=US, ST=MyState, L=MyTown, O=MyOrganization, OU=FOR TESTING ONLY, CN=CertGenCAB
     [java] Subject:C=US, ST=MyState, L=MyTown, O=MyOrganization, OU=FOR TESTING ONLY, CN=DGOHN
     [java] Not Valid Before:Tue Nov 09 15:53:51 EST 2004
     [java] Not Valid After:Sun Nov 10 15:53:51 EST 2019
     [java] Signature Algorithm:MD5withRSA

     [java]  certificate 1 -- Serial number: 46914133237969612308202465797198785159
     [java] Issuer:C=US, ST=MyState, L=MyTown, O=MyOrganization, OU=FOR TESTING ONLY, CN=CertGenCAB
     [java] Subject:C=US, ST=MyState, L=MyTown, O=MyOrganization, OU=FOR TESTING ONLY, CN=CertGenCAB
     [java] Not Valid Before:Thu Oct 24 11:54:45 EDT 2002
     [java] Not Valid After:Tue Oct 25 11:54:45 EDT 2022
     [java] Signature Algorithm:MD5withRSA

     [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: -100408331910175262804647534905568003903
     [java] Issuer:C=US, ST=MyState, L=MyTown, O=MyOrganization, OU=FOR TESTING ONLY, CN=CertGenCAB
     [java] Subject:C=US, ST=MyState, L=MyTown, O=MyOrganization, OU=FOR TESTING ONLY, CN=DGOHN
     [java] Not Valid Before:Tue Nov 09 15:53:51 EST 2004
     [java] Not Valid After:Sun Nov 10 15:53:51 EST 2019
     [java] Signature Algorithm:MD5withRSA

     [java]       certs[1]: Serial number: 46914133237969612308202465797198785159
     [java] Issuer:C=US, ST=MyState, L=MyTown, O=MyOrganization, OU=FOR TESTING ONLY, CN=CertGenCAB
     [java] Subject:C=US, ST=MyState, L=MyTown, O=MyOrganization, OU=FOR TESTING ONLY, CN=CertGenCAB
     [java] Not Valid Before:Thu Oct 24 11:54:45 EDT 2002
     [java] Not Valid After:Tue Oct 25 11:54:45 EDT 2022
     [java] Signature Algorithm:MD5withRSA

     [java] HTTP/1.1 200 OK
     [java] Cache-Control: no-cache="set-cookie"
     [java] Connection: close
     [java] Date: Wed, 10 Nov 2004 22:50:24 GMT
     [java] Content-Length: 1264
     [java] Content-Type: text/html; charset=ISO-8859-1
     [java] Set-Cookie:JSESSIONID=BSbwvHknxVbaSRt8q44DRLrYltTa8txjCSTiVJE3X2sw3cX2wFTX!-389270382;path=/
     [java] X-Powered-By: Servlet/2.4 JSP/2.0

     [java] 
BUILD SUCCESSFUL

Total time: 12 seconds

Run the SSLClientServlet Example

To run the SSLClientServlet, execute the following command

ant run.sslservletclient

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

ssl client test
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.utils|weblogic.net
   provider[0] - SUN - SUN (DSA key/parameter generation; DSA signing; SHA-1, MD5 digests; SecureRandom; X.509 certificates; JKS keystore; PKIX CertPathValidator; PKIX CertPathBuilder; LDAP, Collection CertStores)
   provider[1] - SunRsaSign - Sun RSA signature provider
   provider[2] - SunJSSE - Sun JSSE provider(PKCS12, SunX509 key/trust factories, SSLv3, TLSv1)
   provider[3] - SunJCE - SunJCE Provider (implements RSA, DES, Triple DES, AES, Blowfish, ARCFOUR, RC2, PBE, Diffie-Hellman, HMAC)
   provider[4] - SunJGSS - Sun (Kerberos v5)
   provider[5] - SunSASL - Sun SASL provider(implements client mechanisms for: DIGEST-MD5, GSSAPI, EXTERNAL, PLAIN, CRAM-MD5; server mechanisms for: DIGEST-MD5, GSSAPI, CRAM-MD5)
   provider[6] - WebLogicCertPathProvider - WebLogic CertPath Provider JDK CertPath provider
   provider[7] - WLSJDKCertPathProvider - WebLogic JDK CertPath provider

Troubleshooting

General Troubleshooting Tips for Examples