Let's Encrypt

(Automated Certificate Management for Embedded Systems)

Let's Encryptâ„¢ is a Certificate Authority (CA) that provides free X.509 (SSL) certificates. Unlike a traditional CA where the server administrator must go through a manual process of submitting a Certificate Signing Request (CSR), Let's Encrypt enables automatic CSR signing via its Automated Certificate Management Environment (ACME) protocol.

Starting with Mako Server 3.0, an automated ACME plugin is included as three Lua modules in the Mako Server. More specifically, the Mako Server includes a programmable ACME plugin that may be activated by using the Mako Server's configuration file or activated programmatically by directly interacting with the Lua modules. The ACME protocol automates the CSR signing process, but just like any other CA, Let's Encrypt requires proof of ownership.

Let's Encrypt Embedded Web Server

Figure 1: Let's Encrypt requests web server to show proof of ownership.

Proof of ownership can be provided by one of the two challenge options Let's Encrypt provides, http-01 or dns-01 challenge. See the Let's Encrypt How It Works tutorial for more information.

This tutorial focuses on how to provide proof of ownership for servers running on private networks where the server cannot be accessed from the Internet. If you are running a Mako Server that is publicly available either by directly running the server, on for example an online VPS, or providing a server that is indirectly available by port forwarding on port 80, see the online Mako Server documentation for the http-01 challenge option . This tutorial focuses on the dns-01 challenge option, which is the only challenge option that may be used by servers not publicly available on the Internet.

This tutorial covers the following:

Web Servers Running On Private Networks

One of the more common Mako Server and Barracuda App Server use cases is to integrate the server solution in devices designed to be run and operated on private networks or in environments with no network. The traditional solution for dealing with SSL certificates for servers running on private networks has been to implement a custom CA and its associated chain of trust by, for example, using Real Time Logic's free Certificate (PKI) Management Tool .

Setting up a custom CA has several drawbacks such as requiring a good understanding of certificate management by the end user. A custom CA also requires installation of the CA's root certificate in all client devices (browser) for the device(s) to be trusted.

Let's Encrypt's root certificate is pre-installed in all common client devices (e.g. browsers) and a server certificate signed by Let's Encrypt is automatically trusted by clients as long as the device can be reached by the domain name its SSL certificate is signed for.

Managing domain names for servers running on private networks or servers without a network requires minimal understanding by the end user when properly set up. This process can also be automated as we will show later in this tutorial. However, let's first start with a domain name tutorial to show the many options you have as a product designer when it comes to providing easy secure access to embedded web servers.

DNS Tutorial For Devices On Private Networks

A private network is a network using privately assigned network addresses such as IP addresses in the range 192.168.x.x and where the IP addresses cannot be reached from the Internet. We will show how to use an online DNS server to provide DNS services for resolving private IP addresses. For devices with no network and when an Ethernet crossover cable is used, a DNS entry in the client computer's host file may be necessary.

Devices are typically assigned subdomain names and a fully qualified device name may for example be devicename.product.company.com, where product.company.com is a subdomain of company.com with its own DNS service.

In this tutorial, we use the free domain name registrar freenom. The domain name we chose for this tutorial is realtimelogic.tk and we will add two sub domain names, one for device1 and one for device two. The two fully qualified domain names are:

device1.realtimelogic.tk
device2.realtimelogic.tk

You can follow along this tutorial by creating a freenom account and by registering your own domain name.

The following figure shows the freenom's DNS Management page for the domain name realtimelogic.tk. The screenshot shows we have added the public WAN IP address for the top domain realtimelogic.tk and the subdomain device1, just before adding a new record for device2.

DNS A Record

Figure 2: How to set DNS A record (IPv4 address) for subdomains using private IP addresses.

The two private IP addresses are for two PCs running in our network. If you are following along this tutorial, set the IP address to your own local computer. Note that the purpose with adding the public WAN IP address for the top domain is to make sure Let's Encrypt accepts our DNS settings. The top domain realtimelogic.tk is the one in the above screenshot where the name field is blank. You do not need a web server at this address, but the address must be publicly available and can, for example, be set to your WAN IP address.

