Skip to content

HTTPS Setup with Lets Encrypt

Jump to bottom
rrowlands edited this page Jul 19, 2022 · 11 revisions

 

I will start by recommending that you do all of this in a new working directory, which for example I have created at C:\ssl-working. When you open a command line prompt, you should execute most of your commands from this directory.

Prerequisites

This guide requires the installation and setup of a few pieces of software. Additionally, we will be setting some command line variables here which will be referenced in the rest of the document. If you re-create your command prompt for any reason you will need to set these environment variables again. The keystore password here is specified in this guide as changeit. It is recommended that you use a different password.

  1. Execute this guide on a Windows computer with an existing DDMS installation.

  2. You must first have a domain.

    • To obtain one you will need to visit a domain name registrar. That is outside the scope of this document. This guide also assumes that you are not trying to set up a wildcard cert.

    • Also make sure that the domain is pointing to the static IP address of the server and that your server has the appropriate firewall routing such that it is accessible for public HTTP/HTTPS requests (this will be necessary for the letsencrypt server to verify that you own the domain).

    • Once you have a domain, set your domain to a command line environment variable

      SET DOMAIN=yourdomain.xyz

  3. Set a command line environment variable to your email address. This should be the email address for a technical support staff in your organization. Ideally this should be set to a 'virtual' email address which is forwarded to many different people (e.g. [email protected]).

    SET [email protected]

  4. We highly recommend downloading the latest version of the Java SDK for use in creating these SSL keys. This is because it must have all of the current authenticated keys.

  5. Download acme_client.jar. This guide was designed to work with version 3.0.1.

  6. Install OpenSSL.

  7. If you encounter any errors when generating your certificates, a log file may be generated in C:\var\log\acme\acme.log. You may look at this log file for more information, and if you're asking your support staff for help be sure to include this log file!

Generate and Download PEM Certificates

