The Mako Server seamlessly integrates with Let's Encrypt, a free and automated Certificate Authority (CA) that issues SSL/TLS certificates. By leveraging the Automatic Certificate Management Environment (ACME) protocol, the Mako Server automates the entire process of obtaining, installing, and renewing certificates, ensuring secure HTTPS communication with minimal manual intervention.
In the examples below, the configuration settings are set to use RSA certificates. However, the Mako Server supports both RSA and ECC (Elliptic Curve Cryptography) certificates and defaults to using ECC certificates if not explicitly set.
If you choose to modify the settings to use ECC certificates, it's important to note that the latest version of the Mako Server incorporates an integrated software-based Trusted Platform Module (TPM) for enhanced security. This TPM securely protects the ECC private key, making it impossible to copy or transfer the private key to another computer. This ensures that the key remains secure even if the server is compromised.
By defaulting to ECC certificates and integrating a software-based TPM, the Mako Server enhances the overall security of your SSL/TLS communications:
Note: If you are not using a pre-compiled server and plan on compiling your own server, make sure to read the section on configuring the TPM.
If you're new to certificate management or Public Key Infrastructure (PKI), our Certificate Management Tutorial is a great starting point. It covers the fundamentals of browser trust and how a server’s certificate is verified.
The Automatic Certificate Management Environment (ACME) defined in RFC-8555 is a protocol that enables automatic installation of certificates.
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.
Figure 1: Let's Encrypt requests web server to show proof of ownership.
Let's Encrypt Challenge Methods for SSL/TLS Certificates
To verify domain ownership, Let's Encrypt provides two challenge methods: http-01 and dns-01. Barracuda App Server powered products such as the Mako Server supports both options:
By supporting both challenges, the Mako Server offers flexibility for securing both public-facing and local embedded web servers with Let's Encrypt SSL/TLS certificates.
See the Let's Encrypt How It Works tutorial if you are new to Let's Encrypt.
The following two examples show how to use the http-01 challenge option for a public server running on a VPS and the dns-01 challenge option for a private server running on a home/office computer.
For both examples, download the Mako Server to the target computer and unpack the server in any directory. Use an editor and create a mako.conf file in the same directory as the Mako Server.
The following example also works for a private (Intranet) server if you have configured port forwarding in your router, but note that the server must be accessible via non secure HTTP on port 80. Let's Encrypt communicates with your server using this port number.
Copy the following and paste the configuration data into your mako.conf file, but make sure to change the email address. Let's Encrypt requires a valid address. You must also set the domain name to a name you own. A DNS tutorial can be found further down in this tutorial.
acme={
acceptterms=true,
rsa=true, -- Remove this line if you want to use a TPM-protected ECC key
production=true,
email="john.doe@company.com",
domains={"realtimelogic.tk"}
}
Figure 2: Http-01 configuration options for domain 'realtimelogic.tk'.
Save the file and start the Mako Server. The command on line 1 below shows how to start the server on Linux as user root. We must start it this way since the server must listen on port 80. See the Getting Started Guide for more information.
1 2 3 4 5 6 7 8 9 | mako@vps63784:~$ sudo ./mako -u`whoami`Mako Server. Version 3.2Server listening on IPv6 port 80Server listening on IPv4 port 80Loading certificate MakoServerSharkSSL server listening on IPv6 port 443SharkSSL server listening on IPv4 port 443Loading certificate "cert/realtimelogic.tk.cert.pem"ACME: realtimelogic.tk renewed |
Figure 3: Publicly available server using http-01 challenge option.
In Figure 3, notice how the Mako Server initially loads an embedded certificate (line 5). This certificate is not trusted by your browser but is needed since we initially do not have a Let's Encrypt certificate.
Communicating with Let's Encrypt takes time and line 8 and 9 above are printed roughly 10 seconds after starting the server. The server has at this point installed a certificate that is valid for the requested domain name and you may navigate to https://your-domain-name. The following figure shows the Mako Server's default page and the Let's Encrypt signed certificate's chain of trust.
Figure 4: Let's Encrypt signed certificate's chain of trust.
A much more detailed tutorial on using the many configuration options for the dns-01 option can be found further down in this tutorial, and we will not go into the details of how the next example works. You can simply copy the configuration data below and paste the data into mako.conf, but make sure to change the email address to your own address and the sub-domain name "john-doe" (the 'domains' setting) to your own name.
acme={
acceptterms=true,
rsa=true, -- Remove this line if you want to use a TPM-protected ECC key
production=true,
email="john.doe@company.com",
domains={"john-doe"},
challenge={type="dns-01"}
}
Figure 5: Dns-01 configuration options for sub-domain 'john-doe' using integrated zone key.
Save the file and start the Mako Server. The Mako Server does not need to listen on ports 80 and 443 when using the dns-01 challenge option, but it is much easier to use and understand the example if the server listens on the default ports. We use the same Linux command for starting the server. On Windows, you would just type: mako.
1 2 3 4 5 6 7 8 9 | ~/mako$ sudo ./mako -u`whoami`Mako Server. Version 3.2Server listening on IPv6 port 80Server listening on IPv4 port 80Loading certificate MakoServerSharkSSL server listening on IPv6 port 443SharkSSL server listening on IPv4 port 443Loading certificate "cert/john-doe.local.makoserver.net.cert.pem"ACME: john-doe.local.makoserver.net renewed |
Figure 6: Private server using dns-01 challenge option with testing domain 'local.makoserver.net'.
In Figure 3, when using the http-01 challenge option, line 8 and 9 were printed roughly 10 seconds after starting the server. When using the dns-01 challenge option, this takes much longer and it will take roughly 2.5 minutes before you see the two printouts.
In Figure 6, the private server is locally available on the LAN by navigating to: https://john-doe.local.makoserver.net.
As will be explained in detail later, there are many configuration options for using the dns-01 challenge option. The configuration options selected in Figure 5 uses the dns-01 challenge option with the testing domain https://local.makoserver.net. The Mako Server includes an integrated zone key for this testing domain and this testing domain is hosted by Real Time Logic's DNS testing service. You may create your own zone key using your own domain name and you may host your own DNS server. You may also use the dns-01 challenge option without the DNS service as will be explained further down in this tutorial.
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 rest of this tutorial explains in detail how to provide proof of ownership for private servers. We will explain in detail how to use the Let's Encrypt dns-01 challenge option, which is the only challenge option that may be used by servers not publicly available on the Internet.
The following video shows how to create the configuration file for the automatic DNS challenge option and how to access the server locally and remotely. The remote access option, explained in the tutorial HTTP Behind Firewall, is an additional feature that may be enabled.
This tutorial covers the following:
The traditional solution for dealing with SSL certificates for servers running on private networks has been to implement a custom Certificate Authority (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, including requiring a good understanding of certificate management by the end user and 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.
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, in which 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. You may use your own registered domain name or create a new freenom account.
The domain name we chose for this tutorial is realtimelogic.tk and we will add two subdomain 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.
Figure 7: 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 with this tutorial, set the IP address to your own local computer. Note that the purpose of 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 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 8: 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:
Figure 9: The subdomain 'device1' resolves to a 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.
Figure 10: Mako Server's default certificate is not trusted or valid for subdomain 'device1'.
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 nonpublic 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 by having the Mako Server inform 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.
The following hands-on tutorial teaches you how to manually use the Let's Encrypt's dns-01 challenge option by setting a TXT record for authentication. The SharkTrustX-powered method performs the same steps but automatically.
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.
Create the following directory and two files:
│──── mako.conf │ └─+──www │ └──── index.lsp
Use an editor and insert the following into mako.conf
acme={
acceptterms=true,
production=false, -- Use the Let's Encrypt staging env.
email="john.doe@company.com",
domains={"device1.realtimelogic.tk"},
challenge={
type="dns-01",
servername="manual"
}
}
Figure 11: Mako Server configuration file mako.conf
Change the email address above to a valid address and change the domain name to your own registered domain.
Insert the following into www/index.lsp:
<?lsp
local ad=require("acme/dns")
if ad.recordset then
print(ad.recordset())
else
print"Oops, manual mode not activated!"
end
?>
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(). 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 12: 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. 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:
Figure 13: How to set the DNS TXT record from figure 12 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. You may have to wait 10 minutes if using freenom. This is a good time to take a coffee break.
If you have 'dig' installed, you may check the record as follows:
dig +short _acme-challenge.device1.realtimelogic.tk TXT "xYTPUjSj4ArzEVNT0pG1dXrdRuFqmYOxQK4qXs15gBo"
After two or more minutes, open a browser and navigate to http://device.domain-name.tk as shown in the screenshot below.
Figure 14: 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 15: 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:
Figure 16: 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 11 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.
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.
The options we have presented so far require 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 that 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 lets the personnel renew the certificate when plugged in. The Mako Server documentation includes an example that shows how to programmatically control the acmedns module .
You may receive an error similar to the following if you have followed the above tutorial for the manual DNS challenge option and if using a freenom.com domain.
ACME: renewing device1.realtimelogic.tk failed: DNS problem: SERVFAIL looking up CAA for device1.realtimelogic.tk - the domain's nameservers may be malfunctioning.
The freenom name server sometimes appears to be overloaded and Let's Encrypt may have stringent requirements. You can simply try again later if you get this error or use a paid-for domain name.
Note that the Automatic DNS Challenge Option works without a problem when using a freenom domain.
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 SharkTrustX, 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.
Figure 17: Mako Server communicates with DNS service and Let's Encrypt when auto DNS is enabled.
Open mako.conf and add the following, possibly replacing any other "acme" settings:
acme={
acceptterms=true,
email="john.doe@company.com",
domains={"mydevice"}, -- Include only subdomain name; the FQN will be mydevice.local.makoserver.net
challenge={type="dns-01"}
}
Figure 18: mako.conf example for the integrated zone local.makoserver.net.
Start the Mako Server. You should see the following printouts, but note that the second printout comes two minutes after the first:
Creating new ACME account Loading certificate "cert/mydevice.local.makoserver.net.cert.pem"
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.
The zone local.makoserver.net is the default zone embedded in the Mako Server. You can create your own zone using your own domain name, allowing you to establish a secure and trusted environment for your applications.
The following instructions provide a concise summary of the SharkTrustX Zone Management tutorial.
Navigate to your freenom account and click "Manage Domain". Click "Management Tools" -> Nameservers. Select custom nameservers and enter the two following for nameservers:
nsex1.realtimelogic.com nsex2.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://SharkTrustX.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 (figure 11), 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 19: Printouts from Mako Server when using automatic DNS management.
It takes over two minutes before the last two printouts in Figure 19 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 ensures 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.
You can also enable remote access without opening inbound ports when using the automatic DNS mode.
The reverse connection feature in Mako Server enables secure remote access by allowing the server to initiate an outbound connection to a SharkTrustX service. This eliminates the need for complicated firewall configurations or opening inbound ports. Once the reverse connection is established, the remote user can securely manage the server as if they were connected locally. This feature simplifies remote management while ensuring robust security through SSL encryption, providing a seamless solution for accessing devices behind firewalls or NATs. See the Remote Access Tutorial for additional details.
The SharkTrustX Testing Service is primarily designed as an initial development aid, letting developers test the automatic DNS feature without having to set up their own DNS server. The software for the online service is a source code product we provide, and you may use the software to host your own service either directly or with help from our consulting partners.
The source code for Real Time Logic's DNS service is available on GitHub.The free DNS testing 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.
A dedicated online web interface is created for the registered domain name when a company registers a domain, such as product.company.com, with Real Time Logic's DNS service. 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 their 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.