Using Let’s Encrypt Certificates with OSGi HTTP Service

Rather than one of my usual polemics, this is a quickly-written practical post. I hope the information here is useful to somebody.

Currently I am setting up, the website for my upcoming book “Effective OSGi”. The site is a web app that will allow users to download preview PDFs, order print copies, and so on. Naturally I am developing it in Java and OSGi (in fact, many of the code samples in the book are based on application that will be used to sell and deliver it).

Of course I want to follow best practices and use TLS (HTTPS), and this is much easier nowadays thanks to Let’s Encrypt. However, it wasn’t exactly obvious how to import the certicate provided by Let’s Encrypt into a Java/OSGi application, so I’m documenting the steps that worked for me.

Step One: Get the Certificate

This part I’m not going document in detail because it’s more than adequately documented on the Let’s Encrypt – Getting Started page. I used the “standalone” method. The subsequent steps assume that you have successfully obtained your certificate files, which will be saved under the path /etc/letsencrypt/live/[yourdomain]. The files you will find there are cert.pem, chain.pem, fullchain.pem and privkey.pem.

Step Two: Build Java Keystore

Note that this step is relevant for all Java developers, not just OSGi users.

Java applications cannot directly read PEM files; we need to generate a Java keystore file using the keytool program included with the JDK. Unfortunately keytool also can’t read PEM files directly, so we first have to use openssl to convert them to PKCS12 format:

openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem \
        -out cert_and_key.pkcs12 -name MyDomain \
        -CAfile chain.pem -caname root

You will be prompted to enter an export password. This will only be used in the next step, so it’s fine to use just password. Now we have a file called cert_and_key.pkcs12 which combines both the full certificate chain with the private signing key. Import this into a new keystore file as follows:

keytool -importkeystore \
        -srckeystore cert_and_key.pkcs12 -srcstoretype PKCS12 -srcstorepass password \
        -destkeystore letsencrypt.jks -deststorepass XXXXXX -destkeypass XXXXXXX

You now have a keystore file named letsencrypt.jks. Keep the store and key passwords safe and secret!

Step Three: Configure HTTP Service

This step is relevant to OSGi developers. I’ll assume you are using the Apache Felix HTTP Service.

The HTTP Service is configured with the standard OSGi Configuration Admin. You need to create a configuration record with a PID of org.apache.felix.http with the following settings:

org.apache.felix.https.enable true 8443
org.apache.felix.https.keystore: path/to/letsencrypt.jks
org.apache.felix.https.keystore.password: XXXXXX
org.apache.felix.https.keystore.key.password: XXXXXXX

This should be all you need to do get a green lock icon in your browser. Congratulations, you are now running a properly configured HTTPS server!

However… it’s not very secure yet. Once your site is running, I strongly recommend testing your TLS implementation using SSL Labs from Qualys. If you do this now, you will get at best a B grade.

Step Four: Getting the A Grade

One of the security warnings reported by SSL Labs is due to weak Diffie-Hellman groups. I don’t pretend to understand everything on the linked page, but fortunately the fix is easy: you just need to make sure your Java VM uses 2048-bit Diffie-Hellman keys by setting a system property. This can be specified on the command line as follows:

java -Djdk.tls.ephemeralDHKeySize=2048 ...

To achieve forward secrecy you also need to restrict the cipher suites to use only elliptic-curve algorithms. It’s also a good idea to limit the server to 256-bit rather than 128-bit algos. This is done in the configuration admin record for the HTTP Service; just add the following:

org.apache.felix.https.jetty.ciphersuites.included: \
    TLS_RSA_WITH_AES_256_CBC_SHA256, \

With these settings you should now be a grade A student:

Finally: you might be wondering how to get an elusive A+ grade on SSL Labs. Alas it doesn’t currently seem to be possible in a Java-based server (though I may be wrong – please let me know in the comments). The feature needed to unlock A+ is called TLS_FALLBACK_SCSV, and it requires an API change. Hopefully it will be implemented in Java 9.

Share This:

Vertical Components

Combining Web and OSGi Components

I consider myself a latecomer to Microservices; I only really started to understand and use them in 2005. Nobody called them “Microservices” at the time – as far as I can tell, the term was coined in 2006 by BEA for their microService Architecture (mSA). Regardless, with this history it was a little surprising to hear the term reinvented in 2014 and suddenly gain a great deal of traction. While implementation details vary, the fundamental (more…)

Share This:

Functional Transaction Management – old dog, new tricks! 3 comments

This blog post is all about the new Transaction Control service which is proposed to be part of the next release of the OSGi Enterprise Specification. Paremus has been leading this specification work, which arose from a collaboration with one of our customers, McCarthys. The current state of the RFC is available on GitHub, and there’s even an implementation available in Apache Aries.

Before we delve into the cool features of the Transaction Control service, it’s probably worth remembering why we need yet another transaction abstraction… (more…)

Share This:

The Paremus Service Fabric has no Opinions…

The emergence of the ‘Opinionated’ Microservices Platform continues apace.

We are told that business systems should be REST/Microservice based. We are told that containers should be used everywhere and container images are the deployment artefact du jour: I mean lets face it Virtual Machine Images are so last year! And of-course Reactive is the new cool.

A depressing state of affairs. These messages are at best half-truths. At worst – the IT industry’s ongoing equivalent of Snake Oil.

So (more…)

Share This:

Modularity, Microservices and Containers

My colleague, Derek Baum, had an article published in Jaxenter last week called “Modularity, MicrJaxenter Feb 2016oservices and Containers“.

The article discusses how Microservices and Containers are examples of a general industry drive towards modularity. It goes on to demonstrate how OSGi’s Service-centric approach, its Requirements & Capabilities model, and the OSGi Remote Services specification provide an excellent solution for a containerised microservices solution.

Yes thats right, these concepts/technologies/trends aren’t competing with each other as many would have you believe. In fact they can all be complimentary when used with Paremus Packager.

Paremus Packager integrates the lifecycle of external (non-Java) applications with OSGi and provides a consistent means to start, stop, configure and inter-connect services and we will be making an early access release of the new Docker-based Paremus Packager available to a restricted audience in Q1 2016.  You can sign up for this online with just your email address.

The article is a is a follow up to the presentation of the same name given at the OSGi Community Event in 2015, by Neil Bartlett [ Slides / Video ] and these are a good source of info if you would like to learn more. Of course you can also add comments below if you have any questions.

Share This: