NetBurner 3.3.8a
PDF Version
SSL/TLS Programming Guide

SSL/TLS Overview

The NetBurner SSL/TLS library makes SSL/TLS as easy as possible. However, if this is your first experience with SSL/TLS, some outside reading on how public key cryptography works is extremely helpful.

When you use SSL/TLS to connect to (for example) with a normal web browser, you will not need to know anything about certificates. This is because Amazon purchased a certificate from Verisign and your browser vendor preinstalled Verisign, as an entity that can sign trusted certificates.

Above, is a picture of a perfectly normal TCP or SSL/TLS connection; the client (most often a browser) has connected through the network to a server. If we do not have any entities doing bad things on our network then there is no need for SSL/TLS. However, if the data we are sending is worth stealing, we might have a very different network picture (below).

If our connection is routed through a third party (a normal TCP connection), we have no guarantee that this third party is not a "bad guy" trying to steal or modify our data. The SSL/TLS protocol was designed to eliminate this man in the middle attack. SSL/TLS is designed not only to make sure that the data we send over the network is hidden from snooping eyes, but it is also designed to make sure we are connected to the proper server without any "bad guys" in the middle. This verification is done with Public Key (PK) Cryptography and a hierarchy of trust.
Why do we trust a doctor when we go to the emergency room? We trust the doctor we have never met because we trust the hospital to employ qualified doctors. The hospital vouches for his skills and we trust the hospital. His medical school also vouches for him by giving him a diploma with his name and the schools seal or signature. We trust the school, we trust the hospital, and thus we trust the doctor.
SSL/TLS works in a very similar way. When a client connects to the server sends the client a certificate. This certificate has three major elements:

  • A name (i.e. who is this server)
  • A public key (e.g. think of an open padlock)
  • A signature (by a trusted third party that vouches for the name and the public key)

A doctor's diploma is very similar; it also has three major elements: The doctor's name, the type of degree and the medical school (that vouches for the doctor). For example, Bob and George both graduate from Harvard Medical School. They both have Harvard diplomas. However, the diplomas are unique to each doctor. The diplomas are not interchangeable. Bob's diploma would be of no use to George and vice versa. This illustrates the first key point about SSL/TLS.

Key Point #1: Each and every SSL/TLS server must have a unique certificate. Note: You cannot reuse an SSL/TLS server certificate. The certificates are distinguished by the "common name" or "CN" on the certificate.

If you went into a new doctor's office and saw a diploma from Harvard medical school, you would feel comfortable with the doctor's skills. You trust Harvard and Harvard will vouch for this doctor. If instead, the diploma were from the Medical School of Zaire, you would probably be more skeptical. We do not have the same inherent trust of this school as we did with Harvard.

In SSL/TLS as a client, we have to decide who we will trust to sign our certificates. This list of trusted certificate authorities must be explicitly configured into the client. When the web browser or OS was installed on your PC, it probably installed a list of trusted certificate authorities. With the NetBurner SSL/TLS library, we have to explicitly decide whom we are going to trust to sign server certificates. This leads to key point #2.

Key Point #2: An SSL/TLS client must be pre-configured with a list of Certificate Authorities (CAs) that it will trust to sign server certificates. This list can be common across all the clients and does not have to be unique.

What do I need to do to make SSL/TLS work?

  • You must create or choose a certificate authority. Note: If you create a certificate authority, you will also have to create a set of public/private keys for this authority.
  • You must create public/private keys and a certificate for each SSL/TLS server and have the certificate signed by the certificate authority you have chosen.
  • You must configure the clients with the list of certificate authorities it should trust.

How do I find or create a certificate authority?

Using the medical school example, you can go to Harvard pay lots of $$$ and get a diploma that is trusted by everyone. You can also choose to start your own medical school and issue diplomas. Almost everyone in the world would trust a Harvard diploma. Almost no one will trust a "Bob's Medical School" diploma, unless you spend the time convincing them that it is a quality medical school. In the end, you will likely only be able to convince your family, and then only for non-life threatening needs.

SSL/TLS certificates are a lot like medical schools; you can go and purchase server certificates. To see what a certificate looks like, open your web browser (e.g. Internet Explorer), and connect to (notice the s on the end of https). On Internet Explorer's menu, choose File then Properties. Now, click the Certificates button, and look at all the tabs shown in this section.

How do I know whom my browser trusts?

On your (Internet Explorer) browser's menu - choose Tools then Internet Options. Open the Content tab, click the Certificates button, and open the Trusted Root Certificate Authorities tab. Add Verisign or Thawte and every browser in the world will trust your certificate and your server.

If you want to save some money and create your own certificate authority then you can do so. However, none of the clients will accept your certificate until you convince them to add "Bob's Certificate Authority" to their list of trusted certificate authorities. If, the users using the embedded SSL/TLS system you are deploying are all in one business entity, then it is relatively simple to add your own certificate authority to the list of trusted authorities. If you are responsible for both the client and server end of the connection, it is even easier; you can configure the clients to accept a single server authority - yours.

