PicoStack: Website Certificates

Your website will need a certificate if you want to use TLS to encrypt traffic so that it cannot be intercepted and read -- or worse, modified -- as it flows from a browser to your picos and vice versa.

If you elect to use TLS, the browser will show your visitors that your website is "safe"^* because your URLs will be able to use the HTTPS protocol, rather than the unencrypted HTTP protocol.

To use TLS, you need a certificate which offers proof that you control the web server which hosts your picos and hence your website. A certificate authority will issue you such a certificate after verifying that you do indeed control the web server.

For more detailed information on website certificates, see the article "Understanding Website Certificates" published by the U.S. Federal Government's Cybersecurity and Infrastructure Security Agency (CISA). The article "Protecting Your Privacy," from the same agency, contains more general information. Both articles are directed at consumers, but you, as a website developer using PicoStack, will want to be sure to present a website that feels safe to your visitors.

The rest of this post assumes that you will be hosting your application on an AWS EC2 instance.

Install and start the pico engine

You may have already done this to implement sample code from previous posts. If not, follow the instructions in the README.md file in the pico-engine repo. You will install the pico engine and start it through a secure shell (ssh) connection to the server. To do that you'll have to open port 22 for whatever IP address you are working from. Because you will eventually be done with the shell, you'll need to use something like forever to start the pico engine so that it doesn't stop when you exit the shell.

You can then use the pico engine from the IP address assigned by AWS. We recommend obtaining an elastic IP address, so that it won't change when you have to bounce the server.

Finally, you will need to change the inbound security settings for your EC2 instance to allow direct traffic from the outside world on port 3000 (the default port on which the pico engine listens).

Use nginx

The pico engine does not support TLS, as it is written to provide an HTTP server to transport events and queries to your picos. So, we recommend using nginx as a wrapper around the pico engine. A simple configuration file might look something like this:

http {
  server {
    location / {
      root /data/www;
      index index.html;
    }
    location /images/ {
      root /data;
    }
  }
}

This will allow you to serve static content (on port 80) as well as run the application you are developing for your picos (on port 3000). All you'll have to do is place your static content (including your index.html file) in the /data/www folder on your server. Images could go directly into the /data folder, but be referenced in the src attribute of your img tags as "/images/image1.png" etc.

With nginx running, browsers visiting your IP address will pick up your static content, because it will respond to requests on the standard HTTP port 80.

Your picos will still be available on port 3000 as before, because nginx is not listening on that port, but the pico engine still is.

Use a custom domain name

You will need to register a domain name for use with your PicoStack application. Once that step is complete, and you have set the DNS entries to point at your (elastic) IP address, you can begin using the domain name instead of that IP address to access your picos.

If your site will be using a subdomain inside of an institutional domain where you work, you'll need to use internal processes to request a subdomain and provide your elastic IP address to your institutional DNS zone.

Now that you have a domain name, you will want to restart your pico engine, so you can specify the domain name in the PICO_ENGINE_BASE_URL instead of the IP address, as shown in this comment.

Obtain a certificate

To get a certificate you have to be in control of your server. Any other information you provide, and which will be displayed on the certificate, is whatever you want your visitors to see, and its accuracy is not verified by the certificate issuer.

You will need to work with a certificate authority to do this. A cost is often involved, but your certificate will be valid for a longer time, generally one year, at which time you'll have to again verify that you control the server at your domain name.

We recommend using Let's Encrypt which provides certificates at no cost. Note that they will expire and have to be renewed every two to three months.

Install your certificate

We recommend using the certbot program to obtain and install the certificate. Since you are using nginx, it makes sense to have it do this for you, as illustrated in the experience report starting with this comment.

Adapt your nginx configuration

You will want requests to your picos to use the certificate (and HTTPS) as well, so you'll have to instruct nginx to proxy requests from a different port to your pico engine. We used port 8080 for this purpose, with this configuration setting:

  server {
    location 8080 ssl;
    location / {
      proxy_pass http://localhost:3000;
    }
    # certificate lines as injected by Certbot
  }

This means that requests made to a pico using https://your.domain.name:8080 will be passed along as plain HTTP requests to your actual pico engine which runs locally (to your EC2 instance server) on port 3000.

The certbot program will modify your nginx configuration file, adding lines with certificates, and adding a listener on port 443^** (the default port for HTTPS). Notice that you'll also need to copy the certificate lines from the server entry that listens on port 443 into the place shown as a comment above, as in these lines, for example.

Now you will also need to restart your pico engine with PICO_ENGINE_BASE_URL using the externally visible port 8080, as suggested in this comment.

Finally, you should change the inbound security settings for your EC2 instance to no longer allow direct HTTP traffic from the outside world on port 3000.

Get people to use your application

This is actually the hardest problem. Good luck!

Presenting your website using HTTPS is a great start, as people tend to mistrust sites which do not do so.

Notes

^* The word "safe" is in quotes because TLS only ensures that traffic to your site is encrypted. You will have to be trustworthy in what you do with that traffic in order to build a reputation for being a site worth visiting.

^** In order for your server to receive requests on port 443, you will have to open that port up to the world in your EC2 inbound security settings aka firewall.

PicoStack

Website Certificates