Secure TLS Client

Overview

This example demonstrates how to use the Gecko OS 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

OpenSSL

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: https://www.openssl.org/community/binaries.html or on Ubuntu, run the command: ~$ sudo apt-get install openssl

The manual for OpenSSL may be found here: https://www.openssl.org/docs/

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: 192.168.1.228

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 192.168.1.228.key 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 192.168.1.228.key -out 192.168.1.228.csr

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 192.168.1.228.key 192.168.1.228.key.tmp
~$ openssl rsa -in 192.168.1.228.key.tmp -out 192.168.1.228.key
~$ rm 192.168.1.228.key.tmp

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 192.168.1.228.csr -CA my_ca.crt -CAkey my_ca.key -out 192.168.1.228.crt -set_serial 01

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

Starting the Python TLS Server

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

~$ python echo_tls_server.py 192.168.1.228

NOTES

Loading the CA cert onto the Module (using Gecko OS)

Next we'll load the CA cert onto the Gecko OS device.

Using the Web App Files Tab

The easiest way to do this is to use the Gecko OS Web App provided with Gecko OS. To start the webapp, issue the following command to the device using a Gecko OS terminal: 

> setup web

This starts the Gecko OS softAP and webserver. Connect your computer to the Gecko OS Wi-Fi network. By default, the network name is Gecko OS-XXX , (where XXX is the last 3 digits of the device MAC address).

Then open a web browser and enter the URL: http://setup.com

Wait for the Gecko OS webapp to load, then click on the Files tab. The Files tab enables you to drag and drop files from your computer to the file system on the Gecko OS device.

On your computer, find the CA certificate that you just created: my_ca.pem

Drag this file onto the Gecko OS webapp target area where it says Drop files here . Alternatively, click the button labelled Click to add files .

That's it! The CA certificate is now stored in non-volatile memory on the Gecko OS device flash file system.

Using File Create

You can also use the file_create command to load a file onto the Gecko OS device.

Open my_ca.pem in a text editor such as Notepad++ and determine the size of the file (number of characters, including whitespace, line feeds and carriage returns). Issue the following Gecko OS 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.

The file_create command requires the exact file size, so it is critical that the line endings of the file are correct.

Note : that the .pem format expects a single \n (0x0A) line terminator, and a single \n character at the very end of the file, so ensure that your text editor does not convert line endings.

Connecting to the Python TLS Server

We're now ready to connect the Gecko OS device to the python TLS echo server.

In Gecko OS-W you can use the TCP API to connect.

Use gos_tls_connect to connect to the TLS server.

Use gos_tcp_write to write to the TLS server.

Use gos_tcp_read to read from the TLS server.

Assuming Gecko OS 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 192.168.1.228 3000 my_ca.pem

If everything is working, Gecko OS responds with text similar to: 

Resolving host: 192.168.1.228
[2019-01-01 | 05:58:34: Opening: 192.168.1.228:3000]
Connecting (TLS): 192.168.1.228:3000
[2019-01-01 | 05:58:34: Opened: 0]
0

Issue the Gecko OS write command or use gos_tcp_write to write to the python TLS server: 

> write 0 15
Hello World!!!

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

Issue the Gecko OS read command or use gos_tcp_read : 

> read 0 1000

Hello World!!! should be returned.

Scripts

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:

Supporting Gecko OS Versions

Change Log

Modified Changes
2019-01-01 Created