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.
javax.net.ssl.SSLException: 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 = "https://xyz.com";


    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("sun.security.ssl.allowUnsafeRenegotiation", "true");
    connection = (HttpsURLConnection) url.openConnection();

    connection.setRequestMethod("POST");
    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);
    connection.setSSLSocketFactory(sslSocketFactory);

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

    bufferedReader = new BufferedReader(new InputStreamReader(is));
    String line;
    StringBuffer lines = new StringBuffer();
    while ((line = bufferedReader.readLine()) != null) {
    lines.append(line).append(LINE_BREAKER);
    }
    logger.info("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());
    keyInput.close();
    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
    -Dsun.security.ssl.allowUnsafeRenegotiation=true
    if you get the error message like:
    javax.net.ssl.SSLException: HelloRequest followed by an unexpected  handshake message
  7. If anything goes wrong, turn on -Djavax.net.debug=all to debug. Verify the keystore and truststore locations. Verify the presence of the certificates. Here is a sample log file with successful connection: http://java.sun.com/javase/6/docs/technotes/guides/security/jsse/ReadDebug.html

48 comments:

  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 SSL247.co.uk and other resellers, to what extent is self-signed certification actually beneficial? Thanks in advance!

    ReplyDelete
  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?

    ReplyDelete
  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.

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

      Delete
  4. hi Deni, i used this one ans getting following error
    javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

    can anyone tell me the problem???

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

      Delete
  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

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

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

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

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



    Certificate Authentication

    ReplyDelete
  9. This might be useful as well.

    http://ankursinghal86.blogspot.in/2014/06/authentication-with-client-certificate.html

    ReplyDelete
  10. 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

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

    ReplyDelete
  12. I got this error: javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure.
    How do i resolve this?

    ReplyDelete
  13. Nice post. I was working on it last 6 month but currently its solve.

    ReplyDelete
  14. nice article
    very useful information.
    keep sharing.

    ReplyDelete
  15. Nice information, valuable and excellent design, as share good stuff with good ideas and concepts, lots of great information and inspiration, both of which I need, thanks to offer such a helpful information here.
    java training in Bangalore

    ReplyDelete

  16. We provide best Selenium training in Bangalore, automation testing with live projects. Cucumber, Java Selenium and Software Testing Training in Bangalore.

    ReplyDelete
  17. Thanks for sharing this fantastic Article, really very informative. Your writing skill is very good, you must keep writing this type of Article.

    digital marketing course in hubli

    ReplyDelete
  18. Visit cognex website to know more about aws and microsoft azure certification and training in chennai. We are the best in AWS Training in chennai.

    ReplyDelete
  19. This is most informative and also this post most user-friendly and super navigation to all posts.
    Best RPA Training in Pune
    AWS Training in Pune

    ReplyDelete
  20. interesting information.keep up the good work.Angular training in Chennai

    ReplyDelete
  21. Admiring the dedication you put into your blog and in depth information you provide.
    It’s awesome to come across a blog every once in a while that isn’t the same old rehashed information. Fantastic read! Software Security Solutions

    ReplyDelete
  22. Wonderful blog! Thanks for the information, Also if anyone is interested for Jobs in Aviation field do visit the institute which provides Air Hostess course

    ReplyDelete
  23. Amazing post thank you for sharing this interesting and informative content.
    java training course provider in Faridabad

    ReplyDelete
  24. Thank you for sharing this insightful content. I always look forward to reading such high-quality articles filled with valuable information. The ideas presented are truly excellent and thought-provoking, which makes the post not only enjoyable but also enriching. Your dedication to delivering fantastic work is commendable, and I eagerly anticipate more of your contributions in the future visit Certifications in Software Testing: Boosting Your Career with the Right Course

    ReplyDelete
  25. Your blog provides a thoughtful and informative exploration of idealism in education, making it a valuable resource for those interested in understanding the philosophical foundations of educational theories. Well done!
    If you want to know about Mastering Python: A Comprehensive Course for Beginners You can read this link Mastering Python: A Comprehensive Course for Beginners

    ReplyDelete
  26. You're very welcome! I'm delighted to hear that you found the information valuable and engaging. If you ever have more questions, need further insights, or simply want to discuss any topic, feel free to reach out. I'm here to help! Thank you for your kind words, and I look forward to assisting you in the future. If you know about Future Scope of Data Science visit Future Scope of Data Science

    ReplyDelete
  27. Thank you for sharing this insightful content. I always look forward to reading such high-quality articles filled with valuable information. The ideas presented are truly excellent and thought-provoking, which makes the post not only enjoyable but also enriching. Your dedication to delivering fantastic work is commendable, and I eagerly anticipate more of your contributions in the future visit Unlocking Insights: Exploring Predictive Analytics and its Applications

    ReplyDelete
  28. Thank you for sharing! I always appreciate engaging content with valuable insights. The presented ideas are not only excellent but also captivating, making the post thoroughly enjoyable. Your continued efforts are commendable. Keep up the fantastic work.
    Visit: Python in the Cloud: Deploying Apps with AWS and Azure

    ReplyDelete
  29. I'm grateful for your sharing. I consistently value content that captivates with its valuable insights. The presented ideas are exceptional and thought-provoking, contributing to the overall enjoyment of the post. Continue your fantastic work!
    Visit : AI in Software Testing: The Future of Quality Assurance

    ReplyDelete