Document SSL certificate configuration

[joakime]

Issue by md5
Thursday Oct 01, 2015 at 21:01 GMT
Originally opened as appropriate/docker-jetty#20

---

This should mostly just point at the main Jetty documentation on the subject, but it would probably be good to add some information about how to set up the keystore for the Docker image/container.

[joakime]

Comment by johncmckim
Wednesday Dec 16, 2015 at 21:38 GMT

---

This would be really helpful. On the main page on docker hub, there is a line that shows running a container like so docker run -d -p 80:8080 -p 443:8443 jetty. Naturally, I thought that meant SSL was configured out of the box. However, it doesn't appear to be the case?

I have tried the config below, but it doesn't seem to work. I've probably got some of the jetty-https.xml config wrong. However, is this the general idea? Something like this in the docs that shows how to do it would be really helpful.

FROM jetty:9.3

RUN keytool -genkey -noprompt \
 -alias jetty \
 -dname "CN=xxx, OU=xx, O=xx, L=xx, S=xx, C=xx" \
 -keystore /usr/local/jetty/etc/keystore \
 -storepass password \
 -keypass keyPassword

COPY jetty/jetty-https.xml /usr/local/jetty/etc/jetty-https.xml

RUN echo '--module=ssl' >> /usr/local/jetty/start.ini
RUN echo '--module=https' >> /usr/local/jetty/start.ini

[joakime]

Comment by gregw
Thursday Dec 17, 2015 at 03:26 GMT

---

@johncmckim
rather than try to assemble the SSL configuration yourself, you'd be better off using the jetty module system to configure SSL, that way you get all the configuration setup for you (other than the keystore which your setup looks good). So you need something like:

RUN java -jar "$JETTY_HOME/start.jar" --add-to-startd=https

[joakime]

Comment by johncmckim
Saturday Dec 19, 2015 at 00:36 GMT

---

Thanks @gregw that was a big help.

I couldn't get the keytool command to work correctly. I found that they keystore path should be $JETTY_BASE/etc/ketystore which is one step in the right direction. However, after this I found I was having issues with the password.

I ended up opting to add the --create-files command to your suggestion, which downloads a keystore from the jetty source for you. This probably isn't acceptable in many use cases but it is for me.

RUN java -jar "$JETTY_HOME/start.jar" --add-to-startd=https --create-files

[joakime]

Comment by md5
Saturday Dec 19, 2015 at 01:03 GMT

---

@johncmckim If you want to use your own passwords, it looks like you'd want to append settings for jetty.sslContext.keyStorePassword, jetty.sslContext.trustStorePassword, and jetty.sslContext.keyManagerPassword to $JETTY_BASE/start.d/ssl.ini.

The values for these properties could be generated using java -cp $JETTY_HOME/lib/jetty-util-$JETTY_VERSION.jar org.eclipse.jetty.util.security.Password. Be aware that this command may hang when trying to generated the crypted password if you're in a context with low entropy (e.g. in a Boot2Docker VM like I just tried to test...)

These values could be specified for your build using Docker's ARG/--build-arg functionality if you want to avoid hard-coding your passwords.

All that being said, I think in a production context you'd want to avoid generating a self-signed certificate in the Dockerfile and instead mount in an existing keystore containing your private key and certificate with --volume. In that case, I believe the passwords could be passed through to Jetty in the container as additional arguments to the main start.jar CMD.

[joakime]

Comment by johncmckim
Saturday Dec 19, 2015 at 01:15 GMT

---

@md5 I tried the jetty-util as you suggested and it hung every time so I gave up.

Mounting an existing keystore makes much more sense. I'll give that a go next week. Any examples would be appreciated.

[joakime]

Comment by md5
Saturday Dec 19, 2015 at 01:28 GMT

---

@johncmckim Were you trying in a VM? I tried that and it hung as well after printing out the "OBF" and "MD5" passwords. I believe the issue is that it's calling new SecureRandom() to generate the CRYPT password and hanging due to a lack of available entropy.

[joakime]

Comment by johncmckim
Saturday Dec 19, 2015 at 01:31 GMT

---

@md5 yes. I was using docker on my windows dev machine. It would be using Virtualbox behind the scenes correct? What you describe is exactly what happened to me. I could see the OBF and MD5 passwords but it would not exit.

[joakime]

Comment by md5
Saturday Dec 19, 2015 at 06:54 GMT

---

I opened this issue to discuss the underlying problem around a lack of entropy causing problems for java-based images: docker-library/openjdk#60

[joakime]

Comment by kruton
Thursday May 10, 2018 at 05:32 GMT

---

One solution could be using Conscrypt.

[joakime]

Comment by ghost
Sunday Mar 17, 2019 at 10:26 GMT

---

Hello eveyone,

I too have the problem of adding ssl to jetty image in docker container. I just used the below commands to add my local keystore to jetty image. any help would be highly appreciated.
ADD keystore.jks $JETTY_HOME}/etc/keystore/keystore.jks
EXPOSE 8443
RUN java -jar "$JETTY_HOME/start.jar" --create-startd --add-to-start=https,ssl

[joakime]

Comment by gregw
Monday Mar 18, 2019 at 23:37 GMT

---

@VivinrajSundararaj and what goes wrong? Does the container start? Do you get errors/logs?

[joakime]

Comment by gregw
Tuesday Mar 19, 2019 at 00:02 GMT

---

@VivinrajSundararaj FYI I was just able to start a HTTPS connector with:

docker run  -v/home/gregw/src/jetty-9.4.x/jetty-io/src/test/resources/keystore:/var/lib/jetty/etc/keystore jetty --module=https

