Jacob Barthelmeh 9dcc48c8f7 update copyright to 2023 1 rok pred
..
Makefile 1a291870a3 minor fixes 2 rokov pred
README.md c7fc0fac05 revert changes + spelling/comments 2 rokov pred
client-tls13.c 9dcc48c8f7 update copyright to 2023 1 rok pred
include.am 12d3f94c98 update build and update NULL salt usecase 2 rokov pred
main.c 9dcc48c8f7 update copyright to 2023 1 rok pred

README.md

wolfSSL IoT-SAFE Example

Description

This demo example will run an example TLS 1.3 client using wolfSSL, using an IoT-SAFE applet supporting the IoT.05-v1-IoT standard.

Evaluation Platform

  • Any platform with POSIX-compliant OS such as RaspberryPi
  • Any ICC form-factor with IoT-SAFE applet (see below section for the specific IoT-SAFE configuration)
  • Any serial modem for interfacing between the platform and IoT-SAFE

TLS 1.3

The TLS 1.3 configuration used in this example will use:

  • The mutual authentication between client and server is done with ECC certificate.
  • The key exchange performed is done with ECDHE.
  • The application traffic cipher used is any AEAD.

No PSK authentication, early data, session resumption are used in this demo.

IoT-SAFE Configuration

The below preprocessor macros can be found in the client-tls13.c.

The applet that has been tested with this demo has the current configuration:

Key slot Name Description
0x01 PRIVKEY_ID pre-provisioned with the client ECC private key
0x02 CRT_CLIENT_FILE_ID pre-provisioned with the client ECC public key certificate
0x03 CRT_SERVER_FILE_ID pre-provisioned with the server ECC public key certificate
0x04 ECDH_KEYPAIR_ID used to generate the ECDH key pair that will be used during the TLS session
0x05 PEER_PUBKEY_ID used to store the ECDH public key received from the peer during the TLS session

The following file is used to read the client's certificate and will be used to authenticate the client:

File Slot Name Description
0x02 CRT_CLIENT_FILE_ID pre-provisioned with the client ECC public key certificate

The following file is used to read the server's certificate and will be used to authenticate the server by trusting the server certificate (trust here means no CA chain verification is performed, only comparing the server certificate sent from the server with the one stored in the IoT-SAFE):

File Slot Name Description
0x03 CRT_SERVER_FILE_ID pre-provisioned with the server ECC public key certificate

How the applet configuration (such as putting the client key pair with the corresponding client certificate and the server certificate the client can trust) is performed during its initial and on-field lifetime depends on the infrastructure and is out-of-scope of this demo.

IoT-SAFE Interface

The below code explanations can be found in the client-tls13.c.

In this demo, the client is the IoT-SAFE capable endpoint.

First, it creates a wolfSSL context ctx with TLS 1.3.

wolfSSL_CTX_new(wolfTLSv1_3_client_method());

In order to activate IoT-SAFE support in this context, the following function is called:

wolfSSL_CTX_iotsafe_enable(ctx);

Extracting the client and server certificate can be done by the following functions:

wolfIoTSafe_GetCert(
                    CRT_CLIENT_FILE_ID,
                    cert_buffer,
                    sizeof(cert_buffer));
wolfIoTSafe_GetCert(
                    CRT_SERVER_FILE_ID,
                    cert_buffer,
                    sizeof(cert_buffer));

in which the extracted certificate inside the cer_buffer can be later loaded to the ctx.

Additionally, after the TLS session ssl creation, shown below:

ssl = wolfSSL_new(ctx);

the client associates the pre-provisioned keys and the available slots in the IoT-SAFE applet to the current session:

wolfSSL_iotsafe_on(ssl, PRIVKEY_ID, ECDH_KEYPAIR_ID, PEER_PUBKEY_ID, PEER_CERT_ID);

Compiling

First, user needs to build wolfSSL with the following options:

./configure CFLAGS="-DWOLFSSL_TRUST_PEER_CERT" --enable-tls13 --enable-pkcallbacks --enable-debug --enable-iotsafe --enable-hkdf

Additionally, user can pass CFLAGS="-DDEBUG_WOLFSSL -DWOLFSSL_DEBUG_TLS -DDEBUG_IOTSAFE" if more debugging information is to be used. This can clutter the demo stdout more than --enable-debug does, but this is very useful to see the overall TLS 1.3 handshaking process with IoT-SAFE.

Hence, the full wolfSSL build for the demo is:

./configure CFLAGS="-DWOLFSSL_TRUST_PEER_CERT -DDEBUG_WOLFSSL -DWOLFSSL_DEBUG_TLS -DDEBUG_IOTSAFE" --enable-tls13 --enable-pkcallbacks --enable-debug --enable-iotsafe

-DWOLFSSL_TRUST_PEER_CERT is needed for wolfSSL_CTX_trust_peer_buffer in IDE/iotsafe-raspberrypi/client-tls13.c

Running

After building wolfSSL, from this directory, run make and a help usage will be shown.

Run below to build a minimal demo:

make all

Run below to enable printing UART IO:

make all ENABLE_DEBUG_UART_IO_EXTRA=on|off

Run the built ./main.bin to print the help usage.

An example to run the demo connecting to a server:

./main.bin -ip <ipaddress> -h <full-hostname> -p <port> -t 25 -d /dev/ttyUSB0|/dev/tty/ACM0