Java Example Code

The examples provided in the subpages below show how to implement a client for one way SSL and two way SSL. The examples manage the Java system properties relating to which truststores and keystorefrom to use from within the code. By ommiting these properties the JVM will use the default truststore and keystore (see Java SSL Basics page). These parameters can also be passed to the JVM as command line arguments if you do not wish to have the properties set from within the code and you do not wish to use the default truststore / keystore.

The examples show how the truststore property is explicitly set within the code:

Truststore Property is Static

System.setProperty("javax.net.ssl.trustStore", "truststoreCA.jks");

The certificates in this truststore file are those of each certificate authority trusted by the client. When the socket is connecting to a server, if the server presents a certificate issued by a certificate authority that is not trusted (certificate is not contained in the truststore) then the client will cancel the connection establishment and the connection will fail.


Additional Properties

Older versions of Java may need to add the HTTPS protocol handler property in order for the SSL connection to be successful. Only later versions of java.net.URL support https, previously the java.net.MalformedURLException was thrown with the message unknown protocol: https.

Enable https Handler

System.setProperty("java.protocol.handler.pkgs","com.sun.net.ssl.internal.www.protocol");

Other properties that may need to be set if no crypto provider can be found, or if an SSL provider cannot be determined.      

Setting Crypto and Provider properties

Security.addProvider( (Provider)Class.forName("com.sun.crypto.provider.SunJCE").newInstance());

java.security.Security.addProvider(new com.sun.net.ssl.internal.ssl.Provider());



Example 1: Client establishes 1 way SSL connection

For the most basic example of a client establishing a connection to a server using the default Java keystore and truststore please see http://www.exampledepot.com/egs/javax.net.ssl/Client.html. However if your application needs to manage its truststore at an application level please see example below. This example defines the necessary properties to specify the use of a specific truststore. These examples also assume that the application will use the default Java SSL implementation and JCE.

Prerequisites:

  • Truststore that includes the CA certificate for the authority that issued server’s certificate
Source Code: One way SSL Example

Example 2: client establishes 2 way SSL connection

This example again has the application specifying its own truststore, and also its own keystore. The keystore here is in PKCS12 format (as issued by my CA).

Prerequisites:

  • Truststore that includes the CA certificate for the authority that issued server’s certificate
  • Keystore that contains the private key and certificate of the client
Source Code: Two way SSL Example

2 way SSL: How a servlet reads the client certificate

For a web application secured with 2 way SSL - the application may require to see the client's certificate details so that it can make authorization decisions.
E.g. Bob is allowed access to payment functionality but Peter isnt, so we need to check the cert and see who is making the request.

This code snippet shows how a servlet retrieves the certificate information.

Reading the Certificate from the Request

public void doGet(HttpServletRequest req, HttpServletResponse res) throws ServletException, IOException {
    ..........
    X509Certificate[] certs = (X509Certificate[]) req.getAttribute("javax.servlet.request.X509Certificate");

    .........
Useful Links:
http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/ServletRequest.html#getAttribute(java.lang.String)
http://www.java2s.com/Code/Java/Servlets/javaxservletrequestX509Certificate.htm

Debugging SSL with Java

The following is a JVM environment property that enables detailed SSL debug information to be printed to the standard output

SSL Debug Parameter

-Djavax.net.debug=ssl
Click here to see example SSL Debug output for a one way SSL connection with https://mail.google.com.