Secure TLS Client


This example demonstrates how to use the ZentriOS tls_client command to connect to a secure TLS server using a self-signed TLS certificate. The TLS server runs on a computer using python.

The following steps are covered by this example:

NOTE: The procedures below for running OpenSSL commands, and running the Python TLS server script, will work on Linux, Mac or Windows computers with the correct software packages installed. The examples shown are for a Linux machine. Notes are provided where a variation is required for a different platform, and references for Windows in particular are provided in the final section at the bottom of the page.

TLS Certificate Primer

TLS certificates are used to:

Certificate File Types

There are two types of files used in TLS connections:

Certificate Types


For the following steps in which certificates are generated, it is assumed you have OpenSSL installed on your computer and OpenSSL is in the PATH environment variable i.e. you can execute OpenSSL directly from a command line. OpenSSL may be downloaded here: or on Ubuntu, run the command: ~$ sudo apt-get install openssl The manual for OpenSSL may be found here:

In some instances, it may be necessary to set the RANDFILE environment variable to avoid OpenSSL errors such as ''unable to write 'random state'''. To temporarily set the RANDFILE environment variable to a local file, use the following command:

set RANDFILE=.rnd

Generating a Self-Signed CA Certificate

The first certificate to generate is a self-signed Certificate Authority (CA) certificate. This is the root certificate from which all other certificates are derived.

We start by generating the CA cert key. This is the most sensitive file in your secure TLS system. This should be placed in a secure location.

~$ openssl genrsa -aes256 -out my_ca.key 4096

After executing this command OpenSSL prompts for a password. This is used to secure this CA key. This is the same password used for the rest of the process.

Next we create the self-signed CA cert:

~$ openssl req -new -sha1 -x509 -key my_ca.key -out my_ca.crt

OpenSSL prompts for various values. Press enter to accept a default value. At the 'Common Name' prompt, you can enter any name, for example 'my_cert'.

Next, convert my_ca.crt to .pem format:

First convert to an intermediate .der format

~$ openssl x509 -in my_ca.crt -out my_ca.der -outform DER

Now convert the .der to .pem:

~$ openssl x509 -in  my_ca.der -inform DER -out my_ca.pem -outform PEM

~$ Delete the temporary .der file: > rm my_ca.der For a Windows platform, use del instead of rm.

You have now generated the self-signed CA certificate in the required .pem format.

Generating a Server Certificate

Now that we have a CA certificate, we need to generate a server certificate. This is what our python server will use.

To generate the server certificate, you need to obtain the IP address of your computer on the local network. This is the IP address the module will use to connect to the python server (running on your computer).

For this example, we will assume the local IP address is:

NOTE: At every point where this address appears in the procedure below, you should substitute the IP address of the computer used to run the python TLS server script.

First generate the private key for our server certificate:

~$ openssl genrsa -aes256 -out 1024

OpenSSL prompts for another password. This can be the same as the CA cert's or different.

Next we need to create a Certificate Signing Request (CSR).

~$ openssl req -new -sha1 -key -out

OpenSSL prompts for various values. Press enter to accept default values until reaching the 'Common Name' prompt, then ...

... AT THE PROMPT 'Common Name': enter the IP address of the computer! <- This is very important.

Afterwards, when OpenSSL asks for a 'Challenge password', do NOT enter anything, just press Enter.

Now, remove the passphrase on the server key to avoid the need for manual entry of a passphrase when the server starts:

~$ cp
~$ openssl rsa -in -out 
~$ rm

For a Windows platform, you may need to use copy instead of cp and del instead of rm.

Next we generate the server certificate:

~$ openssl x509 -req -in -CA my_ca.crt -CAkey my_ca.key -out -set_serial 01

We now have everything needed to connect the ZentriOS device to the python server.

Starting the Python TLS Server

To start the server, run the script, supplying the server IP address as an argument:

~$ python


Loading the CA cert onto the Module (using ZentriOS)

Next we'll load the CA cert onto the ZentriOS device. Open my_ca.pem in a text editor such as Notepad++ and determine the size of the file (number of characters, including whitespace and carriage returns). Issue the following ZentriOS command:

> file_create my_ca.pem <file size>

Then copy and paste the contents of my_ca.pem into the serial terminal. This will write the CA certificate to the flash file system on the module. It is critical that the line endings of the file are correct. The .pem format expects a single \n (0x0A) line terminator, and a single \n character at the very end of the file.

Connecting to the Python TLS Server

We're now ready to connect the ZentriOS device to the python TLS echo server. Assuming ZentriOS already has valid credentials for the local Wi-Fi network, issue the following command (don't forget to specify the port number 3000 and to append my_ca.pem):

> tls_client 3000 my_ca.pem

If everything is working, ZentriOS responds with text similar to:

Resolving host:
[2014-11-03 | 05:58:34: Opening:]
Connecting (TLS):
[2014-11-03 | 05:58:34: Opened: 0]

Issue the ZentriOS command (to write to the python server):

> write 0 15
Hello World!!!

You should see Hello World!!! in the python server terminal on the PC.

Issue the ZentriOS command:

> read 0 1000

Hello World!!! should be returned.


The TLS server is created with a Python script:

The following example BASH scripts are provided to help automate the OpenSSL parts of the process described above if required.

To run this example on Windows, the following software packages are needed:

Change Log

ModifiedChangesZentriOS Version