This is an AWS Marketplace only feature.

Overview

The HTTP protocol, commonly used for message exchange over the internet, does not provide encryption or authentication. As a result messages exchanged with this protocol may be insecure and subject to eavesdropping, and their source may be uncertain. To avoid this problem, HTTP is frequently combined with an encryption scheme known as SSL, or more recently TLS, that can be used to keep messages safe from unauthorized access, and verify that the sender is who they claim to be. This secure protocol is called HTTPS.

This document provides information about HTTPS and its setup that applies to all of the AWS Kill Bill architectures.

HTTPS is based on the use of a verification document called a certificate. the certificate serves two purposes:

  1. It provides the keys necessary for a highly secure encryption.

  2. It provides the electronic signature of a certificate authority (CA) who guarantees the identity of the sender.

Increasingly, modern browsers require valid certificates when accessing sites using the HTTPS protocol. It may be difficult or impossible to access these sites if a valid certificate is not found.

The structural details of certificates are defined by international standards and are well beyond the scope of this discussion. For more details see the Wikipedia article. One thing you need to understand, though, is the certificate authority. Normally this is either an organization that is intrinsically well-known and trusted, such as DigiCert or GlobalSign (called a root CA), or an organization in the trust hierarchy derived from a root. A CA in a trust hierarchy must be itself certified by another CA in a chain which eventually leads to the root CA. Your CA, in turn, must be able to certify that you are who you say you are!

For temporary use, you can sometimes create a self-signed certificate, in which you are your own CA. Most browsers will frown on this, since you are simply vouching for yourself, but it may allow you to get started with security.

If you own a domain, your domain provider can serve as your CA. If you don’t have a domain, you can purchase one for very low cost from a domain provider such as Godaddy. When you obtain a domain you need to prove your identity, so your domain provider can trust you. To demonstrate this trust you will need a CNAME.

Preliminary concepts

CNAMEs

A CNAME, or Canonical Name, is an identifier that links your CA to the resources that you are protecting with your certificate. You will be protecting public access to your instances of KAUI and Kill Bill through your load balancer, identified by its DNS name. The CNAME will link your domain to the load balancer. If your domain is mydomain.com your CNAME might look like kaui.mydomain.com. This will direct browsers to your verified domain, and then, through your CNAME, to your AWS resources.

The CNAME is part of your domain’s DNS profile, and your domain provider should have instructions for setting it up.

Protocol and Port Setup

Your AWS security group by default provides rules giving access to KAUI and Kill Bill using the HTTP protocol and a specified port number. For HTTPS you will need additional rules with the new protocol and a new port number.

Validation

When you create a new certificate, unless you are acting as your own CA, you will need to validate your certificate. This identifies the trust hierarchy for the certificate. You may need to setup a temporary CNAME for this purpose, and you may need to provide temporary access via an extra port in your security group.

Obtaining a Certificate

There are many ways to obtain a certificate that you can use to protect a particular resource. Here we will describe three that may be of use in particular Kill Bill scenarios running on AWS. These are:

  1. Creating a self-signed certificate

  2. Using the AWS Certificate Manager

  3. Using the free CA Let’s Encrypt

Self-Signed Certificates

The quickest and easiest way to create a certificate is to sign it yourself. In this way you become your own CA. A self-signed certificate should be considered temporary. It will provide encryption, but it cannot prove the identity of your service because you are vouching for yourself. Most browsers will complain or require extra steps to use your system, and some may not allow its use at all.

Since you are acting as your own CA, a self-signed certificate does not require a CNAME. One simple way to create a self-signed certificate is to use the free command line program openssl. This program is usually preloaded in Linux and Macintosh environments, and can be downloaded for Windows.

First, open your terminal or command application, if necessary, and type openssl version to be sure the program is available. If not, you will need to download it first.

Next, type the following command:

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout privateKey.key -out certificate.crt

This will bring up a series of questions about your identity, such as name, address, phone, etc. This information becomes a part of your certificate. You can ignore most of these by typing enter. Then type:

openssl rsa -in privateKey.key -text > private.pem
openssl x509 -inform PEM -in certificate.crt > public.pem

This will create two files that are necessary for encryption.

Finally, follow the instructions for your Kill Bill system type to copy these files to your certificate. When copying private.pem, remove all text prior to "-----BEGIN RSA PRIVATE KEY-----". Then install your certificate in your system.

Using the AWS Certificate Manager (ACM)

The AWS Certificate Manager (ACM) offers a straightforward way to provide SSL/TLS protection for AWS resources such as load balancers. This is most appropriate when using the multi-tier or cloud formation installation options. There is no extra cost for using ACM certificates.

1. Request a Certificate

If you are on a page that is asking for your certificate, click on Request a new Certificate from ACM. Otherwise, select ACM from the Services menu. You will be taken to the main page of the ACM. Initially this will probably show that you have no certificates. Click Request a Certificate.

