Document SSL certificate configuration

[md5]

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.

[johncmckim]

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

[gregw]

@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

[johncmckim]

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

[md5]

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

[johncmckim]

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

[md5]

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

[johncmckim]

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

[md5]

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

[kruton]

One solution could be using Conscrypt.

[ghost]

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

[gregw]

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

[gregw]

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

[ghost]

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

[mimatn]

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.

[rvesse]

@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]

@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

[joakime]

This issue has been moved to the new Official Eclipse Jetty Docker repository.

See jetty/jetty.docker#2