Automatic Onboard Trusted Certificate Creation with an ACME CA

To help developers tackle the growing burden of implementing and managing security on embedded and IoT devices, NetBurner now offers the ability for automatic onboard trusted certificate issuance via the ACME protocol. This means that modules running NNDK 3.5+ can in just a few lines of code (assuming a valid public IP and DNS name) request, install, and renew valid certificates that are trusted in all major browsers.

See the ACME example in <nndk_install>\examples\SSL\acmeservlet or blog post at https://www.netburner.com/learn/new-feature-easy-ssl-certificates-with-acme-and-lets-encrypt/ for more information.

If a valid public IP and DNS name isn't an option, consider one of these other options:

Automatic Onboard Self-Signed Certificate Creation

With very little effort (a single line of code, in fact), NetBurner modules acting as a server and running NNDK 3.x can automatically generate a self-signed certificate that can be used in secure SSL communications.

This feature is designed to allow engineers to have maximum control over the certificates that are used by their devices and can be modified in several different ways. Currently, the default behavior is as follows:

1) If a certificate is manually loaded on the module prior to the initialization of the SSL server, that certificate will be used, and the device will generate nothing.
2) If a TLS connection is attempted, either through SSL_connect(), SSL_accept(), or StartHttps(), and the device does not have a certificate loaded already, one will be generated automatically.
3) If a certificate has been generated previously and a new certificate is manually loaded on the device, the newly loaded certificate will be used in place of the automatically generated one. This will take place once the device has gone through a power cycle. The automatically-generated certificate will still be available on the module.
4) If ENABLE_AUTOCERT_REGEN is defined (found in predef.h), then the module will periodically check to see if the auautomatically-generated cert has expired, and if it has, it will automatically generate a new one. How often it is checked is defined by AUTO_CERT_GEN_CHECK (also in predef.h), and defaults to once per minute.

Certificates generated with this functionality are good for one year. These certificates live in non-volatile memory and will survive if the device is powered off. The auto-generated certificate creation system has been extended substantially since it was first introduced. The following examples are available to demonstrate the capabilities of the system, including several examples for advanced users who need more control over how the certificates are generated. The are located in <nndk_install>\examples\SSL\SslOnboardCertGeneration:

Simple: Shows how to initialize the system to enable onboard certificate generation.
Advanced: Shows how to manually call SSL_CreateNewSelfSignedCert() with properly formatted alt names.
CompiledCa: Shows how to create a custom self signed cert function that uses a compiled in Certificate Authority to sign the generated certificate.

When generating the certificate, the random number generator will need to be properly seeded. This is done by analyzing serial and network traffic. Pinging the device or visiting the device's config page from a browser will speed this process up.

By default, the certificate is generated using ECC with SECP384R1. This can be changed to an RSA key by undefining ENABLE_ECCKEY_CREATE in nburn\libraries\crypto\platform\<platform name>\user_settings.h, and then rebuilding your application. To specify what curve or RSA key length is used in certificate generation, define DEFAULT_KEY_TYPE as one of the values defined by SslKeyType_t.

Manual Private CA Certificate Creation

The NNDK ships with some open source tools for the generation and maintenance of SSL privately-issued keys and certificates. In the \nburn\CreateCerts directory there is a ReadMe.txt file which provides information on the .bat and .sh scripts used to make the creation process easier. Please refer to these files if you want more information.

These scripts are thin shell script wrappers around OpenSSL. OpenSSL is usually included in the NNDK at \Nburn\gcc\msys\1.0\bin\openssl.exe. OpenSSL is subject to the OpenSSL License, which is not part of the NetBurner License.

Obtaining Certificates via a third-party Certificate Authority

If you are going to have your certificates signed by an external entity, they will need a CSR file.

Note: The common name you enter in this step must match the deployed DNS name or IP Address of the Server it will be used on.

Open a command prompt/DOS window
Navigate to the directory that you want to house your device files
To make a Device Certificate Request file, execute the command (and press the Enter key when finished): openssl genrsa -out Server.key 1024 openssl req -new –key Server.key –out Server.csr
Send this Server.csr to the CA that will create your certificate.
Make sure you request your certificate in PEM format (which is typical for open source software like Apache: it's just plain text.)

When you get the certificate (usually something like example_com.crt) it will usually come with CA certificates and/or Chain certificates. These are important for helping other SSL clients or servers validate your certificate since every single CA isn't installed on every single device: instead, your certificate will often be issued by some Intermediate, and there is a chain of trust that eventually goes back to some Root CA which is installed on most devices. So, we want to help that chain be unbroken by providing others with the full chain:

Open your new certificate and the CA and/or Chain certificates in a text editor.
Review all the open certificates (you may need to scroll significantly in the Chain file) and see if the Chain file includes your new certificate at the top (unlikely) or the separate CA certificate at the bottom (also unlikely) – we don't want to duplicate anything in the next steps.
Create a new file called something like device_chain.crt
Copy-paste in order from top to bottom:
- Your new certificate (if not duplicated below)
- The chain certificates (in order from most intermediate to most root, though you won't be able to see this without using some certificate parsing tool)
- The root certificate (if separate and not duplicated above)
Use this device_chain.crt instead of device.crt in the Manual Certificate Installation instructions below in order to install it on your device. This will provide the full chain of trust to wolfSSL, which will allow other devices to securely talk with yours with much fewer issues.

Warning: If you lose the Server.key file associated with this particular device, then you will not be able to use the certificate file they send back. Once you have a signed certificate and private key, you may discard the Server.csr file: it's only used for that request.

Manual Certificate Installation

The compfile utility converts .crt and .key files to C++ source code files that can be built into your application (note this implies that each device needs its own application image). It is already part of in the batch and shell files mentioned previously. This section is included in the event you wish to run it separately against your .crt and .key files.

Open a command prompt in \nburn\CreateCerts\ECDSA or \nburn\CreateCerts\RSA, depending on the type of certificate you are converting.
Execute the commands: compfile device.key comp_key comp_key_len key.cpp compfile device.crt comp_cert comp_cert_len cert.cpp

Note: comp_key, comp_key_len, comp_cert, and comp_cert_len all refer to global variables available in the application that represent the key data, the length of the key data, the cert data, and the length of the cert data respectively.

Adding the Module to your Code Set

Take the key.cpp and cert.cpp files previously created and import it into your project directory. If you are using command line tools, copy it to your project directory and add it to your makefile.

Testing Your Certificates

The batch and shell files checkcert and checkkey can be found in \nburn\CreateCerts\ECDSA or \nburn\CreateCerts\RSA. For example: checkcert device.crt checkkey device.key

Creating a Certificate Authority List

To create a CA List that will hold all of the CA certificates you are willing to accept, you can either compile the certificate data into your project, or you can load it dynamically from a flash drive.

To use the compiled in data, create a header file in your project directory that will hold the certificate data. In this file, create a const char array for each certificate that is initialized as a string literal with each corresponding CA certificates’ data. Make sure to take note of the length of the array, as it will passed into SSL_connect() as function parameters. The example nburn\examples\SSL\SslClientVerifyPeerBasic demonstrates this method.

To use an SD card or onchip flash to store the certificate data, please see the example nburn\examples\SSL\SslClientVerifyPeerEffs for further guidance. In that example, we initialize the SSL system with a call to SslInit() before we start the HTTPS server so that we might add the certificates with calls to SSL_AddCertToClientCaList() for each certificate that we want to load. In this examplewe do this before the calls to SSL_connect() so that we can add multiple certificates stored on the SD card or onchip flash.