Secure Element Demo

This app demonstrates how to use the Microchip ATECC608A Secure Element (SE) chip to issue a HTTPS request.

It demonstrates the following:

1. Generate self-signed certificates
2. Program certificates to SE
3. Run a local HTTPS development server
4. Issue HTTPS request to development server using the SE for authentication

Overview

This demo does the following:

1) Configures SE:
Before the SE can be used it must be configured and lock.
Configuring involves writing the SE 'configuration' zone and specifying how the various 'slots' can be used.
Once configured, the SE MUST be locked, the SE will not fully work until it is locked.

Locking is a IRREVERISLBE . Once the SE is locked it cannot be unlocked.

Configuration is done by:

1. Program app to device
2. Press Button 1 for 1s to invoking locking operation, see se_configure() for more details.

2) Generates a self-signed, root Certificate Authority (CA) certificate, root-ca.crt :
This certificate is the root from which all other certificates are signed.
The private key to this certificate is extremely sensitive (in production).

This certificate has two main parts:

• Public certificate : root-ca.crt : This is inherently insecure and distributed in the open.

                   This file is saved to the device's extended File System (unencrypted).  

• Private key : root-ca.key : In production, this key is extremely sensitive and should NEVER be distributed.

                    This is used to sign `test-server.crt` and `signer-ca.crt` (see below)

3) Generates a server certificate, test-server.crt :
This certificate is used by the local OpenSSL HTTPS server.
This certificate is signed by the root-ca.crt .
The device uses the root-ca.crt (which is stored on its extended File System)
to authenticate this server certificate.

This certificate has two main parts:

• Public certificate : test-server.crt : This is given to the device during the HTTPS TLS handshake

• Private key : test-server.key : In production, this key is extremely sensitive and should NEVER be distributed.

  NOTE: The server certificate is generated with an IP address of your local computer.

  If the IP address of your computer changes then this server certificate will no longer work.
  During the HTTPS TLS handshake, the device validates the IP address in the server certificate.
  If the IP address does not match the IP address of the server it is trying to connect then the connection will immediately fail.

  NOTE: In production you would NOT use an IP address but instead a domain name, e.g.: myserver.com

4) Generates a device certificate signing certificate, signer-ca.crt :
This certificate is used to sign device certificates.
This certificate is signed by the root-ca.crt .
This is what's known as an 'intermediate' certificate.
Recall the root-ca.key is very sensitive and should rarely be used.
The signer-ca.crt useful so that signer-ca.key can be used to sign the device certificates (which will happen often).

This certificate has two main parts:

• Public certificate : signer-ca.crt : This is stored inside the SE,

                                        the device uses this to create a certificate chain during a TLS handshake  

• Private key : signer-ca.key : In production, this key is extremely sensitive and should NEVER be distributed.

                                        This is used to sign `device.crt` (see below)

5) Generates a device certificate signing request (CSR) from the SE, device.csr :
When the SE is 'configured' (see section 1 above) a private key pair is generated in the SE.
The private key is used to authenticate the device with the server.
The private key NEVER leaves the SE. If the SE is tampered with this private key is destroyed.

During a HTTPS TLS handshake, the server requests the device's certificate, device.crt to authenticate the device.
To generate the device certificate, a CSR is required from the SE.

This example app features a Gecko OS command:

   se_gen_csr

This command invokes gos_atca_generate_csr() which instructs the SE to generate a CSR which
is signed by the SE's internal private key. The CSR, device.csr , is used in the next step to create the device certificate, device.crt

6) Generates a device certificate, device.crt :
The device certificate is used to authenticate the device with the server.
i.e. The device certificate is how the server knows the device is valid and not a hacked device.

The device certificate is effectively generated as follows:

device.crt = SIGN( device.csr , signer-ca.key )

i.e. The device CSR is signed by the 'signer' certificate's private key.

The 'chain of trust' is then:

root-ca.crt -> signer-ca.crt -> device.crt