Your own PC is probably assigned a dynamic IP address by the DHCP server. We have set a short TTL for the DNS settings if we should need to change the IP settings, but usually, locally connected computers get the same IP address when restarted since the DHCP server remembers the client computer's MAC address. We will later show how Mako Server can dynamically update DNS settings by using a DNS service.

After adding the DNS settings, we can open a command window and check if the device domain names resolve. The following example shows how to check one of the domain names:

x:\>ping device1.realtimelogic.tk
Pinging device1.realtimelogic.tk [192.168.1.100] with 32 bytes of data:
Reply from 192.168.1.100: bytes=32 time<1ms TTL=128

Figure 3: The ping command verifies that the DNS record is set correctly.

After making sure the DNS works, we can start any web server on the PC with this IP address. The following screenshot shows the Mako Server accessible via the domain device1.realtimelogic.tk:

Mako Server

Figure 4: The subdomain 'device1' resolves to private IP address, where the Mako Server is running.

As you can see from the above screenshot, we are using an HTTP connection and the browser shows this as "Not secure". We get a certificate error if we change to https since we have thus far not installed a certificate for the domain name device1.realtimelogic.tk.

Self Signed Certificate

Figure 5: Mako Server's default certificate is not trusted or valid for subdomain 'device1'.

Using Let's Encrypt to Sign Certificates for Non Public Web Servers

So now that we have covered DNS, it's time to create a certificate for our domain name and have Let's Encrypt sign our certificate with its publicly trusted root.

The Mako Server makes it possible to have Let's Encrypt sign certificates for non public servers by using what is known as the dns-01 challenge option. This option shows domain ownership proof by setting a DNS TXT record.

The Mako Server includes an option for automatically setting the DNS entry, but this requires using our online DNS service. We will discuss the automatic DNS option later. We can also configure the Mako Server for manual DNS TXT entry mode, where the Mako Server informs the user when it is time to set the DNS TXT record.

For the next tutorials, download the Mako Server and get familiar with running the server in console mode.

Using the manual DNS TXT Record option

Manually setting the Let's Encrypt DNS TXT Record

Open a console window in a directory suitable for creating some test files and directories. The Mako Server must be in the PATH environment variable or the Mako Server's full pathname must be provided when starting the server -- e.g. c:\installdir\mako.

Run the following commands in the console window (works for Windows, Linux, and Mac):

echo acme={acceptterms=true, rsa=true, email="john.doe@company.com", domains={"device1.realtimelogic.tk"}, challenge={type="dns-01", url="manual"}} > mako.conf mkdir www echo ^<?lsp print(require("acmedns").recordset()) ?^> > www/index.lsp

Figure 6: Commands used for creating mako.conf and www/index.lsp

Linux/Mac users : the echo commands must have the strings in single quotes -- e.g. echo 'the string' > file. The last echo command includes the Windows escape symbol ^. Remove the symbols when using Linux and Mac.

In the first echo command, change the email to a valid address before creating the mako.conf file. The email address is used when registering with the Let's Encrypt service. Also, make sure to set your own domain name.

You may also use an editor to create mako.conf and www/index.lsp. The 'acme' mako.conf configuration option enables the ACME plugin. See the Mako Server's online Let's Encrypt documentation for more information. The LSP file www/index.lsp calls acmedns.recordset() and the LSP page must be executed after setting the DNS TXT entry. This will be explained below.

Start Mako Server in the console window as follows:

x:\>mako -l::www
Mako Server. Version 3.0
BAS lib 4402. Build date: Jul  2 2019
Copyright (c) Real Time Logic.

Loading x:\\mako.conf.
Trace file: mako.log
Mounting mako.zip
Server listening on IPv6 port 80
Server listening on IPv4 port 80
Loading certificate MakoServer
SharkSSL server listening on IPv6 port 443
SharkSSL server listening on IPv4 port 443
Info: www/.preload not found
Loading www as "root application" : ok
Set ACME DNS TXT Record:
        Record name:    _acme-challenge.device1.realtimelogic.tk
        Record data:    UctRs7Sq51Y7_hSECQFBcBr_jCe5tjQXMqQPwWBP7Ro

