Personal tools
You are here: Home / OSCAR EMR 15 / 4.0 Developers / 4.1 Installation / 4.1.0.4 APR Production Connector

4.1.0.4 APR Production Connector

Using Certbot with the Apache Portable Runtime (APR) with Tomcat 7

4.1.0.4 Using the Apache Porable Runtime connector

Installation of Certbot and the APR connector for Tomcat7 made easy.

Preface

Document Version History

  • v1.0 – initial OSCAR 15 version published to oscarmanual.org – November 5, 2018
  • v1.1 – added Cipher suite restrictions for medium compatibility/security – November 23, 2018
 copyright © 2018 by Peter Hutten-Czapski MD under the Creative Commons Attribution-Share Alike 3.0 Unported License

 

Contents

  1. Preface
    1. Document Version History
  2. Prerequisites
  3. Installing a Certificate
  4. Installing APR Connector

Prerequisites

It is assumed that

  1. You have OSCAR running on Ubuntu 16.04 LTS Xenial (Xerus) or similar (Mint 18 etc) .
  2. You are running Tomcat7. 
  3. You have a a fully qualified domain name (FQDM) registered that you plan to use for OSCAR.
  4. You have a basic level of Linux knowledge and you can open a Linux terminal
  5. You can cut and paste EXACTLY the following instructions.
NOTE: Firefox will copy with Control+C while a Linux terminal requires Shift+Control+V for past

Load a Certificate for your OSCAR Instance

Option 1: Using a Self Signed Certificate

Only use this option if you don't have an official website (you don't have a Fully Qualified Domain Name) and you need to obtain a certificate that Open SSL can use with the APR connector.  Your users will be bothered with browser warnings that your OSCAR instance is "untrusted"

Write down the Common Name (CN) for your SSL Certificate. The CN is the fully qualified name for the system that uses the certificate. If you are using Dynamic DNS, your CN should have a wild-card, for example: *.api.com. Otherwise, use the hostname or IP address (for example. 192.16.183.131 or dp1.acme.com).

Run the following OpenSSL command to generate your private key and public certificate. Answer the questions and enter the Common Name when prompted.

openssl req -newkey rsa:2048 -nodes -keyout privkey.pem -x509 -days 365 -out cert.pem
Review the created certificate: 
openssl x509 -text -noout -in cert.pem

Install the files into a location and with file ownership accessible to Tomcat. 