During a HTTPS TLS handshake, the server just needs root-ca.crt to authenticate
the signer-ca.crt + device.crt certificate chain which is provided by the device.

7) Programs generated C struct templates:
During steps 4) and 6), template C structs are generated: See:

   <demo dir>/cert_templates/cert_def_1_signer.c
   <demo dir>/cert_templates/cert_def_2_device.c

The SE library uses these templates to convert the compressed certificates stored in the SE to DER format.

8) Saves credentials to SE:
After the credentials are generated and the templates are programmed to the device,
the following Gecko OS command is issued:

   se_save_creds

This saves the following information to the SE:

• root-ca.crt public key - This is needed to uncompress the signer-ca.crt
• signer-ca.crt - This is needed during the device authentication step of an HTTPS TLS handshake
• device.crt - This is needed during the device authentication step of an HTTPS TLS handshake

• hostname - Not technically needed, this shows how other metadata can be stored to the SE.

                            The demo uses this to determine the domain name of the server to issue the HTTPS request.

  After the credentials are saved the SE, the demo is ready to connect to the development server.

  NOTE: To reset the credentials, issue the Gecko OS command:

  se_reset

  After resetting, new credentials must be saved to the SE using the se_save_creds command.

Prerequisites

The following is required to run this demo:

OpenSSL

OpenSSL is an open-source crypto library: https://www.openssl.org/

In this demo it is used for the local development HTTPS server.

Linux and Mac users can install this library via command line, e.g.:

apt-get openssl

Windows users can install this library from here:
https://slproweb.com/products/Win32OpenSSL.html

Python 32-bit

Python 32-bit, 2.7 or 3.x is required to run the certificate generation scripts.
More details here: https://www.python.org/

Python Modules

Run the following command to install the required Python modules:

pip install cryptography pyasn1_modules pytz

Python Cryptography Module

The Python cryptography module is required: https://pypi.org/project/cryptography

You can install via command line with:

pip install cryptography

Python ASN1 Module

The Python pyasn1_modules module is required: https://pypi.org/project/pyasn1-modules

You can install via command line with:

pip install pyasn1_modules

Python Timezone Module

The Python pytz module is required: http://pytz.sourceforge.net

You can install via command line with:

pip install pytz

Demo Instructions

To run this demo, do the following:

1) Determine your computer's local IP address

Your computer will run a local HTTPS server. The device needs to know your computer's local network IP address to connect to the HTTPS server.

NOTE: If you have multiple interfaces, you must select the IPv4 address that is on the same network to which the device will connect

Windows

On Windows, issue the command:

ipconfig

Your local IP address is the IPv4 Address that is printed.

Linux/Mac

On Linux/Mac, issue the command:

ifconfig

Your local IP address is the addr: that is printed.

2) Program This Demo Application to Device

Program this demo app to the device with default settings.
This demo app needs to be programmed to the device
so that the setup scripts can issue commands to the SE to generate the device certificate.

Use the IDE or command line to program this demo as you normally would.

NOTE: Ensure the app is running on the device after programming.

3) Configure the SE

If necessary, you must configure the SE.
When the app starts and the SE needs to be configured, it will print something like:

SE not configured!
Press and hold button 1 to configure SE now

Press and hold button 1 for 1s to configure the SE.

Note About SE Locking

Before the SE can be used it MUST be configured and 'locked'.
Locking is a one-time operation.
After the SE is locked, the configuration is 'set-in-stone' and CANNOT be unlocked.

Due to security concerns there is no way around this.
The SE must be locked before it can be used. Once it is locked it cannot be unlocked.

If the SE was previously locked with a different configuration there is a chance this demo may still work
but its operation cannot be guaranteed.

4) Invoke Setup Script

Invoke the setup_demo.py Python script:

cd <demo directory>/resources/generation_scripts
python setup_demo.py --hostname <IP address from step 1>

