cert2arduino

Certificate to Arduino Header Converter

A simple npm command-line utility that allows visitors to convert a downloaded certificate file (a .pem or .crt file) into a header file you can use with an Espressif device (ESP-32, for example) in the Arduino IDE to make secure connections (HTTPS) to remote servers.

Learn more: Arduino ESP32 Connect to a Server Using HTTPS.

Background

While working on an ESP32 project, I realized that I needed a way to make a secure (SSL) connection to a web server to retrieve some data. In the example code included with the Arduino IDE as well as some online tutorials, I realized that I need to download the certificate for the server, then convert it into a format that an Arduino sketch could use to make secure connections to the server.

Basically, the download certificate is a text file with a specific format:

-----BEGIN CERTIFICATE-----
MIIhvzCCIKegAwIBAgIRAITxhzWmYmL5EFvp9GRTHY0wDQYJKoZIhvcNAQELBQAw
OzELMAkGA1UEBhMCVVMxHjAcBgNVBAoTFUdvb2dsZSBUcnVzdCBTZXJ2aWNlczEM
MAoGA1UEAxMDV1IyMB4XDTI0MTIwOTA4MzYzNFoXDTI1MDMwMzA4MzYzM1owGjEY
.
.
.
mcNL3qT7c96/YJZvxPiXDCfAvaKv3zYq+vH1O4hpJ1XYm7SFeHFQ5AyisnKP4z7U
uDcTXhOPTOtzsVMEaRbCaYwq+y/4AxLasMtUj4h20s9E2BwMgSy8jjbvlTZKli4D
hSaI
-----END CERTIFICATE-----

The file contains a header (-----BEGIN CERTIFICATE-----) and footer (-----END CERTIFICATE-----) that delimits the certificate code. Everything in between is the raw code of the public certificate.

Note: That particular file is 184 lines long, so I used the three periods vertically in the middle to indicate that part of the file was cut out of the example.

To use that certificate in an Arduino sketch, you must first convert it into a format that the Arduino IDE understands. Specifically you must convert it to a file that:

1. Defines a variable name for the certificate. You'll reference this name in the code that leverages the certificate. In the example code below, this is the const char* cert= code that creates a variable called cert for the certificate.
2. Adds a continuation character (\) at the end of every line (except the last one) telling the Arduino compiler that there are more lines in the current statement.
3. Quotation marks (") at the beginning and end of each line (before the continuation character).
4. A newline (\n) at the end of each line before the ending quotation mark.

Here's what the modified file looks like (with the same indicator showing that I dropped a bunch of lines from the output):

const char* cert= \
"-----BEGIN CERTIFICATE-----\n" \
"MIIhvzCCIKegAwIBAgIRAITxhzWmYmL5EFvp9GRTHY0wDQYJKoZIhvcNAQELBQAw\n" \
"OzELMAkGA1UEBhMCVVMxHjAcBgNVBAoTFUdvb2dsZSBUcnVzdCBTZXJ2aWNlczEM\n" \
"MAoGA1UEAxMDV1IyMB4XDTI0MTIwOTA4MzYzNFoXDTI1MDMwMzA4MzYzM1owGjEY\n" \
.
.
.
"mcNL3qT7c96/YJZvxPiXDCfAvaKv3zYq+vH1O4hpJ1XYm7SFeHFQ5AyisnKP4z7U\n" \
"uDcTXhOPTOtzsVMEaRbCaYwq+y/4AxLasMtUj4h20s9E2BwMgSy8jjbvlTZKli4D\n" \
"hSaI\n" \
"-----END CERTIFICATE-----\n";

I found that the Arduino Compiler doesn't care if the file has the continuation character (\) appended at the end of each line:

const char* cert= 
"-----BEGIN CERTIFICATE-----\n"
"MIIhvzCCIKegAwIBAgIRAITxhzWmYmL5EFvp9GRTHY0wDQYJKoZIhvcNAQELBQAw\n"
"OzELMAkGA1UEBhMCVVMxHjAcBgNVBAoTFUdvb2dsZSBUcnVzdCBTZXJ2aWNlczEM\n"
"MAoGA1UEAxMDV1IyMB4XDTI0MTIwOTA4MzYzNFoXDTI1MDMwMzA4MzYzM1owGjEY\n"
.
.
.
"mcNL3qT7c96/YJZvxPiXDCfAvaKv3zYq+vH1O4hpJ1XYm7SFeHFQ5AyisnKP4z7U\n"
"uDcTXhOPTOtzsVMEaRbCaYwq+y/4AxLasMtUj4h20s9E2BwMgSy8jjbvlTZKli4D\n"
"hSaI\n"
"-----END CERTIFICATE-----\n";

Making those changes to the certificate file isn't impossible, but at 184 lines for this particular example, it's pretty tedious work If you have to do this frequently for certificates for different sites. Since I don't like doing that type of tedious work, I decided to build a utility that handles the process for me (and you).

That's why you're here.

To use the utility, you must download a server's public key into a .pem or .crt file. I'm not going to show you how to do that here, just follow the instructions found online. Here's a good example: How to Download the SSL Certificate From a Website in Windows.

Installation

To install the CLI command, open a terminal window or command prompt and enter the following command:

npm install -g cert2arduino

Operation

Open a terminal window or command prompt and navigate to the folder containing the downloaded certificate file.

If you installed the utility using the command at the end of the previous section, enter the following command:

cert2arduino

If you didn't install the package, you can run it using:

npx cert2arduino

The utility first prompts you to select the downloaded certificate file:

Cert2Arduino

Converts a certificate file to a C++ array for use in Arduino sketches.

? Select the input file to convert: » - Use arrow-keys. Return to submit.
>   firebase.crt
    google.crt

Next, it prompts you for a couple of other configuration settings:

Cert2Arduino

Converts a certificate file to a C++ array for use in Arduino sketches.

√ Select the input file to convert: » google.crt
√ Append backslash to output lines? ... no / yes
√ Enter the name for the Arduino certificate variable: ... cert

Input file: D:\dev\node\cert2arduino\google.crt
Output file: D:\dev\node\cert2arduino\cert.h

Done!

As I mentioned earlier, I noticed that the Arduino compiler doesn't seem to care if the certificate file has backslashes at the end of each line or not. So the "Append backslash to output lines?" option controls that.

Next, the utility prompts for the name of the variable embedded in the generated header file.

Enter a name for the certificate variable exposed by the generated header file (or accept the default "cert"). In this example, and the example generated file shown above, I used cert. You can use anything that you want here as long as it is a valid C variable name.

A valid C variable name can contain letters, digits, and underscores, but must always start with a letter or an underscore; it cannot start with a number, contain spaces, or use reserved keywords like "int" or "float" - examples include: "age", "my_variable", "totalSum", "x", "y".

Reference: C Variable Names (Identifiers).

At this point, the utility reads the cert file, converts it to the proper format for c header files, and writes it to a file using the variable name as the file name (plus the .h extension) as shown in the example.

If you run the utility in Visual Studio Code, the generated file will immediately open in an editor window.

Arduino Code

To use the header file in your Arduino sketch, add the following line to the top of the sketch's main file:

#include "cert.h"

That's it, reference the file's variable name in your code like this:

client.setCACert(cert);

---

If this code helps you, please consider buying me a coffee.