Tuesday, November 9, 2010

Mutual PKI Authentication With a Java-based Application

I recently added certificate based authentication to an application I have been working on for awhile. It took longer to get done than I would have thought primarily because the number of moving pieces and most advice and guidance I found online was incomplete. I hope that documenting the complete setup I used will save someone else some time and frustration.

The requirements were:
  • Wiring together two Java applications via SOAP, using CXF framework
  • The producing application needed a valid server certificate
  • The consuming application needed to present a valid client certificate to the server
  • These certificates needed to be signed by a trusted root and share the same certificate authority
  • For authentication purposes, no custom code within the application itself
  • Use the Java keytool program to create keypairs and generate signing requests

The broad strokes:
  1. Create the necessary certificates
  2. Setup tomcat on the producing side to accept only https connections and require client authentication
  3. Setup the consuming application to present client certs that can satisfy the secure authentication handshake

Creating and signing the certificates

I have previously created a CA setup using strictly openssl, but for this project, I needed to lean more heavily on keytool to originate the keypairs and openssl to do the certificate signing. The keytool program comes with the JDK. I used a windows based openssl binaries from SLP.

Setup a directory structure as recommended by openssl installation and set an environment variable, %SSLDIR%, to point to your CA directory.

Create CA and RA
# Create the CA's keypair and self-signed certificate
# -x509 means create self-sign cert
# -keyout means generate keypair
# -nodes means do not encrypt private key.
# -set_serial sets the serial number of the certificate
openssl req -verbose -x509 -new -nodes -set_serial 1234 -subj "/CN=codebeneathCA/OU=project/O=company/ST=MO/C=US" -days 7300 -out %SSLDIR%/certs/cacert.pem -keyout %SSLDIR%/private/caprivkey.pem -config %SSLDIR%/openssl.config


# Create the Root Authority's keypair and Certificate Request
# without -x509, we generate an x509 cert request.
# -keyout means generate keypair
# -nodes means do not encrypt private key.
openssl req -verbose -new -nodes -subj "/CN=codebeneathRoot/OU=project/O=company/ST=MO/C=US" -days 7300 -out %SSLDIR%/certs/csrra.pem -keyout %SSLDIR%/private/raprivkey.pem -config %SSLDIR%/openssl.config


# Have the CN=codebeneathCA issue a certificate for the CN=codebeneathRoot
# We need -extfile exts -extenstions x509_extensions to make sure
# CN=TheRA can be a Certificate Authority.
openssl ca -batch -days 7300 -cert %SSLDIR%/certs/cacert.pem -keyfile %SSLDIR%/private/caprivkey.pem -in %SSLDIR%/certs/csrra.pem -out %SSLDIR%/certs/ra-ca-cert.pem -extfile exts -extensions x509_extensions -config %SSLDIR%/openssl.config


Create Server Cert

# Create keypairs and Cert Request for a certificate for server
# This procedure must be done in JKS, because we need to use a JKS keystore.
# The current version of CXF using PCKS12 will not work for a number of
# internal CXF reasons.
keytool -genkey -alias codebeneath-server -dname "CN=10.9.5.210,OU=codebeneath-server,O=company,ST=MO,C=US" -keystore C:/certs/server-keystore.jks -storetype jks -storepass password -keypass password -validity 365
keytool -certreq -alias codebeneath-server -keystore C:/certs/server-keystore.jks -storetype jks -storepass password -keypass password -file codebeneath-server-csr.pem


# Have the CN=codebeneathRoot issue a certificate for server via the Certificate Requests.
openssl ca -batch -days 7300 -cert %SSLDIR%/certs/ra-ca-cert.pem -keyfile %SSLDIR%/private/raprivkey.pem -in %SSLDIR%/requests/codebeneath-server-csr.pem -out %SSLDIR%/requests/codebeneath-server-ra.pem -config %SSLDIR%/openssl.config


# Rewrite the certificates in PEM only format. This allows us to concatenate them into chains.
openssl x509 -in %SSLDIR%/certs/cacert.pem -out %SSLDIR%/certs/cacert.pem -outform PEM
openssl x509 -in %SSLDIR%/certs/ra-ca-cert.pem -out %SSLDIR%/certs/ra-ca-cert.pem -outform PEM
openssl x509 -in %SSLDIR%/requests/codebeneath-server-ra.pem -out %SSLDIR%/requests/codebeneath-server-ra.pem -outform PEM