Figure 7: Mako Server loading mako.conf with the 'acme' configuration option.

The above command line option instructs Mako Server to load the 'www' application where we have the index.lsp page we created using the echo command in figure 6. Notice from the above printouts that Mako Server loads our configuration file. After a few seconds, you should see the text "Set ACME DNS TXT Record". Navigate to freenom (or any other domain name registrar you are using) and set the TXT record for your domain as shown below:

Set DNS TXT Record

Figure 8: How to set the DNS TXT record from figure 7 using the domain registrar's default DNS server.

The default is to set the 'A' record so make sure to change the type to 'TXT' as shown above.

The Mako Server's ACME engine is, at this point, paused and we must resume the operation by calling function acmedns.recordset() . However, after setting the TXT record, give the DNS server at least two minutes to replicate the data before continuing. This is a good time to take a coffee break.

After two or more minutes, open a browser and navigate to http://device.domain-name.tk as shown in the screenshot below.

Resuming the ACME Plugin

Figure 9: Resuming the paused ACME engine.

Recall that the LSP page index.lsp calls acmedns.recordset() and prints the result from this function. The function returns true, meaning that the ACME engine was in a paused state and that calling the function resumed operation.

After a few seconds, you should see the following in the console window:

ACME: device1.realtimelogic.tk renewed
Loading certificate "cert/device1.realtimelogic.tk.cert.pem"

Figure 10: Mako Server console printouts showing successful certificate renewal.

The new certificate is now loaded, and we can simply change the URL from http:// to https:// as shown in the screenshot below:

Trusted Let's Encrypt Signed Certificate

Figure 11: The browser now trusts the Let's Encrypt signed certificate provided by the server.

Notice the error message from index.lsp above. Since we are re-executing index.lsp, function acmedns.recordset() returns 'nil, "error message"', letting the user know that the DNS challenge state is inactive.

Since the Mako Server is a tool and not a ready to use end product, you must design a supporting web application that at a minimum lets the user resume the ACME state machine by calling function acmedns.recordset() no sooner than two minutes after the DNS record has been set. You may also design a web application that programmatically controls the ACME plugin.

Staging environment v.s. Production environment

The certificate you get when using the mako.conf file created in figure 6 uses Let's Encrypt's staging environment and not the production environment. The certificate will, for this reason, not be trusted by the browser. Please make sure you can successfully use the staging environment prior to switching to the Let's encrypt production environment. When switching to the production environment, the account information saved in cert/account.json will be invalid. The Mako Server prints a nasty error message, but recovers and creates a new Let's Encrypt account using the production environment.

Enable Logging when using the DNS challenge option in manual mode

The Mako Server would typically not be run in a console window for deployed applications and the DNS text record printed would not be visible. For this reason, the log module must be enabled such that the user receives an email when it is time to renew the certificate. The Mako Server's ACME plugin checks if the certificate needs to be renewed one time every 24 hours and dispatches an email to the configured recipient with the DNS TXT record information when it is time to renew the certificate.

Signing Certificates For Devices Behind Proxy or Devices With No Network Connection

The options we have presented so far requires a permanent Internet connection by either a direct connection via company router or company proxy. See the proxy options if the private network is behind a proxy.

Sometimes devices with embedded web servers are deployed in environments without a permanent Internet connection.

For example, maintenance personnel may connect a laptop directly to a device using an Ethernet crossover cable. For this setup to work, the laptop must be connected to the Internet by using, for example, a cellular modem and the laptop must be configured such the device can connect to the Internet via the PC when the device is being managed.

With such a network setup, the Mako Server's ACME plugin should be used directly by a dedicated web application that enables the personal to renew the certificate when plugged in. The Mako Server documentation includes an example that shows how to programmatically control the acmedns module .


Using the Automatic DNS Option

Using the automatic DNS option is by far the easiest option since the end user does not need to set DNS TXT records or update the DNS A record if the device IP address should change.

