Say goodbye to SSL/TLS certificate registration and renewal headaches, and beef up your NetBurner security!
In the upcoming 3.5.0 NNDK release, we’re making it easier to get and update SSL/TLS certificates on your NetBurner device.
Without easy automatic SSL protocols like ACME and providers like Let’s Encrypt, the process of requesting, renewing and installing a certificate can take hours (or even days, in the case of embedded or legacy systems) and is easy to forget. But thanks to the Internet Security Research Group’s efforts, securing your project is about as painless as it can get — not to mention at the bargain price of free!
The Code
In this tutorial we’ll be modifying an existing basic HTML project, but you may prefer to use the example project code that ships with NNDK 3.5+ under examples\SSL\acmeservlet — the basic web server example at examples\Web\SimpleHtml is a good blank slate to start from.
All code in this blog post are Copyright NetBurner, Inc, and may only be executed on NetBurner provided hardware. See the NNDK license that came with your product for more details.
Getting Started with ACME
Thanks to a new protocol defined in RFC8555 called ACME (Automatic Certificate Management Environment) and providers like Let’s Encrypt and BuyPass, the process of getting and renewing publicly trusted SSL certificates is now almost painless.
How painless you ask?
Well, first we have to make a few assumptions that are unfortunately part of the ACME protocol and SSL certificate infrastructure itself:
- We assume that your device’s web server is accessible via a public IP address (IPv4 or IPv6 on the Internet, either directly or via port forwarding on ports 80 and 443)
- And that it has a public DNS name registered like
you.example.com
If these two are true, then a public ACME certificate provider should be able to look up that domain name, contact your device’s web server, validate your certificate request, and automatically install that certificate onto your device. (We currently support HTTP-01 authentication, not yet DNS-01.)
This can work on your local network too, however again the ACME server will need to be able to contact your device by looking up whatever DNS name you’re providing: that’s part of the verification. So if you’re trying to implement ACME SSL on your corporate network, you’ll need to configure your ACME server and local DNS such that the server can browse to your NetBurner device’s internal web server using the specified DNS name(s).
Once those assumptions are met, adding ACME to your project requires only a few lines!
Just edit your project’s main.cpp to include the following at the top (outside your UserMain function):
//Include the ACME server and cert managment stuff.
#include <http.h>
#include <acmeRFC8555Servlet.h>
#include <crypto/certgen.h>
#include <nbtime.h>
//Define the default certificate names and email. Note ALT_NAME is required
const char * DEFAULT_CERT_EMAIL= "changeme@Netburner.com";.
const char * DEFAULT_CERT_ALT_NAMES= "changeme.example.com";
const char * DEFAULT_CERT_COM_NAME= "changeme.example.com";
//Make sure your system know what time it is.
NtpClientServlet ntp_client;
//And then create an ACME client
//By default with no constructor this will have no email address
//And register on the public (production, not staging) server.
LetsEncryptAcmeServletObject acme_client;
That’s it! So how do you know it worked? You can do some debugging of the time (which is critical for proper SSL/TLS operation) and the ACME client like so:
// Is Time valid?
if(ntp_client.TimeIsValid())printf("Time is valid\r\n");
// Print ACME diagnostic messages to the console
acme_client.SetDiag(true);
// Or get the current state:
NBString state=acme_client.GetStateString();
// Or if you prefer a const char * you can print:
printf("Acme State:%s\n", acme_client.GetStateCC());
With SetDiag(true) enabled, your device’s console will output diagnostic data showing the connection and certificate exchange process:
End-User Settings
Users can override the DEFAULT_*constants you specified above by visiting the NetBurner Config page for your device. This allows you to flash multiple devices with the same compiled app image and adjust the device DNS names or contact email addresses in the field or as the environment changes.
Options and Limitations
As you can see the default constants include a Common Name and Alternate Name you can specify, but if you want more than just those two you can specify multiple Alternate Names in one string separated by commas:
const char * DEFAULT_CERT_ALT_NAMES = "example.com,demo.example.com,test.example.com,www.example.com";
By default the system uses https://acme-v02.api.letsencrypt.org/directory (Let’s Encrypt) as an ACME Certificate Authority, but you can change this by using a different client or instantiating the base client class. We’ve included a client for BuyPass, which is accessible by replacing the Let’s Encrypt client with this: BuyPassAcmeServletObject acme_client; — note that BuyPass requires a contact email address to be specified in the CertData while for Let’s Encrypt it’s optional. In both cases the CA should email you if your certificate is in danger of expiring (fails to auto-renew.)
If you’re testing your ACME setup with the free Pebble server on your LAN (changing the default Pebble ports from 5002/5001 to 80/443 of course) just change your main.cpp to use a custom ACME client class override instead:
// Create a custom ACME client to a local Pebble server:
AcmeServletObject acme_client("https://192.168.10.90:14000/dir");
If you want your device to be able to discard its ACME certificate and get a new certificate, the function acme_client.Delete_Everything_Restart(); is also available. For further ACME client details see our upcoming documentation for NNDK 3.5+.
Note that Let’s Encrypt and BuyPass have rate limits. This means that if you’re testing a lot or requesting many new certificates, you could end up having to wait days or weeks before your certificate order will be approved. If you’re testing a lot, consider using the Let’s Encrypt Staging endpoint, https://acme-staging-v02.api.letsencrypt.org/directory — you can do this easily by adding “true” to the Let’s Encrypt ACME client constructor: LetsEncryptAcmeServletObject acme_client(true);
Also, our ACME client currently does not support EAB (External Account Binding) or issuer-specific APIs, which means that Let’s Encrypt, BuyPass, and self-hosted ACME issuers are the best choice for now: many other providers want you to have an account with them before they’ll issue you a certificate. You can see a listing of ACME SSL providers here: https://acmeclients.com/certificate-authorities/
Wrap-up
Now your project can create and automatically renew its SSL certificates, supported by all major browsers over HTTPS and many more TLS-enabled applications! We hope your projects benefit from the enhanced security and ease of protecting your NetBurner device with industrial grade encryption.
If you have any questions or feedback about certificates, ACME, or NetBurner we welcome your comments on our Forums or at sales@netburner.com or support@netburner.com.