# Create a chain readable by CertificateFactory.getCertificates.
type %SSLDIR%\requests\codebeneath-server-ra.pem %SSLDIR%\certs\ra-ca-cert.pem %SSLDIR%\certs\cacert.pem > %SSLDIR%\requests\codebeneath-server.chain


# Replace the certificate in the server keystore with their respective full chains.
keytool -import -file codebeneath-server.chain -alias codebeneath-server -keystore C:/certs/server-keystore.jks -storetype jks -storepass password -keypass password -noprompt


# Create the server Truststore file containing the CA cert.
keytool -import -file cacert.pem -alias codebeneathCA -keystore C:/certs/server-truststore.jks -storepass password -noprompt


Create Client Cert

# Create keypairs and Cert Request for a certificate for client (codebeneath)
# This procedure must be done in JKS, because we need to use a JKS keystore.
# The current version of CXF using PCKS12 will not work for a number of
# internal CXF reasons.
keytool -genkey -alias codebeneath -dname "CN=10.9.5.105,OU=codebeneath-client,O=company,ST=MO,C=US" -keystore C:/certs/client-keystore.jks -storetype jks -storepass password -keypass password -validity 365
keytool -certreq -alias codebeneath -keystore C:/certs/client-keystore.jks -storetype jks -storepass password -keypass password -file codebeneath-csr.pem


# Have the CN=codebeneathRoot issue a certificate for client via the Certificate Requests.
openssl ca -batch -days 7300 -cert %SSLDIR%/certs/ra-ca-cert.pem -keyfile %SSLDIR%/private/raprivkey.pem -in %SSLDIR%/requests/codebeneath-csr.pem -out %SSLDIR%/requests/codebeneath-ra.pem -config %SSLDIR%/openssl.config


# Rewrite the certificates in PEM only format. This allows us to concatenate them into chains.
openssl x509 -in %SSLDIR%/requests/codebeneath-ra.pem -out %SSLDIR%/requests/codebeneath-ra.pem -outform PEM


# Create a chain readable by CertificateFactory.getCertificates.
type %SSLDIR%\requests\codebeneath-ra.pem %SSLDIR%\certs\ra-ca-cert.pem %SSLDIR%\certs\cacert.pem > %SSLDIR%\requests\codebeneath.chain


# Replace the certificate in the client keystore with their respective full chains.
keytool -import -file codebeneath.chain -alias codebeneath -keystore C:/certs/client-keystore.jks -storetype jks -storepass password -keypass password -noprompt


# Create the client Truststore file containing the CA cert and server cert.
keytool -import -file cacert.pem -alias codebeneathCA -keystore C:/certs/client-truststore.jks -storepass password -noprompt
keytool -import -file codebeneath-server-ra.pem -alias codebeneath-server -keystore C:/certs/client-truststore.jks -storepass password -noprompt


Create trust for the server to know the client

# Import the client cert into the server Truststore.
keytool -import -file codebeneath-ra.pem -alias codebeneath -keystore C:/certs/client-truststore.jks -storepass password -noprompt


Export client cert from keystore for browser import

The keytool program cannot export private keys in any format, so use portecle to do these steps so that we can verify the setup using a browser without involving the actual client application.
  1. Start portecle: java -jar ./portecle.jar
  2. File... Open keystore file... select the ./client-keystore.jks file. Type the password.
  3. Right-client the "codebeneath" certificate name. Select Export...
  4. Export Type: Private Key and Certificates. Export Format: PKCS #12. Click OK. Type the password.
  5. For the PKCS #12 password, it must be non-blank value or else the browser will not import it correctly.
  6. In the browser, import the certificate as a "Personal" certificate.
  7. In the browser, import the CA certificate as a trusted authoritative certificate.

Double check the results so far...

On the server machine:

keytool -list -keystore ./server-keystore.jks
  • one signed certificate chain, PrivateKeyEntry, alias="codebeneath-server"