The automatic DNS option requires the use of Real Time Logic's DNS service, which is specifically designed to help Mako Server and Barracuda App Server deployments automatically maintain the "DNS A record" (IP address) and set the "ACME DNS TXT record" when it is time to renew.

Let's Encrypt DNS Service

Figure 12: Mako Server communicates with DNS service and Let's Encrypt when auto DNS is enabled.

The Mako Server initially registers the device with the online DNS service and authenticates by using the zone key received after signing up for the DNS service. The Mako Server also sends a message to the DNS service if its IP address should change. When it is time to renew, Mako Server starts the renewal process by communicating with Let's Encrypt and the DNS service when Let's Encrypt requests proof of ownership.

When using the automatic option, devices are assigned a subdomain either by using the mako.conf file or programmatically by directly controlling the ACME plugin.

The fully qualified device name may, for example, be devicename.product.company.com, in which product.company.com is a subdomain of company.com with its "product" subdomain managed by Real Time Logic's DNS service.

Automatic DNS Tutorial

Navigate to your freenom.com account and click "Manage Domain". Click "Management Tools" -> Nameservers. Select custom nameservers and enter the two following for nameserver 1 and 2.

acme1.realtimelogic.com
acme2.realtimelogic.com

Click the save button and wait until the changes have replicated across the Internet's whois database. This may take up to 48 hours. One way to test if the settings are ready is to run the whois command line program for your domain name. Whois should list the above name servers.

When whois reports the correct name servers, navigate to https://acme.realtimelogic.com

Sign up for the DNS service and follow the signup process. The DNS service sends you an email with the zone account key when the registration is complete.

Open mako.conf created with the echo command in figure 6, remove 'url="manual"' and add 'key="the key from the email you received"'. The domain name entry should only include the device subdomain name -- e.g. "device". See the second example in the Mako Server's online Let's Encrypt documentation for more information.

Start Mako Server in the console window as follows:

x:\>mako

Mako Server. Version 3.0
BAS lib 4402. Build date: Jul  2 2019
Copyright (c) Real Time Logic.

Loading x:\mako.conf.
Trace file: mako.log
Mounting mako.zip
Server listening on IPv6 port 80
Server listening on IPv4 port 80
Loading certificate MakoServer
SharkSSL server listening on IPv6 port 443
SharkSSL server listening on IPv4 port 443
ACME: device.realtimelogic.tk renewed
Loading certificate "cert/device.realtimelogic.tk.cert.pem"

Figure 13: Printouts from Mako Server when using automatic DNS management.

It takes more than two minutes before the last two printouts in figure 13 are printed to the console. The Mako Server ACME plugin waits two minutes after requesting the online DNS service to set the records before it continues. This makes sure the Let's Encrypt service can successfully verify the DNS TXT record.

The automatic DNS mode makes sure the certificate is valid and automatically renews the certificate without any user interactions. The user is informed by email each time the certificate is renewed if the data logging option is enabled.

About Real Time Logic's DNS Service

Real Time Logic's DNS service is primarily designed as an initial development aid, letting developers immediately incorporate a 100% automatic SSL certificate renewal process in their products designed for operating on private networks.

The source code for Real Time Logic's DNS service is available on GitHub.

The free DNS service must not be used for production mode, and product manufacturers should consider setting up their own service. Real Time Logic's DNS service runs on one online VPS and uses bind for the DNS management. The bind service is controlled by a Lua powered application running on a Mako Server instance. Contact Real Time Logic for details on running your own DNS service if you need help with installing the DNS software available on GitHub.

When a company registers a domain, such as product.company.com, with Real Time Logic's DNS service, a dedicated online web interface is created for the registered domain name. All devices registered for the particular domain name get listed online and may be viewed by the registered administrator after authenticating. In addition, any person without authentication requirements may view the devices registered for the location from where the user is located. This construction makes it easy to find devices that get its IP address via DHCP. In other words, the typical static IP configuration needed for server devices is not needed. The online DNS service greatly simplifies device deployment since devices can be shipped and deployed without requiring any network configurations by the end user.

Posted in Tutorials