Friday, May 7, 2010

Mutual Authentication with Client Certificate over HTTPS/SSL using Java

This blog is about SSL/TLS mutual authentication using Java. I am on the client side with a client certificate signed by an intermediate issuer and finally by Verisign. (aha, a certificate chain is here to make the situation not vanilla already.) The server requests a client certificate and recognizes Verisign as a Certification Authority (CA). You can safely ignore this blog if you have a self-certified certificate.

During the implementation, I got tripped more than a couple of times over error messages like:
403.7 Forbidden: Client Certificate Required. HelloRequest followed by an unexpected handshake message
To save somebody some time in the future, a step by step instruction is provided below:
  1. I assume you have a valid certificate or a chain of certificates, whose root is acceptable by the server. The valid certificate contains its private key. Run the following command to verify:
    keytool -list -v -keystore "your certificate file"
    Entry type: PrivateKeyEntry
  2. Import your certificate and intermediate certificates into a browser like IE or Firefox and test out the https URL. This step will validate the certificates and save you a lot of troubles down the road. Java version of the SSL implementation is not as simple/mature as the browsers'. Please make sure all the certificates have not expired.
  3. Backup your keystore located at /your_home_directory/.keystore by default and the truststore located at somewhere similar to \Java\jre6\lib\security\cacerts
  4. Use not-yet-commons-ssl utility to import your certificates into the Java keystore format. Sample command is:
    java -cp not-yet-commons-ssl-0.3.9.jar org.apache.commons.ssl.KeyStoreBuilder 
  5. Customize the following java code, replace the static final Strings to fit in your needs. Note that this implementation forcefully use a specific alias to present the corresponding certificate/certificate chain to the server. Somehow the default KeyManager simply disqualifies my certificate to be presented to the server.
    public class Main {

    private static final Logger logger = Logger.getLogger(Main.class.getName());
    private static final String LINE_BREAKER = System.getProperty("line.separator");

    private static final String CERTIFACATE_FILE = "your keystore location";
    private static final String CERTIFACATE_PASS = "changeit";
    private static final String CERTIFACATE_ALIAS = "your alias";
    private static final String TARGET_URL = "";

    public static void main(String[] args) {
    String targetURL = TARGET_URL;
    URL url;
    HttpsURLConnection connection = null;
    BufferedReader bufferedReader = null;
    InputStream is = null;

    try {
    //Create connection
    url = new URL(targetURL);
    //Uncomment this in case server demands some unsafe operations
    //System.setProperty("", "true");
    connection = (HttpsURLConnection) url.openConnection();

    connection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
    connection.setRequestProperty("Content-Language", "en-US");

    SSLSocketFactory sslSocketFactory = getFactory(new File(CERTIFACATE_FILE), CERTIFACATE_PASS, CERTIFACATE_ALIAS);

    //Process response
    is = connection.getInputStream();

    bufferedReader = new BufferedReader(new InputStreamReader(is));
    String line;
    StringBuffer lines = new StringBuffer();
    while ((line = bufferedReader.readLine()) != null) {
    }"response from " + targetURL + ":" + LINE_BREAKER + lines);

    } catch (Exception e) {

    private static SSLSocketFactory getFactory(File pKeyFile, String pKeyPassword, String certAlias) throws Exception {
    KeyManagerFactory keyManagerFactory = KeyManagerFactory.getInstance("SunX509");
    KeyStore keyStore = KeyStore.getInstance("JKS");

    InputStream keyInput = new FileInputStream(pKeyFile);
    keyStore.load(keyInput, pKeyPassword.toCharArray());
    keyManagerFactory.init(keyStore, pKeyPassword.toCharArray());

    //Replace the original KeyManagers with the AliasForcingKeyManager
    KeyManager[] kms = keyManagerFactory.getKeyManagers();
    for (int i = 0; i < kms.length; i++) {
    if (kms[i] instanceof X509KeyManager) {
    kms[i] = new AliasForcingKeyManager((X509KeyManager) kms[i], certAlias);

    SSLContext context = SSLContext.getInstance("TLS");
    context.init(kms, null, null);
    return context.getSocketFactory();

    * This wrapper class overwrites the default behavior of a X509KeyManager and
    * always render a specific certificate whose alias matches that provided in the constructor
    private static class AliasForcingKeyManager implements X509KeyManager {

    X509KeyManager baseKM = null;
    String alias = null;

    public AliasForcingKeyManager(X509KeyManager keyManager, String alias) {
    baseKM = keyManager;
    this.alias = alias;

    * Always render the specific alias provided in the constructor
    public String chooseClientAlias(String[] keyType, Principal[] issuers, Socket socket) {
    return alias;

    public String chooseServerAlias(String keyType, Principal[] issuers, Socket socket) {
    return baseKM.chooseServerAlias(keyType, issuers, socket);

    public X509Certificate[] getCertificateChain(String alias) {
    return baseKM.getCertificateChain(alias);

    public String[] getClientAliases(String keyType, Principal[] issuers) {
    return baseKM.getClientAliases(keyType, issuers);

    public PrivateKey getPrivateKey(String alias) {
    return baseKM.getPrivateKey(alias);

    public String[] getServerAliases(String keyType, Principal[] issuers) {
    return baseKM.getServerAliases(keyType, issuers);

  6. Try to set
    if you get the error message like: HelloRequest followed by an unexpected  handshake message
  7. If anything goes wrong, turn on to debug. Verify the keystore and truststore locations. Verify the presence of the certificates. Here is a sample log file with successful connection:


  1. Denis, whilst I myself have authenticated on SSL Certificates from a leading authority (GlobalSign) a contact of mine has self-signed SSL authentication. To what extent does this change the authentication process? With low cost SSL certification from and other resellers, to what extent is self-signed certification actually beneficial? Thanks in advance!

  2. Who is on the server side?
    Does the client expect the server to be certified by a CA or self-certification is sufficient?
    Does the server expect the client to be certified by a CA or self-certification is sufficient?

  3. Denis,
    What alias did you force the key manager to use? I'm also having trouble getting the KeyManager (or something) to send my cert to the server.

    1. According to the code:
      private static final String CERTIFACATE_ALIAS = "your alias";

  4. hi Deni, i used this one ans getting following error PKIX path building failed: unable to find valid certification path to requested target

    can anyone tell me the problem???

    1. From the exception, it says the certification chain is broken somewhere.

  5. Next time, please include your import statements. I am having a hell-of-a-time trying to get your code to complie without ClassCastExceptions

    1. In Eclipse, the shortcut ctrl-shift-o will resolve all your import errors.

  6. WOW, thank you, thank you, thank you!!!!!! this resolved our issue.

  7. Awesome stuff. Helped me solve the issue as well! Kudos

  8. Hi,
    Thank you all for posting timely updates, your reviews would indeed help simplifying the complex procedures.

    Certificate Authentication

  9. Hi,
    This is the nice post and this post is really appreciable and informatics .I like this post too much.
    Thanks a lot for sharing such a good source with all, i appreciate your efforts taken for the same. I found this worth sharing and must share this with all.
    Authentication Certificate

  10. This might be useful as well.

  11. Hi,
    Great blog nice n useful information , it is very helpful for me , I realy appreciate thanks for sharing. I would like to read more information thanks.
    Certificate Authentication

  12. this is good example.. it worked in my env..thanks a bunch