SSL/TLS is based on Public Key Cryptography (PK) and a little bit of background on PK is necessary in order to deploy a secure SSL/TLS solution. Public Key Cryptography is different from Symmetric Key Cryptography. In PK, the keys used for encryption are broken into two parts, much like a padlock (the public part) and a key (the private part). If you give someone an open padlock and a steel box, they can put things into the box, close the lid, and lock the lock. Unless they have the key to the lock, they cannot open the box. They can be confident that if they mail you the box, none of the mailmen along the way can look inside. Only the person who holds the (private) key to the padlock can open the box. For additional information on Public Key Cryptography, please read the Cryptography FAQ (

When the SSL/TLS client connects to a server, the server sends back a certificate with a public key (open padlock). This certificate also includes the name of the server and a signature vouching for both the public key and the name. If any part of the certificate is changed, the signature will compute to be invalid.

So, if we have a "bad guy" in the middle, he can watch the padlock going from the server to the client. But, when the client puts his secret information into the box and locks it, the "bad guy" cannot see inside. He only knows that the client sent something in the box to the server. The secrets in the box are safe from the prying eyes of the "bad guy". This safety only exists if the server has done a good job of protecting the private key. If the "bad guy" sneaks into the server room, logs on the server console, and makes a copy of the private key, he can intercept all of the traffic. He can also change the content at will. This leads to key point #3.

Key Point #3: When using Public Key Cryptography (as SSL/TLS does), the system is only as secure as the security of the private key. Since a server needs access to the private key to unlock the data from the client, the private key must exist on the server.

Key Point #3 Corollary: If the private key exists on the server, then the system is only as secure as the physical security of the server. If the server is not physically secure, then someone (i.e. the "bad guy") can attach an emulator or other hardware to the server and read out the private key.

For example, suppose the "bad guy" wants to intercept your credit card number when you send it to Amazon to order a book. We have already shown that he cannot read the data unless he has Amazon's private key. However, he has one other option - he can pretend to be Amazon and offer his own certificate to you, the client. If this certificate is properly signed by a Certificate Authority the client trusts, then client will accept the connection. If any "Certificate Authority" in the list of trusted authorities is compromised, then the system is insecure. If the "bad guy" has the ability to add a new "Certificate Authority" to the client, then he can completely compromise the system. This leads to key point #4.

Key Point #4: If the ability to add a "Certificate Authority" to the client's list of trusted authorities is not secure, then system is not secure.

Key Point #4 Corollary: If the list of trusted "Certificate Authorities" exists on the client, then the system is only as secure as the physical security of the client. If the client is not physically secure, then someone (i.e. the "bad guy") can attach an emulator or other hardware to the client and add a "trusted" authority.

These last two key points imply that it is not possible to build a system that is more secure than the physical security of the device being secured.

Important: All the cryptography in the world will not help if someone can gain access to your computer and hide a bug inside the keyboard; or even easier, add or modify a system file to record your keystrokes and periodically send them over the internet to some nefarious foe.

Recommended Reading

For an excellent overview of computer security:

  • Secrets and Lies by Bruce Schneier (ISBN 0-471-25311-1)

For a detailed review of cryptography:

  • Applied Cryptography by Bruce Schneier (ISBN 0-471-11709-9)

For a detailed description of the SSL/TLS protocol:

  • SSL and TLS by Eric Rescorla (ISBN 0-201-61598-3)

For a reference on the math and methods in cryptography (this is a heavy duty book):

  • Handbook of Applied Cryptography by Menezes, Oorschot and Vanstone (ISBN 0-8493-8523-7)

Onboard Self Signed Certificate Creation

To help developers tackle the growing burden of implementing and managing security on embedded and IoT devices, NetBurner now offers the ability for onboard self-signed certificate generation. This means that 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/TLS 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/TLS 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.

Creating Self-Signed Certificates

The NetBurner SSL/TLS library provides some open source tools for the generation and maintenance of SSL/TLS self-signed keys and certificates. These tools are based on OpenSSL and subject to OpenSSL License. The NetBurner SSL/TLS library code subject to the standard NetBurner License (located by default in \Nburn\docs).

  • openssl.exe: Creates certificates and keys
  • compfile: Creates .cpp files from certificates and keys

There is a readme.txt file in \nburn\CreateCerts that provides information on .bat and .sh files used to make the creation process easier. Please refer to the script files if you want more information on the OpenSSL options used to create the certificates and keys. Certificates should use the PEM format.

Creating a Certificate Authority (CA) Certificate and Key

This step creates a CA you can use to sign certificates. Important: You should only have to do this step once. The key file created in this step should be protected as the security of all your certificates depend on it. You have two choices to protect this key file. Note: If you want the key to not be protected by a pass phrase then leave the -des off the genrsa command.

  • Open a command prompt in \nburn\CreateCerts\ECDSA or \nburn\CreateCerts\RSA, depending on the type of certificate you want to create.
  • Run makeca to create CA.crt and CA.key, which will be used by other script files to sign server and client certificates and keys.
  • You will be prompted to answer some questions. If you require more detailed information please refer to the OpenSSL website and documentation.

Creating a Server Certificate and Key for Your Device

You will need to create a certificate and key for each device you deploy, and the Common Name in the certificate must match each of your device's name. For example, if I have 2 devices and am using DNS, then I could name them Device1 and Device2, and the certificate would need the CN to match. If I did not have DNS, I could use their IP addresses as the CN. However, if their IP address changes, the certificate would no longer be valid because the CN would not match.

  • Open a command prompt in \nburn\CreateCerts\ECDSA or \nburn\CreateCerts\RSA, depending on the type of certificate you want to create.
  • Run 'makeserver' to create device.crt and device.key. The script will also invoke compfile to create cert.cpp and key.cpp in case you desire to use a compiled-in cert and key.
  • This certificate will be signed with the CA certificate created previously.

Converting a Certificate and Key to Code with <tt>compfile</tt>

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
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.

Using a Recognized Certificate Authority

If you are going to have your certificates signed by an external entity, they will need a Certificate Request 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.

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.

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 Certificate Authority Lists

Creating a CA List file

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/TLS 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.