NodeMCU/ESP8266 and SSL/TLS/HTTPS

Security is always good. But you need to pay attention to implement it well, otherwise it can be very harmful.

Let's say that we want to secure the communication between our NodeMCU (ESP8266) and a server (cloud/LAN/whatever). Starting from NodeMCU devkit 2.4, you have a class named WiFiClientSecure, which implements a TLSv1.2 client with some recent (and secure) ciphers, such as aes_128_cbc_sha256.

Trust me, you want to use this class. Do not try to implement another TLS class if you don't know what you're doing.

Before seek for some examples, let's clear some points:

• WiFiClientSecure is a subclass of WiFiClient, so you can use it as a drop-in replacement, and you can use all methods from the parent class
• connect() method of WiFiClientSecure will not return an error if the certificate is invalid - the check is up to you (later in this post you'll see how do this)
• the SDK doesn't contains root certificates (such as a browser do)
• you can check a certificate in two way: by checking its certification chain (as a browser), or you can check the certificate fingerprint itself ("certificate-pinning")

Checking the certificate fingerprint

Each certificate has its own fingerprint. It's hard to match with a (valid) private key, so checking the fingerprint is a valid method in order to secure a channel.

Pros:

• Simple and effective: if the certificate fingerprint is wrong, then simply the certificate is not valid
• There is no way to force a device to accept a certificate without altering its own code
• Easy to deal with self-signed certificates

Cons:

• You need to know the certificate fingerprint during compilation-time
• The fingerprint cannot change during the lifetime of the code build/version, so you cannot change/renew the certificate

This method is useful on self-signed certificates or with a certificate that is valid far beyond the software version lifetime, because you cannot generate two certificates with the same fingerprint (this means, for example, that you cannot use Let's encrypt certificates, as they expires after 90 days, unless you're planning to release a new version every 90 days).

Code example:

WiFiClientSecure client;
int result = client.connect("tls.host", 443);
if (result != 1) {
  // Something bad happened on connection
} else {
  // Socket is connected BUT the certificate is not verified yet
  // Verifying the certificate by using fingerprint
  if(client.verify("D1:D0: ... :7E, "tls.host")) {
    // Certificate is OK
  } else {
    // Certificate is invalid
  }
}

Checking the certificate trust chain

This method is the most widely used because of its versatility: the client checks for a signature from a trusted certification authority (from a local storage of certificates). So, even if the certificate changes, as long as it's signed by a trusted CA, the certificate is valid.

WiFiClientSecure doesn't handle a CA bundle file (yet), so if you want to check multiple certification authorities, you need to load them manually and check each of them. In the example, we'll see how to check only for one CA: it's trivial to convert it in a loop for checking multiple certificates.

Pros:

• The certificate can be changed (re-newed, re-issued, etc) without issues
• Easy to have multiple certificates (for example, one for each host of a cluster)

Cons:

• You need to embed the certification authority certificate (in the code or in a separate file/memory)
• If the CA is a separate file, and there are external ways to access that memory (eg. an SD card), it's trivial to tamper the CA store

Code example (in the example, ca_cert is the CA certificate binary loaded in memory, and ca_cert_len is the length of ca_cert memory area, in bytes):

WiFiClientSecure client;
int result = client.connect("tls.host", 443);
if (result != 1) {
  // Something bad happened on connection
} else {
  // Socket is connected BUT the certificate is not verified yet
  // Load CA certificate
  client.setCACert(ca_cert, ca_cert_len);
  // Verifying the certificate by using loaded certificate
  if(client.verifyCertChain("tls.host")) {
    // Certificate is OK
  } else {
    // Certificate is invalid
  }
}