So I can see that your keystore is incorrectly named and you have a bracket problem. Try being explict and put the keystore at /var/lib/jetty/etc/keystore

Note you don't need to add the ssl module as that is a transient dependency of https. Nor do you need to create-startd as that is already created.

[joakime]

Comment by ghost
Friday May 03, 2019 at 20:06 GMT

---

@gregw I have certificate *.pem file and I have added the file to docker container by the docker command as below

COPY my-domain.pem /etc/ssl/certs/my-domain.pem

docker run -d -p 80:8080 -p 443:8443 -v /home/deploy/backend/ssl:/etc/ssl/certs

Can you please help to provide the steps to make the ssl working in docker container in my local machine?

[joakime]

Comment by mimatn
Friday Mar 20, 2020 at 09:53 GMT

---

I had to work on this setup for work, and since I obtained something that works, maybe someone may find it useful here.

You need:

• ssl.ini and https.ini as explained in the docs
• certificates of all the intermediary CAs that you may have used, so that a complete chain to a valid root may be built. In my case, I have a private CA whose certificate is my-priv-ca.crt, and a signing CA whose certificate is my-sign-ca.crt.
• p12 archive built from the public and private parts of the server's certificate. You build it with something like openssl pkcs12 -export -name server -in server.pem -inkey server.key -out server-keystore.p12

In the Dockerfile, I copy all those files where they belong (/var/lib/jetty/start.d/ or /var/lib/jetty/etc/) and then work with the keytool to:

• build the keystore from the server's p12
• add the CA's certificates to the truststore

The ssl.ini then refers to those stores.

My Dockerfile is something like this:

FROM jetty:9.4.27-jre11-slim

RUN mkdir /var/lib/jetty/etc

COPY --chown=jetty:jetty ssl.ini /var/lib/jetty/start.d/
COPY --chown=jetty:jetty https.ini /var/lib/jetty/start.d/
COPY --chown=jetty:jetty my-sign-ca.crt /var/lib/jetty/etc/
COPY --chown=jetty:jetty my-priv-ca.crt /var/lib/jetty/etc/
COPY --chown=jetty:jetty server-keystore.p12 /var/lib/jetty/etc/

RUN keytool -importkeystore -destkeystore etc/keystore -srckeystore etc/server-keystore.p12 -srcstoretype pkcs12 -srcstorepass key -deststorepass jettyssl -alias server -noprompt \
  && keytool -import -destkeystore etc/truststore -file etc/my-sign-ca.crt -deststorepass jettyssl -alias my-sign-ca -noprompt \
  && keytool -import -destkeystore etc/truststore -file etc/my-priv-ca.crt -deststorepass jettyssl -alias my-priv-ca -noprompt

EXPOSE 8080
EXPOSE 8443

ssl.ini instead goes like this:

# Module: ssl
--module=ssl

jetty.ssl.host=0.0.0.0
jetty.ssl.port=8443
jetty.httpConfig.securePort=8443
jetty.sslContext.keyStorePath=etc/keystore
jetty.sslContext.trustStorePath=etc/truststore
jetty.sslContext.keyStorePassword=OBF:1vgd1vu91ytc1zzu20041yta1vv11vgh
jetty.sslContext.keyManagerPassword=OBF:1vgd1vu91ytc1zzu20041yta1vv11vgh
jetty.sslContext.trustStorePassword=OBF:1vgd1vu91ytc1zzu20041yta1vv11vgh

# Enable client certificate authentication.
jetty.sslContext.needClientAuth=true

Remeber that you get the obfuscated password with java -cp ./jetty-util-9.3.6.v20151106.jar org.eclipse.jetty.util.security.Password jettyssl.
Note that I needed client authentication active: disable it if your site is public.

https.ini is just:

# Module: https
--module=https

With the above setup, using:

docker  build -t ssljetty:latest .
docker run --rm -d -p 8080:8080 -p 8443:8443 --name jtty ssljetty:latest 

I have, at port 8443, Jetty serving SSL with my certificate.

I hope this is helpful.

[joakime]

Comment by rvesse
Friday Mar 20, 2020 at 11:14 GMT

---

@mimatn That's really helpful, have actually been working on something similar this last week myself and figured out much the same

One other gotcha that people should be aware of is that Jetty defaults to assuming a JKS format key store, if you are using Java 9+ as the JDK in your image then the default format becomes PKCS12 and trying to start Jetty with a Keystore in that format will produce stack traces like the following:

java.security.PrivilegedActionException: java.security.UnrecoverableKeyException: Get Key failed: Given final block not properly padded. Such issues can arise if a bad key is used during decryption.
	at java.base/java.security.AccessController.doPrivileged(Native Method)
	at org.eclipse.jetty.xml.XmlConfiguration.main(XmlConfiguration.java:1837)
Caused by:
java.security.UnrecoverableKeyException: Get Key failed: Given final block not properly padded. Such issues can arise if a bad key is used during decryption.
	at java.base/sun.security.pkcs12.PKCS12KeyStore.engineGetKey(Unknown Source)
	at java.base/sun.security.util.KeyStoreDelegator.engineGetKey(Unknown Source)
        [...]

I believe there is a Jetty setting to change the default format but since in our environment we needed to be backwards compatible to JDK 8 for the time being we added --deststoretype jks to our keytool -importkeystore commands

[joakime]

Comment by joakime
Friday Mar 20, 2020 at 15:16 GMT

---

@rvesse Jetty will just use java.security.KeyStore, which supports both JKS and PKCS12 since Java 8 (along with OS specific options as well).

https://docs.oracle.com/javase/8/docs/api/java/security/KeyStore.html