SSL certificates
Overview
HTTPS prevents network attackers from observing or injecting page contents. This is desirable for server applications like RaspAP — or indeed any locally hosted web application. But HTTPS requires TLS certificates, and while deploying public websites is largely a solved issue thanks to the ACME protocol and Let's Encrypt, local web servers still mostly use HTTP because no one can get a universally valid certificate for localhost.
Locally trusted certificates
Managing your own Certificate Authority (CA) is the best solution, but this usually requires an involved manual setup routine. An excellent solution for local websites is mkcert. This is a zero-config tool for making locally-trusted certificates with any name you like. mkcert automatically creates and installs a local CA in the system root store and generates locally-trusted certificates. It also works perfectly well with RaspAP. This allows you to generate a trusted certificate for a hostname (for example, raspap.local) or IP address because it only works for you.
Here's the twist: it doesn't generate self-signed certificates, but certificates signed by your own private CA. This tool does not automatically configure servers or mobile clients to use the certificates, though — that's up to you. These steps are covered in detail below.
Read more about mkcert here and follow the project on GitHub.
Creating a certificate
There are two options to go about creating a self-signed certificate with mkcert: 1) manually, or 2) with the Quick installer. Both methods are described below.
Manual steps
Follow the steps below to generate and install a locally-trusted certificate for RaspAP. The local domain raspap.local is used in the examples below. You may substitute this with the default raspberrypi.local or your own hostname.
Tip
If you've changed your hostname prior to starting this process, be sure to reboot your device for the change to take effect.
Start by installing the pre-built binary for Arch Linux ARM on your Raspberry Pi:
sudo wget https://github.com/FiloSottile/mkcert/releases/download/v1.3.0/mkcert-v1.3.0-linux-arm -O /usr/local/bin/mkcert
sudo chmod +x /usr/local/bin/mkcert
mkcert -install
Using the local CA at "/home/pi/.local/share/mkcert" â¨
The local CA is now installed in the system trust store! âĄī¸
raspap.local:
You should see output like the following:
Using the local CA at "/home/pi/.local/share/mkcert" â¨
Created a new certificate valid for the following names đ
- "raspap.local"
- "*.raspap.local"
- "raspap.local"
Reminder: X.509 wildcards only go one level deep, so this won't match a.b.raspap.local âšī¸
The certificate is at "./raspap.local+2.pem" and the key at "./raspap.local+2-key.pem" â
.pem file in lighttpd:
Set permissions and move the .pem file:
Edit the lighttpd configuration with sudo nano /etc/lighttpd/lighttpd.conf. Add the following block to enable SSL with your new certificate:
server.modules += ("mod_openssl")
$SERVER["socket"] == ":443" {
ssl.engine = "enable"
ssl.pemfile = "/etc/lighttpd/ssl/raspap.local.pem"
ssl.ca-file = "/home/pi/.local/share/mkcert/rootCA.pem"
server.name = "raspap.local"
server.document-root = "/var/www/html"
}
Optionally, you can redirect all HTTP requests to HTTPS like so:
$SERVER["socket"] == ":80" {
$HTTP["host"] =~ "(.*)" {
url.redirect = ( "^/(.*)" => "https://%1/$1" )
}
}
Restart the lighttpd service:
Verify that lighttpd has restarted without errors: You should see a response like the following:â lighttpd.service - Lighttpd Daemon
Loaded: loaded (/lib/systemd/system/lighttpd.service; enabled; vendor preset: enabled)
Active: active (running) since Sun 2023-03-26 10:09:46 CEST; 5 days ago
Main PID: 1080 (lighttpd)
Tasks: 6 (limit: 779)
CPU: 5min 17.332s
CGroup: /system.slice/lighttpd.service
ââ1080 /usr/sbin/lighttpd -D -f /etc/lighttpd/lighttpd.conf
ââ1168 /usr/bin/php-cgi
ââ1185 /usr/bin/php-cgi
ââ1186 /usr/bin/php-cgi
ââ1187 /usr/bin/php-cgi
ââ1188 /usr/bin/php-cgi
Mar 30 18:23:38 raspap lighttpd[1433]: Syntax OK
Mar 30 18:23:38 raspap systemd[1]: Started Lighttpd Daemon.
rootCA.pem to your lighttpd web root:
Important
Do not share the rootCA-key.pem file.
Finish by following the client configuration steps below.
Quick installer
The Quick Installer may also be used to generate SSL certs with mkcert. The installer automates the manual steps described above, including configuring lighttpd with SSL support. It's recommended to review these steps to have an idea of what is happening behind the scenes.
Invoke the Quick installer and specify the -c or --cert option, like so:
Note
Executing the Quick installer only installs mkcert and generates an SSL certificate with the input you provide. It does not (re)install RaspAP.
$ curl -sL https://install.raspap.com | bash -s -- --cert
888888ba .d888888 888888ba
88 8b d8 88 88 8b
a88aaaa8P' .d8888b. .d8888b. 88d888b. 88aaaaa88a a88aaaa8P
88 8b. 88 88 Y8ooooo. 88 88 88 88 88
88 88 88. .88 88 88. .88 88 88 88
dP dP 88888P8 88888P 88Y888P 88 88 dP
88
dP version 3.2.1
The Quick Installer will guide you through a few easy steps
RaspAP mkcert: Configure a new SSL certificate
Current system hostname is raspap
Create an SSL certificate for raspap.local? (Recommended) [y/N] y
Install to lighttpd SSL directory: /etc/lighttpd/ssl? [y/N]: y
***************************************************************
A new SSL certificate for: raspap.local
will be installed to lighttpd SSL directory: /etc/lighttpd/ssl
***************************************************************
Complete installation with these values? [y/N]: y
RaspAP mkcert: Fetching mkcert binary
RaspAP mkcert: Installing mkcert
Using the local CA at "/home/pi/.local/share/mkcert" â¨
The local CA is already installed in the system trust store! đ
Warning: "certutil" is not available, so the CA can't be automatically installed in Firefox and/or Chrome/Chromium! â ī¸
Install "certutil" with "apt install libnss3-tools" and re-run "mkcert -install" đ
RaspAP mkcert: Generating a new certificate for raspap.local
Using the local CA at "/home/pi/.local/share/mkcert" â¨
Warning: the local CA is not installed in the Firefox and/or Chrome/Chromium trust store! â ī¸
Run "mkcert -install" to avoid verification errors âŧī¸
Created a new certificate valid for the following names đ
- "raspap.local"
- "*.raspap.local.local"
- "raspap.local"
Reminder: X.509 wildcards only go one level deep, so this won't match a.b.raspap.local.local âšī¸
The certificate is at "./raspap.local+2.pem" and the key at "./raspap.local+2-key.pem" â
The installer will guide you through the steps of creating a certificate, as shown above. Complete the installation by following the client configuration steps below.
Client configuration
Open a browser and enter the following address, substituting the domain name you chose in the steps above: http://raspap.local/rootCA.pem. Download the root certificate to your client and add it to your system keychain. Examples below illustrate this process on macOS:
Be sure to set this certificate to "Always trust" to avoid browser warnings.
Finally, enter the address https://raspap.local in your browser. Enjoy an encrypted SSL connection to RaspAP.
Mobile devices
For the certificates to be trusted on mobile devices and remote clients, you will have to install the root CA using the method described above. Alternatively, on iOS, you can either use AirDrop or email the CA to yourself. After installing it, be sure to enable full trust.
More advanced topics are covered at mkcert.
Discussions
Questions or comments about using SSL certificates? Join the discussion here.