If you encounter problems you may refer to the troubleshooting guide here.

  1. Generate account key. This only needs to be done once for all SSL certs across your entire organization.

    • C:\ssl-working\GnuWin32\bin\openssl.exe genrsa -out C:\ssl-working\account.key 2048

  2. Copy the default cacerts keystore included in the jdk to the ssl-working directory.

    • copy C:\ssl-working\jdk\jre\lib\security\cacerts cacerts.jks
    • If Windows says the file does not exist, this file may also be located at C:\ssl-working\jdk\lib\security\cacerts

  3. Generate the private/public certificate in the keystore with the CN of the domain. The validity parameter here may be adjusted if you would like to change how long your domain key is valid. We have specified it to be valid for one year.

    • C:\ssl-working\jdk\bin\keytool -genkeypair -alias %DOMAIN% -keyalg RSA -validity 365 -keysize 2048 -keystore cacerts.jks -dname CN=%DOMAIN% -storepass changeit
    • If it asks for a key password hit enter

  4. Generate a certificate signing request (CSR):

    • C:\ssl-working\jdk\bin\keytool -certreq -alias %DOMAIN% -keystore cacerts.jks -file %DOMAIN%.csr -storepass changeit -ext san=dns:%DOMAIN%
    • A file named %DOMAIN%.csr should now exist in C:\ssl-working

  5. Register your CA user account (notice that we agree to Subscriber Agreement but it is suggested to read it before agreeing):

    • C:\ssl-working\jdk\bin\java.exe -jar acme_client.jar --command register -a account.key --with-agreement-update --email %EMAIL%

  6. Request a certificate order and download HTTP01 challenges:

    1. Create the directories:

      • mkdir C:\ssl-working\workdir
      • mkdir C:\ssl-working\well-known
      • mkdir C:\ssl-working\well-known\acme-challenge

    2. Order the certificate

      C:\ssl-working\jdk\bin\java.exe -jar acme_client.jar --command order-certificate -a account.key -w ./workdir -c ./%DOMAIN%.csr --well-known-dir ./well-known/acme-challenge --one-dir-for-well-known

    3. Command should return

      ("status":"ok")

      and

      C:\ssl-working\well-known\acme-challenge

      should have a file with a randomly generated name in it.

  7. Copy the challenge file to the tomcat webserver

    1. mkdir C:\MDSS\tomcat\webapps\ROOT\.well-known
    2. mkdir C:\MDSS\tomcat\webapps\ROOT\.well-known\acme-challenge
    3. copy C:\ssl-working\well-known\acme-challenge\* C:\MDSS\tomcat\webapps\ROOT\.well-known\acme-challenge\*
    4. Verify that file exists: C:\MDSS\tomcat\webapps\ROOT\.well-known\acme-challenge\RANDOM_FILE_NAME

  8. Next we must tell the server to accept HTTP requests on port 80

    • Open this file with a text editor: C:\MDSS\tomcat\conf\server.xml. Add this new http connector directly below the existing 8080 connector in the file.

      <Connector connectionTimeout="20000" port="80" protocol="HTTP/1.1" />

  9. Verify the challenges for our csr

    1. Open port 80

    2. Boot your DDMS server (using the manager). If your server is already running you may ignore this.

    3. Verify that this url can be hit from an external network

      http:// (your_url_here) :80/.well-known\acme-challenge\ (your RANDOM_FILE_NAME here)

    4. Verify the domains. This will cause our certificate authority (Let's Encrypt) to execute a GET request against our DDMS server and request that randomly generated filename (which we just tested in the previous step).

      C:\ssl-working\jdk\bin\java.exe -jar acme_client.jar --command verify-domains -a account.key -w ./workdir -c ./%DOMAIN%.csr

  10. Generate certificate and download it

1.  `mkdir certdir`
2.  `C:\ssl-working\jdk\bin\java.exe -jar acme_client.jar --command generate-certificate -a ./account.key -w workdir --csr %DOMAIN%.csr --cert-dir certdir`
3.  You should have pem files in

    `C:\ssl-working\certdir`

Import the Certificate into the Keystore

  1. Add the Let's Encrypt intermediate certificate to the keystore.

    If it asks you to "trust the certificate?" type yes and hit enter. It should respond with "Certificate was added to keystore".

    1. Download the Let’s Encrypt X3 Intermediate from https://letsencrypt.org/certs/lets-encrypt-x3-cross-signed.pem.txt to C:\sslworking\letsencrypt.pem

    2. Import the intermediate certificate into the keystore.

      C:\ssl-working\jdk\bin\keytool.exe -importcert -alias LE_INTERMEDIATE -keystore cacerts.jks -storepass changeit -file .\letsencrypt.pem

  2. Import the signed certificate chain into the keystore

    C:\ssl-working\jdk\bin\keytool.exe -importcert -alias %DOMAIN% -keystore cacerts.jks -storepass changeit -file .\certdir\fullchain.pem

  3. (Optional) You may verify that the certificates were added to the keystore by

    C:\ssl-working\jdk\bin\keytool.exe -list -keystore cacerts.jks -alias %DOMAIN%

Setup Tomcat to Use the Keystore

Once the user has a signed keystore it is pretty easy to setup tomcat to use HTTPS.  In the DDMS manager make sure the server is stopped.  Then from the Menu select Configuration -> Server Settings.

  1. Check Enable HTTPS. 
  2. For the keystore location set it to C:/ssl-working/cacerts.jks
  3. For the keystore alias type in the name of the alias for the signed certificate in the keystore. You specified this in the DOMAIN environment variable as part of the prerequisites section of this documentation.
  4. For the keystore pass type in changeit.

Start Tomcat.  If you access the server from localhost or 127.0.0.1 your web browser will say the certifcate is invalid because the certificate is for the domain name and not localhost.

Backup Critical Files

Throughout this process we have generated some critical files that should be backed up to prevent loss of critical data should your hard-drive fail. The following files are critical and data-redundency (backup) procedures should be followed to ensure their integrity:

  1. account.key
  2. cacerts.jks
  3. %DOMAIN%.csr
  4. The certdir directory

Switching Back to HTTP

Switching back to HTTP is easy.

  1. Just open the manager and uncheck Enable HTTPS.
  2. Clear your browers cookies for the domain and localhost.  When HTTPS is enabled tomcat sends session cookies which can only be overwritten by HTTPS cookies.  When the server is switched back to HTTP it will not be able to overwrite the session cookies, so they need to be manually removed.

Renewing

This certification renewal process must be repeated every 60-90 days as per limitations of the letsencrypt CA. The certificate expires within 90 days, however you have 30 days to renew the certificate. You may check the status of your certificate by visiting your DDMS server (with HTTPS enabled) and using your web browser to view the certificate. To renew your certificate, follow these steps:

  1. Run this guide on the same Windows computer that you originally set your cerfiticate up. Open a command line and set the environment variables that are documented in the Prerequisites section.

  2. Delete these directories

    • rmdir /s /q C:\ssl-working\workdir
    • rmdir /s /q C:\ssl-working\well-known
    • rmdir /s /q C:\MDSS\tomcat\webapps\ROOT\.well-known

  3. Shutdown your DDMS webserver if it is currently running. If your server is currently using HTTPS, open the manager settings and disable it. This will be required when verifying the domain in a later step.

  4. If you have not already archived your old cert directory, you may do so now by renaming it with the old certificate's expiration date.

    • For example:

      rename certdir certdir-10-1-2019

    • If you need to perform any data-redundency backup on this archived file do so now.

  5. Follow steps 6-10 in section Generate and Download PEM Certificates

  6. Follow steps 2-3 in section Import the Certificate into the Keystore (skip step 1).

  7. If your server is running, shut it down. Open the manager settings again and enable HTTPS. Your old settings should still be there and should work fine (if not, re-enter them).

  8. Boot your server and then connect to it with a browser. Verify that the certficiate expiration date has been updated.

  9. Perform any necessary data backup procedures as documented in the Backup Critical Files section.

You may also use this script to somewhat automate the renewal process:

https://github.com/terraframe/DDMS/blob/master/build/ssl-renew.bat

ODK Quirks

ODK may not work out of the box with SSL / HTTPS. If you have issues with submitting form data, or if you run into an issue while changing a user's password using the ODK management UI, the root cause is that sometimes ODK will forward you back to HTTP even though you're using HTTPS. To fix this issue, open the file C:\MDSS\tomcat\webapps\IndiaddmsMobile\WEB-INF\classes\security.properties and change the following settings:

security.server.secureChannelType=REQUIRES_SECURE_CHANNEL security.server.channelType=REQUIRES_SECURE_CHANNEL

References

  1. Java ACME Client Documentation
  2. Lets Encrypt (Our Certificate Authority) Website"
  3. Tutorial for using Java with LetsEncrypt
  4. ACME Client Documentation for Multiple Domains
  5. ACME Documentation for renewing a certificate

DDMS

Clone this wiki locally