Configure Valid SSL Certificates

Overview

SSL Certificates (or Certs) will help in securely transferring the data from client to the server.  Web Applications use the SSL certificates to encrypt the traffic between client and server.  If the application is not configured with a valid SSL Certificate, we will see a message "Your connection is not private" on the browser. Also, it will be much easier for others to break in to your data.

Let's Encrypt

Let's Encrypt is a certificate authority which is free, open and automated.  It provides a CLI tool to generate certificates by validating the domain in an automated fashion.  The code is open sourced and can be found here.  It has various modes/plugins in which it can operate.  The details can be found here.  We have used Standalone plugin to generate the certificate for Bahmni.

Process of Generating SSL Certs

We need a valid domain before we start generation of certs.  The process is outlined below:

Summary: Overall, the idea is that LetsEncrypt will create a certificate for your domains/sub-domains, only if it knows with certainty that you control those domains. For it to verify that you control the domains, you need to run the letsencrypt command line program from an IP address where the domains are mapped. This way, when the LetsEncrypt command contacts the LetsEncrypt servers, with your domain names, there is a handshake sent back by the server to the domain, which should be received back to the client (which is itself). This way, the client program knows that since the request for "X" domain, came back to itself, the client is being run by the person who controls the domain "X".

  1. Buy a domain from bigrocks or godaddy (or similar website).  Here we bought bahmnidev.org.
  2. Spin up a server in the cloud (which can be accessed through the internet via a public IP).  One options is to create a Digital Ocean droplet. These instructions will go through if you created the certificate in this droplet (a separate server from the one hosting Bahmni) or if you did it in the machine where you will be running Bahmni.
    1. One reason to use a droplet is if your Bahmni instance will not be exposed to the internet, and will instead be accessible only via LAN within the hospital premises. In such cases, it is still recommended to use HTTPs connection for security. If so, then you will need to obtain SSL certificates using an the droplet, and then create an internal DNS entry for something like "emr.hospital.org" in your local router.
  3. Manage your DNS entries in your hosting provider (bigrocks, godaddy, or whoever you chose) by associating the Bahmni server's public IP address with multiple sub-domains.  For example, we created multiple A Records like dev.bahmnidev.org, dot10.bahmnidev.org, dot6.bahmnidev.org, local.bahmnidev.org etc all pointing to the same public IP where we will run the letsencrypt program.
  4. Access the droplet or Bahmni server using SSH, go to the /etc directory and and clone the letsencrypt git repo.

    cd /etc
    sudo git clone https://github.com/letsencrypt/letsencrypt
    cd letsencrypt
  5. Run the following command from the cloned directory. It will ask for an email address at the time of certificate generation.  

    # Note that the first domain/subdomain passed as -d becomes the main folder structure / name in the certificate. So, good to give the topmost level as the first option
    ./letsencrypt-auto certonly --standalone -d dev.bahmnidev.org -d dot10.bahmnidev.org --debug
  6. Ensure that the 443 port is free & open.  You can do this by telneting to that port or you can use an online tool like  http://www.yougetsignal.com/tools/open-ports/ (enter dev.bahmnidev.org and port 443 and you will see its open)
    1. This program starts up a server and listens on 443 port.  It issues a request to ACME server hosted by the Let's Encrypt folks.  They will send another request to the specified domain (here https://dev.bahmnidev.org).  The started up program will send back a response.  If the response is proper, the domain validation will be successful.
  7. Once the letsencrypt domain validation is successful, it will generate the SSL certificates at the location /etc/letsencrypt/live/dev.bahmnidev.org/
  8. Place the certificate in the correct location.
    1. If you created the certificate in a droplet, copy over the complete letsencrypt folder as-is from /etc/letsencrypt to your Bahmni instance where Apache httpd will be running. Place it in the /etc folder on your server.
    2. If you did it in the same server, no need to do anything.
  9. Configure these settings in the /etc/httpd/conf.d/ssl.conf of Apache httpd

    SSLCertificateFile /etc/letsencrypt/live/dev.bahmnidev.org/cert.pem 
     
    SSLCertificateKeyFile /etc/letsencrypt/live/dev.bahmnidev.org/privkey.pem 
     
    SSLCertificateChainFile /etc/letsencrypt/live/dev.bahmnidev.org/chain.pem
  10. Once the certs are configured, we can now change back our DNS settings on the hosting provider to point back to the original domains where we want to host Bahmni.  Now accessing https://dev.bahmnidev.org/home will forward the urls to the correct servers, which have SSL certificates configured with the same name. Not, that your browser needs to access the Bahmni servers with the same "domain" entries in the URL, which you used to generate the certificates for. If the DNS entries are not available in the public DNS servers, or your local DNS, then you will need to make these entries in your local /etc/hosts file.
    1. The browser (or any certificate reader app) will show you which DNS entries have been signed for in the certificate. See this: http://pasteboard.co/mVhwFcB.png. The following command should work on Linux: http://serverfault.com/questions/425427/listing-domains-on-a-ucc-san-ssl-certificate. This way one can make sure that all the domain (and sub-domains) that were requested in the certificate, are actually present in the certificate.

Notes

  1. LetsEncrypt only gives 90 day validity certificates: https://letsencrypt.org/2015/11/09/why-90-days.html. If you dont renew after 90 you will get the same "Your connection is not private" warning

Configuring the developer machine if you want to use these certificates on your Vagrant box

  1. SCP the certificates at this location (/etc/letsencrypt/live/dev.bahmnidev.org) - A copy has been kept for you on our .10 boxes in the same location.
  2. Place it in the same location on your vagrant box.
  3. Update the ssl.conf (available at /etc/httpd/conf.d/ssl.conf) with the changes mentioned in Step 9 above.
  4. Make entries for dev.bahmnidev.org in your /etc/hosts
  5. Access the URL -> https://dev.bahmnidev.org/bahmni/home

References

A Blog post on Free SSL/TLS Certificates using LetsEncrypt

The Bahmni documentation is licensed under Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)