NOTE: Ensure the device is connected before invoking the script

This script does the following:

1. Ensures the SE is configured
2. Generates a self-signed root CA certificate
3. Generates a local development server certificate
4. Generates a 'signer' CA certificate and C struct template needed by SE
5. Issues a command to the device to generate a Certificate Signing Request (CSR) from the SE
6. Uses the CSR to generate a device certificate and C struct template needed by SE
7. Waits for you to re-program app to device with generated C struct templates
8. After app is re-programmed, saves generated credentials to SE

4) Start the local HTTPS Server

NOTE: You can SKIP this step if the server was started in the previous step.

Start the OpenSSL HTTPS server. The device will issue a HTTPS request to this server
using the SE for device authentication.

Windows

On Windows, invoke the following commands:

cd <demo dir>/resources
.\openssl_server.bat

Linux/Mac

On Linux/Mac, invoke the following commands:

cd <demo dir>/resources
./openssl_server.sh

NOTE: You must have port 4433 open to run these scripts.

5) Configure Device's Wi-Fi Credentials & Bring Up Network

Go to the Gecko OS command console and configure your local network's Wi-Fi credentials:

network_up -s

OR

set wlan.ssid <your network name>
set wlan.passkey <your network password>
save
network_up

After the network is brought up, the device should begin issuing HTTPS requests to
the local OpenSSL HTTPS server.

If everything works correctly, you should see something like:

<HTML><BODY BGCOLOR="#ffffff">
<pre>


s_server -accept 4433 -no_comp -msg -state -tlsextdebug -no_ticket -www -CAfile .\credentials\root-ca.crt -cert_chain .\credentials\test-server-chain.crt -cert .\credentials\test-server.crt -key .\credentials\test-server.key -msgfile .\server.log -Verify 9
Secure Renegotiation IS supported
Ciphers supported in s_server binary

...

printed to the Gecko OS console.
This is the standard response generated by the OpenSSL HTTPS server.

6) Congratulate Yourself!!

If you've successfully made it to this point, then you've just done the following:

1. Configured SE
2. Generated self-signed certs
3. Programmed certs to SE
4. Ran local HTTPS server
5. Issued client authenticated HTTPS request to server using the SE

Please note what's happening in part 5).

1. Device issues HTTPS request and starts TLS handshake
2. The server gives its test-server.crt to the device
3. The device validates that the IP address it's trying to connect matches the IP address in the test-server.crt
4. The device uses root-ca.crt on its File System to validate test-server.crt
5. At this point the server is authenticated, the device knows it's talking to the right server
6. Server requests device's certificate
7. Device retrieves device.crt + signer-ca.crt from the SE and constructs a certificate chain
8. Device signs certificate chain using SE
9. Device returns signed certificate chain to the server
10. Server uses root-ca.crt to validate the device's certificate chain
11. At this point the device is authenticated, the server knows its talking to a valid device
12. The device uses the SE to generate a session key to encrypt the connection, this key only lasts for as long as the connection is opened
13. Both the server and device are authenticated, and a unique session key is used to encrypt all data that is transferred between the device and server

Fantastic, great work!

Source Files

• cert_templates
  • cert_def_1_signer.c
  • cert_def_1_signer.h
  • cert_def_2_device.c
  • cert_def_2_device.h
  • cert_def_3_device_csr.c
  • cert_def_3_device_csr.h
• resources
  • credentials
    • root-ca.crt
  • generation_scripts
    • cert2certdef.py
    • create_device_cert.py
    • create_root_ca.py
    • create_server_cert.py
    • create_signer_cert.py
    • generate_certificates.py
    • import_gos_sdk_utils.py
    • provision_device.py
    • secure_element_common.py
    • secure_element_device.py
    • setup_demo.py
    • init .py
  • manifest.cfg
  • openssl_server.bat
  • openssl_server.sh
• commands.c
• common.h
• main.c
• README.md
• secure_element.mk
• se_utils.c