keytool -list -keystore ./server-truststore.jks
  • CA certificate, trustedCertEntry, alias="codebeneathca",
  • client certificate,trustedCertEntry, alias="codebeneath"

On the client machine:

keytool -list -keystore ./client-keystore.jks
  • one signed certificate chain, PrivateKeyEntry, alias="codebeneath"
keytool -list -keystore ./client-truststore.jks
  • CA certificate, trustedCertEntry, alias="codebeneathca",
  • server certificate, trustedCertEntry, alias="codebeneath-server"

Server setup using tomcat


To accomplish the required mutual authentication (server is trusted https:// and client presents a valid certificate) requires setup within tomcat and the server war web.xml file. There is no code involved, it is strictly the setup of the servlet container to handle the security handshaking.

Tomcat server.xml file

Note that the clientAuth attribute must be "true" for things to work properly, even though the specification says that each war may individually be setup to require/not require client auth.
...
<Connector port=\"8443\" protocol=\"HTTP/1.1\" SSLEnabled=\"true\"
maxThreads=\"150\" scheme=\"https\" secure=\"true\"
clientAuth=\"true\" sslProtocol=\"TLS\"
keystoreFile=\"C:/certs/server-keystore.jks\"
keystorePass=\"password\"
keyAlias=\"codebeneath-server\"
truststoreFile=\"C:/certs/server-truststore.jks\"
truststorePass=\"password\"
/>
...

Tomcat tomcat-users.xml file

Each username must match a client certificate subject line. Use portecle to open the client cert and cut-and-paste the "Subject:" line to this file's username value. So, even though the client certificate is valid given the truststore requirements, each client must also be specifically listed in this file to have access to the server application.
...
<role rolename=\"codebeneathRole\">
<user username=\"CN=10.9.5.43, OU=project, O=company, ST=MO, C=US\" password=\"password\" roles=\"codebeneathRole\">
...


Server war web.xml file

Both "role-name" elements must match the tomcat-users.xml defined rolename. The "auth-method" value of "CLIENT-CERT" will require a client certificate for authentication. The "transport-guarentee" value of "CONFIDENTIAL" will redirect all requests
...
<login-config>
<auth-method>CLIENT-CERT</auth-method>
</login-config>
<security-role>
<role-name>codebeneathRole</role-name>
</security-role>
<security-constraint>
<display-name>CodeBeneath</display-name>
<web-resource-collection>
<web-resource-name>CodeBeneath</web-resource-name>
<description></description>
<url-pattern>/*</url-pattern>
<http-method>GET</http-method>
<http-method>POST</http-method>
<http-method>HEAD</http-method>
<http-method>PUT</http-method>
<http-method>OPTIONS</http-method>
<http-method>TRACE</http-method>
<http-method>DELETE</http-method>
</web-resource-collection>
<auth-constraint>
<description>
<role-name>codebeneathRole</role-name>
</auth-constraint>
<user-data-constraint>
<description>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>
...


Debug SSL

In the event that the mutual authentication fails, we can enable specific debugging on the server side. In the catalina.bat file, add the switch -Djavax.net.debug=ssl,handshake

Client Setup

Since the project used SOAP WS-*, including WS-Security, on the client side we used the CXF project to handle the wsdl-to-java code generation and to create the client port. My project uses CXF version 2.2.11, with the additional "cxf-rt-ws-security" dependency jar.

Client java code
package com.codebeneath;

import org.apache.cxf.endpoint.Client;
import org.apache.cxf.frontend.ClientProxy;
import org.apache.cxf.jaxws.JaxWsProxyFactoryBean;
//import org.apache.cxf.interceptor.LoggingInInterceptor;
import org.apache.cxf.interceptor.LoggingOutInterceptor;
import org.apache.cxf.transport.http.HTTPConduit;
import org.apache.cxf.configuration.jsse.TLSClientParameters;
import org.apache.cxf.binding.soap.saaj.SAAJOutInterceptor;
import org.apache.cxf.ws.security.wss4j.WSS4JOutInterceptor;
import org.apache.ws.security.handler.WSHandlerConstants;

import java.net.URL;
import java.security.GeneralSecurityException;
import java.security.KeyStore;
import java.security.KeyStoreException;
import java.security.NoSuchAlgorithmException;
import java.security.UnrecoverableKeyException;
import java.security.cert.CertificateException;
import java.util.HashMap;
import java.util.Map;
import java.util.logging.Logger;
import javax.net.ssl.KeyManager;
import javax.net.ssl.KeyManagerFactory;
import javax.net.ssl.TrustManager;
import javax.net.ssl.TrustManagerFactory;
import javax.xml.ws.BindingProvider;

/**
* Client a SOAP WS client for the service. Handles logging support, WS-Security and PKI certificates
*/
public final class Client {

private static final String DEFAULT_PASSWORD = "password";
private static final String KEYSTORE_FILENAME = "/client-keystore.jks";
private static final String TRUSTSTORE_FILENAME = "/client-truststore.jks";

private Client() {
}

/**
* Create a new WS client
* @param serviceUrl, the service URL endpoint
* @param sigPropFile, the properties file for client PKI. Must be on the classpath at runtime
* @return client port
*/
public static TroubleTicketServiceSoap createClient(URL serviceUrl, String sigPropFile, String keystoreDir) {

JaxWsProxyFactoryBean factory = new JaxWsProxyFactoryBean();
factory.setAddress(serviceUrl.toString());
factory.setServiceClass(TroubleTicketServiceSoap.class);

// request and response traces in the server.log
addLogging(factory);

// SOAP WS-Security header
addSecurityHeaders(factory, sigPropFile);

// create the client
TroubleTicketServiceSoap port = (TroubleTicketServiceSoap) factory.create();
((BindingProvider) port).getRequestContext().put("schema-validation-enabled", Boolean.TRUE.toString());

// handle trust of server certificates
addCertificateHandling(port, serviceUrl, keystoreDir);

return port;
}

private static void addLogging(JaxWsProxyFactoryBean factory) {
factory.getOutInterceptors().add(new LoggingOutInterceptor()); // SOAP Request
// factory.getInInterceptors().add(new LoggingInInterceptor()); // SOAP Response
}

private static void addSecurityHeaders(JaxWsProxyFactoryBean factory, String sigPropFile) {

// setup the properties for WS-Security. This is PKI signed. The SIG_PROP_FILE must be on the classpath
Map wss4jOutProps = new HashMap();
wss4jOutProps.put(WSHandlerConstants.ACTION, WSHandlerConstants.SIGNATURE);
wss4jOutProps.put(WSHandlerConstants.USER, "client");
wss4jOutProps.put(WSHandlerConstants.PW_CALLBACK_CLASS, ClientPasswordCallback.class.getName());
wss4jOutProps.put(WSHandlerConstants.SIG_PROP_FILE, sigPropFile);
wss4jOutProps.put(WSHandlerConstants.SIG_KEY_ID, "DirectReference");

// add required security interceptors
factory.getOutInterceptors().add(new SAAJOutInterceptor());
factory.getOutInterceptors().add(new WSS4JOutInterceptor(wss4jOutProps));
}

private static void addCertificateHandling(TroubleTicketServiceSoap port, URL serviceUrl, String keystoreDir) {
Client proxy = ClientProxy.getClient(port);
HTTPConduit conduit = (HTTPConduit) proxy.getConduit();
TLSClientParameters tcp = new TLSClientParameters();
tcp.setDisableCNCheck(true);

try {
KeyStore trustStore = KeyStore.getInstance("JKS");
KeyStore keyStore = KeyStore.getInstance("JKS");

// accept all self-signed server certs
// tcp.setTrustManagers(CertificateAcceptorCXF.acceptAllCerts());

File truststoreFile = new File(keystoreDir + TRUSTSTORE_FILENAME);
trustStore.load(new FileInputStream(truststoreFile), DEFAULT_PASSWORD.toCharArray());
TrustManagerFactory trustFactory = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
trustFactory.init(trustStore);
TrustManager[] tm = trustFactory.getTrustManagers();
tcp.setTrustManagers(tm);

// enable client certs for authentication
File keystoreFile = new File(keystoreDir + KEYSTORE_FILENAME);
keyStore.load(new FileInputStream(keystoreFile), DEFAULT_PASSWORD.toCharArray());
KeyManagerFactory keyFactory = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm());
keyFactory.init(keyStore, DEFAULT_PASSWORD.toCharArray());
KeyManager[] km = keyFactory.getKeyManagers();
tcp.setKeyManagers(km);

} catch (KeyStoreException kse) {
System.out.println("Security configuration failed with the following: " + kse.getCause());
} catch (NoSuchAlgorithmException nsa) {
System.out.println("Security configuration failed with the following: " + nsa.getCause());
} catch (FileNotFoundException fnfe) {
System.out.println("Security configuration failed with the following: " + fnfe.getCause());
} catch (UnrecoverableKeyException uke) {
System.out.println("Security configuration failed with the following: " + uke.getCause());
} catch (CertificateException ce) {
System.out.println("Security configuration failed with the following: " + ce.getCause());
} catch (GeneralSecurityException gse) {
System.out.println("Security configuration failed with the following: " + gse.getCause());
} catch (IOException ioe) {
System.out.println("Security configuration failed with the following: " + ioe.getCause());
}

if (serviceUrl.getProtocol().trim().equalsIgnoreCase("https")) {
conduit.setTlsClientParameters(tcp);
LOG.info("GSTv3 Web Service protocol is 'https' so " + "set the TLSClientParameters on the "
+ "HTTPConduit. This should cause the" + " request to accept all certificates "
+ "and disable the CN Check.");
} else {
LOG.info("GSTv3 Web Service url did was not 'https' so did NOT " + "set the TLSClientParameters "
+ "on the HTTPConduit.");
}
}
}


