security-onion-letsencrypt.md

Automate LetsEncrypt certificate deployment in SecurityOnion

Prerequisites

• A domain name
• A DNS provider that works with Certbot. I'm using Cloudflare.
• An API token for the DNS provider that is scoped to allow TXT record creation.
• SecurityOnion 2.4 with sudo privileges and SSH access.

Turn on user certs in Security Onion (do this only once)

1. Administration -> Configuration
2. Options -> Show all configurable settings, including advanced settings
3. Filter "cert"
4. nginx -> ssl -> ssl/tls
5. Replace deafult cert: set to True
6. Don't replace the key files yet - we're going to automate this!

Setup LetsEncrypt

Note: some of these commands may seem unnecessary, e.g. the symlinks. Don't skip them. SecurityOnion 2.4 is based on Oracle Linux, which has some quirks.

1. Log in as your admin user and su to root.

   sudo su

2. Install snapd.

   yum install epel-release
   yum install -y snapd
   ln -s /var/lib/snapd/snap /snap

3. Install certbot.

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

4. Install certbot Cloudflare DNS plugin.

   snap set certbot trust-plugin-with-root=ok
   snap install certbot-dns-cloudflare

5. Initialize the /etc/letsencrypt directory by running certbot without any arguments. Ignore the errors.

   certbot

6. Add Cloudflare DNS API token.

   TOKEN={enter your Cloudflare API token here}
   echo dns_cloudflare_api_token=$TOKEN > /etc/letsencrypt/cloudflare.ini
   chmod 400 /etc/letsencrypt/cloudflare.ini

7. Request the certificate. Replace your.fqdn.xyz with the FQDN of your SecurityOnion server.

   FQDN=your.fqdn.xyz
   certbot certonly --dns-cloudflare --dns-cloudflare-credentials /etc/letsencrypt/cloudflare.ini -d $FQDN

8. Copy the cert and key to SecurityOnion's nginx salt config.

   cp -f /etc/letsencrypt/live/$FQDN/privkey.pem /opt/so/saltstack/local/salt/nginx/ssl/ssl.key
   chmod 644 /opt/so/saltstack/local/salt/nginx/ssl/ssl.key
   cp -f /etc/letsencrypt/live/$FQDN/fullchain.pem /opt/so/saltstack/local/salt/nginx/ssl/ssl.crt
   chmod 640 /opt/so/saltstack/local/salt/nginx/ssl/ssl.crt

9. Create a post-hook to perform this each time certs are renewed.

   cat <<EOF > /etc/letsencrypt/copy_to_nginx.sh
   cp -f /etc/letsencrypt/live/$FQDN/privkey.pem /opt/so/saltstack/local/salt/nginx/ssl/ssl.key
   chmod 644 /opt/so/saltstack/local/salt/nginx/ssl/ssl.key
   cp -f /etc/letsencrypt/live/$FQDN/fullchain.pem /opt/so/saltstack/local/salt/nginx/ssl/ssl.crt
   chmod 640 /opt/so/saltstack/local/salt/nginx/ssl/ssl.crt
   so-nginx-restart
   EOF
   
   chmod +x /etc/letsencrypt/copy_to_nginx.sh

10. Test certbot renew, and create a cron job for it.

    certbot renew --dry-run --post-hook /etc/letsencrypt/copy_to_nginx.sh
    crontab -e

11. Place the following at the TOP of the file and save:

    # check certs once a week
    10 4 * * 0 certbot renew --post-hook /etc/letsencrypt/copy_to_nginx.sh

12. Restart nginx

    so-nginx-restart

Maintenance

If the steps above succeeded, there is no special maintenance required. The cron job will renew the certs automatically before they expire.

Use SecurityOnion's built-in soup utility to maintain your SecurityOnion stack.