sudo cp *.pem /etc/tomcat7/
sudo chown tomcat7:tomcat7 /etc/tomcat7/*.pem

Option 2: Optain a Certbot Certificate for your FQDN

Certbot will register your server with Lets Encrypt so that external browser access to the OSCAR will be with a green padlock for a trusted connection.  If you don't want have a fully qualified domain name or you don't want to leave port 80 open to the outside world OSCAR will need to be configured with a self signing certificate for internal use (see option 1 above).

Certbot is available natively in Ubuntu 18.04, but older distros will need to install a ppa.  To install certbot from the ppa execute the following

sudo apt-get install software-properties-common
sudo add-apt-repository ppa:certbot/certbot
sudo apt update
sudo apt install certbot
Certbot needs to communicate on port 80 to authenticate.  Stop any services that bind to port 80 (apache2 nginx others). You may need open port 80 on your router and forward that port as port 80 on your server.  Those instructions vary by server.  In the following replace FQDM with your the fully qualified domain name that you own (eg www.example.org)
sudo certbot certonly --standalone -d FQDN
Follow the prompts.  If successful you will get output similar to 
IMPORTANT NOTES:
 - Congratulations! Your certificate and chain have been saved at:
   /etc/letsencrypt/live/www.example.org/fullchain.pem
Test by checking if there are files as below
sudo ls /etc/letsencrypt/live/www.example.org
cert.pem  chain.pem  fullchain.pem  privkey.pem  README

Certificate Installation

Install the files into a location and with file ownership accessible to Tomcat.  The following assume that the certificates were generated by Certbot.
sudo su
cp /etc/letsencrypt/live/FQDN/*.pem /etc/tomcat7/
chown tomcat7:tomcat7 /etc/tomcat7/*.pem

Certbot Renewals

Lets Encrypt certificates expire after 90 days.  To renew you need to stop any services that might be binding to port 80 (eg apache2) and stop Tomcat.  You can automate Certbot renewals with a file similar to the following
#!/bin/bash
#
# /usr/share/oscar-emr/letsencrypt.cron
#
# a script file for OSCAR that updates certbot generated certificates
#====================================================================
#   Copyright Peter Hutten-Czapski 2018 released under the GPL v2
#====================================================================
#
certbot renew --pre-hook "service tomcat7 stop"
cp /etc/letsencrypt/live/www.example.com/*.pem /etc/tomcat7/
chown tomcat7:tomcat7 /etc/tomcat7/*.pem
service tomcat7 start
Don't forget to 
sudo chmod 711 /usr/share/oscar-emr/letsencrypt.cron
and run it with crontab.  The settings are sane in so far that the hook that stops tomcat is only run if the certificate is within 30 days of expiry (running the script weekly is plenty)
 

APR for Tomcat 7

Apache Portable Runtime

These instructions install the production connector called APR that uses OpenSSL rather than Java to encrypt.  This is faster and also allows for installing certificates that are not self signed.  First get the library needed
sudo apt-get install libtcnative-1
While that installs the needed library, you also need to make a link to where tomcat7 will be looking for it.  
sudo ln -sv /usr/lib/x86_64-linux-gnu/libtcnative-1.so /usr/lib/
Change the properties for Tomcat to active the connector.  Ensure that the connector listener is uncommented
<Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />
Adjust the connector to the following or similar.
Assumptions:
  • maxThreads are set for 4 core processor on the server or better
  • Ciphers are set for client browsers in the following (or newer)
  1. Firefox 31.3.0+ ESR
  2. Chrome 49+
  3. Safari 5.1.9+
  4. Android 4.0.4+
  5. BlackBerry Tablet OS (QNX) 2.1
  6. IE 7 /  Edge 15 (Note that only some OSCAR functions work in IE and Edge)
<Connector port="8443" 
                 maxThreads="800"
                 disableUploadTimeout="true"
                 scheme="https" secure="true"
                 SSLEnabled="true"
                 SSLCertificateFile="/etc/tomcat7/cert.pem"
                 SSLCertificateKeyFile="/etc/tomcat7/privkey.pem" 
                 SSLCertificateChainFile="/etc/tomcat7/chain.pem" 
              SSLCipherSuite="HIGH:!aNULL:!eNULL:!EXPORT:!DES:!RC$:!MD5:!kRSA"
 />
For greater compatibility (particularly earlier androids) consider 
SSLCipherSuite="ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:ECDHE-ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS"
NOT TESTED:  For the most secure TLS 1.2 connections (but least compatible) use
SSLCipherSuite="ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256"
On restarting tomcat you can tail /var/lib/tomcat7/logs/catalina.out and get confirmation that the APR connector is loaded
INFO: Loaded APR based Apache Tomcat Native library 1.1.33 using APR version 1.5.2.
Nov 05, 2018 12:46:48 PM org.apache.catalina.core.AprLifecycleListener lifecycleEvent
INFO: APR capabilities: IPv6 [true], sendfile [true], accept filters [false], random [true].
Nov 05, 2018 12:46:48 PM org.apache.catalina.core.AprLifecycleListener initializeSSL
INFO: OpenSSL successfully initialized (OpenSSL 1.0.1f 6 Jan 2014)
Nov 05, 2018 12:46:48 PM org.apache.coyote.AbstractProtocol init
INFO: Initializing ProtocolHandler ["http-apr-8443"]
Nov 05, 2018 12:46:48 PM org.apache.catalina.startup.Catalina load
 

Document Actions