Client client-sign.properties

# Do not change these two properties
#
org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
org.apache.ws.security.crypto.merlin.keystore.type=jks
# Set your keystore location and password here!
#
org.apache.ws.security.crypto.merlin.file=c:/certs/client-keystore.jks
org.apache.ws.security.crypto.merlin.keystore.password=password
org.apache.ws.security.crypto.merlin.keystore.alias=codebebeath


Conclusion


I hope that this complete picture of mutual PKI certificate authentication helps. If anything is not clear, let me know and I will try to clarify.

9 comments:

Matt White said...

Excellent post! It has saved me a bunch of time.

I wanted to pass on one piece of information that caused me some trouble setting-up SSL client and server authentication in case anyone else reading this post runs into the same issue.

While configuring a CXF client to consume a WCF service, I received exceptions stating ”HelloRequest followed by an unexpected handshake message". After some digging it turns out that this is caused by renegotiation being disabled between Java 6 update 19 and 21. This was done as a short term stop-gap solution to prevent a well publicized SSL security vulnerability. The final patch was included in Java 6 update 22. Updating the Java version solved the problem. See the following link for more details: Link

Once again, great post!

Unknown said...

On which platform will it run, means what and all softwares do we have to install to run this code on our pc

Jeff said...

Geetanjali, The techniques here are platform independent, so would work on any OS. As far as software, any relatively recent version of Java (JDK v6+), Apache Tomcat (v6+), OpenSSL and Portecle will work.

Unknown said...
This comment has been removed by the author.
Unknown said...

Hi,
I am not able to get "%SSLDIR%/certs/cacert.pem". So can you please help out which version of openssl we need to install and how to. So that i will learn. Because i am new to PKI.

Advanced thanks for your help

Thanks
kumar

Jeff said...

Kumar,
If you're referencing the first two code blocks, then the line breaks may have thrown you off. Meaning the lines are meant to be run as a single command, like:

openssl req -verbose -x509 -new -nodes -set_serial 1234 -subj "/CN=codebeneathCA/OU=project/O=company/ST=MO/C=US" -days 7300 -out %SSLDIR%/certs/cacert.pem -keyout %SSLDIR%/private/caprivkey.pem -config %SSLDIR%/openssl.config

Unknown said...

Hi,
I am really thanks for your replay, I will share my mail Id, So can you please share some certificate based authentication material and how process is going and how to start.

Mail Id:pki.developer@gmail.com

please help me to understand these stuff.

thanks
kumar

Karuppasamy Mariappan said...
This comment has been removed by the author.
Karuppasamy Mariappan said...

I cant understand Your client code. please send to me web services and their client code sir. I am waiting for your fruitful reply Sir,
karuppasamyit10@gmail.com