The next page will give you the option to import a certificate, or to request a public or private certificate. Choose private, then click again on Request a Certificate. This will take you to the Request a Certificate page. You are initially at Step 1: Add Domain Names.

ELB request certificate

2. Setup a CNAME

To validate your certificate, you must first setup a temporary CNAME. The values to use for the CNAME will be seen shortly. You will then create the CNAME that you will actually use to access the system.

Enter your domain name, using the wildcard format. Then click Next. On the following page, select DNS Validation. The next page gives you the chance to assign one or more tags to your certificate. These are optional and can be skipped. Finally, you are given a chance to review your request. Check everything, then click Confirm and Request. The Validation page will appear.

ELB cert validation 1

At the bottom you will see your domain name with a status of Pending Validation. Click the triangle next to your domain name. The display will expand to show the values that you must use to create your validation CNAME.

ELB cert validation 2

The two strings labeled Name and Value should be copied to the two required entries for your CNAME. Copy these long strings carefully. Do not include any trailing periods. There is an option to save these strings in a file so they may be copied more easily, or stored for a later time.

Your second CNAME is much simpler. The first entry will be kaui. The second entry will be simply your domain name, e.g., mydomain.com.

3. Create and Validate your Certificate

When your CNAMEs are set, return to ACM and click Continue. The display changes to show that your certificate is Pending Validation. The certificate should now appear also on the main ACM page. When (and if) it is validated, the status will change to Success. This may take several hours or more. A short time later it will change again to Issued.

When your certificate is successfully created, you may delete the temporary (validation) CNAME.

Using Let’s Encrypt (with Certbot)

Let’s Encrypt is a root CA that is free to use. Certificates based on Let’s Encrypt can be created using the application certbot. This approach is useful when using a third-party load balancer like nginx, which cannot be protected with ACM certificates. Let’s Encrypt can be used free of charge.

Certbot is pre-installed in the latest Kill Bill AMI, but if you need a different version of certbot, this is also available through the new package manager snap. This package manager is also preinstalled in the Kill Bill AMI.

To setup a certificate using certbot, perform the following steps. This discussion assumes you are using nginx:

1. Create a CNAME

Create a CNAME, following instructions from your domain provider. You will be asked to provide two items of information. The first is simply kaui. The second is the Public IPV4 DNS name for your EC2 instance, for example, ec2-3-238-230-120.compute-1.amazonaws.com. Note that the IPV4 address alone will not work.

2. Add your CNAME to the nginx configuration file

This step tells nginx to forward HTTPS traffic via your CNAME.

First, login to your EC2 instance.

Next, using a text editor of your choosing, edit the file /etc/nginx/sites-enabled/killbill.conf. You will need to use sudo to edit this file.

This file contains two server blocks. The second block contains the lines:

server {
    listen 443;
    server_name _;

Replace the underscore after server_name with your CNAME:

server {
    listen 443;
    server_name kaui.mydomain.com;

Save the modified file, then reload it with the following command:

sudo nginx -s reload

3. Enable HTTP on port 80 (temporarily)

Go to your EC2 dashboard and add a new inbound rule to your security group as follows: Type: HTTP, Protocol: TCP, Port Range: 80, Source: 0.0.0.0/0. Your inbound rules should now look like this:

single ami inbound port 80

This is just to allow certbot to create your certificate. After the certificate is created, we recommend that you remove this rule to maintain security.

4. (Optional) Update the certbot package

First, remove the existing certbot package by typing the command:

sudo apt-get remove certbot

When asked if you want to proceed, type Y for yes.

Next, install the latest version of certbot using snap, and link it to the /usr/bin directory:

sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot

5. Create and Install the Certificate

Run certbot using the following command:

sudo certbot --nginx

Respond to any questions that are asked. If all goes well, you will see a message like:

IMPORTANT NOTES:
 - Congratulations! Your certificate and chain have been saved at:
   /etc/letsencrypt/live/deployment.killbill.io/fullchain.pem
   Your key file has been saved at:
   /etc/letsencrypt/live/deployment.killbill.io/privkey.pem
   Your cert will expire on 2021-07-11. To obtain a new or tweaked
   version of this certificate in the future, simply run certbot again
   with the "certonly" option. To non-interactively renew *all* of
   your certificates, run "certbot renew"

If the message does not appear, review the above steps carefully. If needed you can also try the certbot help page.

Testing and Renewal

When your certificate is installed, you should be able to access KAUI from you browser using https:// followed by your CNAME as the address. The browser should indicate that the site is secure.

When your certificate is successfully installed, you can edit your security groups again to remove the access through port 80.

The Let’s Encrypt certifcates are only valid 90 days and will therefore neeed to be renewed. certbot will create a cron entry under /etc/cron.d/certbot to make this process automatic.

The ACM certificates will renew automatically.