Use Let's Encrypt Certificates with DRP

This knowledge base describes one example of using Let's Encrypt TLS Certificates for the dr-provision service (DRP Endpoint). This is only one example of how you might use Let's Encrypt.

Solution¶

This solution uses the certbot tool to interact with the Let's Encrypt APIs to authenticate and get a TLS Certificate. Other tools exist that will handle this capability for you.

This solution assumes you are running the commands at the Shell of the DRP Endpoint.

All Let's Encrypt prerequisites/requirements must be in place prior to running this process. For example, valid DNS records MUST be setup in advance, for the Fully Qualified Domain Name (FQDN) of the DRP Endpoint server.

Install Certbot
Run certbot in standalone mode
```
certbot certonly --standalone
```

Follow the prompts from the CLI tool. This generates certificates in directory:

/etc/letsencrypt/live/[drp fqdn]

replace "[drp fqdn]" with your FQDN (e.g. drp.example.com) 4. Configure SystemD to now use the new certificate and private key:

DRP_ENDPOINT="drp.example.com"  # SET THIS APPROPRIATELY !!

cat <<EOF > /etc/systemd/system/dr-provision.service.d/certificate.conf
[Service]
Environment=RS_TLS_KEY_FILE=/etc/letsencrypt/live/$DRP_ENDPOINT/privkey.pem
Environment=RS_TLS_CERT_FILE=/etc/letsencrypt/live/$DRP_ENDPOINT/fullchain.pem
EOF

Notify SystemD of updated config files, and restart DRP Endpoint
```
systemctl daemon-reload
systemclt restart dr-provision
```

Verify/test the TLS certificate is as expected (using openssl)

DRP_ENDPOINT="drp.example.com"  # SET THIS APPROPRIATELY !!

echo "Checking DRP Endpoint:  '$DRP_ENDPOINT'"

openssl s_client -showcerts -connect $DRP_ENDPOINT:8092  # api port
# hit enter to return to shell prompt

openssl s_client -showcerts -connect $DRP_ENDPOINT:8090  # secure files port
# hit enter to return to shell prompt

In the final verification step, it should be clearly identified that the TLS Certificate is issued by Let's Encrypt.

Automatic Certificate Renewals¶

To automatically renew certificates, create a monthly cron job, which runs the Certbot renewal process. Then via the use of the post hooks after renewal, trigger an import of the newly generated certificate and key.

To create the crontab entry, as root, perform:

cat << EOF > /etc/cron.monthly/dr-provision-letsencrypt-renewal.sh
#!/bin/sh

certbot renew
exit 0
EOF

chmod 700 /etc/cron.monthly/dr-provision-letsencrypt-renewal.sh

Now create the Certbot post hook so that when a renewal certificate is created, DRP updates the Certificate it's using.

Note

This script assumes that you have a $HOME/.drpclirc with appropriate credentails for user, password, and endpoint. If not, adjust the post-hook script to include the appropriate command line argument flags to the drpclicall. Seers_kb_00010 for more details.

This will create the post hook:

cat << EOF /etc/letsencrypt/renewal-hooks/post/dr-provision.sh
#!/usr/bin/env bash

# reload the TLS certs in dr-provision, gets cert/key files from the
# environment - which assumes injected via systemd

function xiterr() { [[ $1 =~ ^[0-9]+$ ]] && { XIT=$1; shift; } || XIT=1; printf "FATAL: $*\n"; exit $XIT; }

PATH=$PATH:/usr/local/bin

T=$(mktemp /tmp/drp-tls.XXXXXXX)
strings /proc/$(pidof dr-provision)/environ | grep RS_TLS > $T
source $T

[[ -n "$RS_TLS_CERT_FILE" ]] \
  && drpcli system certs set "$RS_TLS_CERT_FILE" "$RS_TLS_KEY_FILE" \
  || xiterr 1 "Cert/key file variables not defined"

echo ""
echo "- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -"
echo ">>> Reloading 'dr-provision' certs from files"
drpcli system certs set "$RS_TLS_CERT_FILE" "$RS_TLS_KEY_FILE"
CERT_SYS=$?
drpcli files certs set "$RS_TLS_CERT_FILE" "$RS_TLS_KEY_FILE"
CERT_FILES=$?
CERTS_ALL=$( expr $CERT_SYS + $CERT_FILES)
if (( $CERTS_ALL ))
then
  echo "FATAL:  Failed to load certificate files.  Status:"
  (( $CERTS_SYS )) && echo "        'drpcli system certs' failed"
  (( $CERTS_FILES )) && echo "        'drpcli files certs' failed"
  exit 1
else
  echo "Certificates successfully reloaded for API and Files services."
  echo "  cert:  $RS_TLS_CERT_FILE"
  echo "   key:  $RS_TLS_KEY_FILE"
fi
echo "- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -"
echo ""

rm -f $T
EOF

chmod 700 /etc/letsencrypt/renewal-hooks/post/dr-provision.sh

This process will search for the Envrionment variables that are usually set in the SystemD unit start files for the Certificate locations, then reload the newly generated cert and keyfile in to DRP.

In DRP v4.6.0 and newer, the certificate set process will automatically enable the DRP Endpoint HTTPS process to serve the new cert/key. In previous versions, you will have to restart DRP (eg systemctl restart dr-provision).

Additional Information¶

The example used in this document shows how to configure SystemD to utilize the certificate. The generated certificates can be used in other modes of operation. See the dr-provision binary help (eg dr-provision --help) for more details on the options around certificates and keys.

As of Digital Rebar Platform (DRP) version v4.7.0 and newer, there is a separation of the API port service from the Secure File server port. By default, the API port runs on TCP Port 8092, while the new Secure File Server port runs on TCP Port 8090.

Each port requires it's own TLS Certificate for correct operations. By default DRP will be set up with a self-signed TLS certificate. To set a TLS certificate for both ports, you must run a Certificate set command for each service port. For example:

drpcli system certs set <cert_file> <private_key>
drpcli files certs set <cert_file> <private_key>

Versions¶

DRP Endpoints Version v4.x

Note that DRP Certificate handling changes for v4.7.0 and newer. See the rs_cert_ops documentation for more details.

Keywords¶

ssl, tls, certificate, letsencrypt, systemd, https, Let's Encrypt, certbot, openssl, Lets Encrypt, api port, files server port

Revision Information¶

KB Article     :  kb-00059
initial release:  Fri Feb 26 10:13:47 PST 2021
updated release:  Fri Aug 02 10:11:00 PST 2022