The project is meant to showcase the Hybrid Post-Quantum capabilities of an MQTTs client using TLS 1.3 and the mbedtls library.
For info or comments, contact us at hello@securitypattern.com
The TLS handshake has been agumented with Hybrid PQ capabilities by introducing a new KEM and a new signature mechanism.
These are, respectively X25519-MLKEM768 and Ed25519-MLDSA.
The functions responsible for the KEM can be found in qubip.c:
HybridKeyKEM *hybrid_key_gen();
void hybrid_key_free(HybridKeyKEM *);
The signature and signature verification functions are implemented in the already present mbedtls file pk_wrap.c that get called several times during the TLS handshake.
static int ed25519_mlds44_sign_wrap(mbedtls_pk_context *pk,
mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hash_len,
unsigned char *sig, size_t sig_size, size_t *sig_len,
int (*f_rng)(void*, unsigned char*, size_t), void *p_rng);
static int ed25519_mlds44_verify_wrap(mbedtls_pk_context *pk,
mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hash_len,
const unsigned char *sig, size_t sig_len);
Furthermore, the certificate parsing functionalities have been expanded to include support for Hybrid PQ certificates in file pk_parse.c
A few examples of Hybrid PQ certificates have been hardcoded in file MQTTInterface.c
The ID definitions for the Hybrid mechanism are as follows:
#define MBEDTLS_SSL_IANA_TLS_GROUP_MLKEM768 0x11ec
#define MBEDTLS_TLS1_3_SIG_ED25519_MLDSA44 0x090a
#define MBEDTLS_TLS1_3_SIG_ED25519_MLDSA65 0x090b
as shown in file ssl.h
A PQ openssl server can be setup to test the TLS handshake between the board and the server by compiling a version of openssl with the support for PQ cryptography.
The server can only be used to test the handshake as it is not a MQTTs server.
To do so, the following components need to be compiled:
mkdir -p installs/{openssl,liboqs}
sudo apt install build-essential linux-headers-$(uname -r) \
libtool automake autoconf \
make cmake ninja-build \
git wget libssl-dev
export INSTALL_DIR=$(pwd)/installs
cd openssl
LDFLAGS="-Wl,-rpath -Wl,$INSTALL_DIR/openssl/lib64" ./config shared --prefix=$INSTALL_DIR/openssl
make
make install
cd ..
cd liboqs
mkdir build
cd build
cmake -G"Ninja" .. -DOPENSSL_ROOT_DIR=$INSTALL_DIR/openssl -DOQS_DIST_BUILD=ON -DCMAKE_INSTALL_PREFIX=$INSTALL_DIR/liboqs
ninja install
cd ../oqs-provider
liboqs_DIR=$INSTALL_DIR/liboqs cmake -DOPENSSL_ROOT_DIR=$INSTALL_DIR/openssl -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=$INSTALL_DIR/openssl -S . -B _build
cmake --build _build
cp _build/lib/oqsprovider.so $INSTALL_DIR/openssl/lib64/ossl-modules
sed -i "s/default = default_sect/default = default_sect\noqsprovider = oqsprovider_sect/g" $INSTALL_DIR/openssl/ssl/openssl.cnf && \
sed -i "s/\[default_sect\]/\[default_sect\]\nactivate = 1\n\[oqsprovider_sect\]\nactivate = 1\n/g" $INSTALL_DIR/openssl/ssl/openssl.cnf && \
sed -i "s/providers = provider_sect/providers = provider_sect\nssl_conf = ssl_sect\n\n\[ssl_sect\]\nsystem_default = system_default_sect\n\n\[system_default_sect\]\nGroups = \$ENV\:\:DEFAULT_GROUPS\n/g" $INSTALL_DIR/openssl/ssl/openssl.cnf && \
sed -i "s/HOME\t\t\t= ./HOME = .\nDEFAULT_GROUPS = kyber768/g" $INSTALL_DIR/openssl/ssl/openssl.cnf
A series of shell scripts can be used to launch the chosen vesion of the server. The options differ in the certificates used to perform mutual authentication.
- Classic TLS
- MLDSA44
- MLDSA65
- Production-like PKI setup by PoliTO
The certificates are provided in the relative folders under certificates
- The library is provided by CSIC
- A precompiled binary for the STM32F4 is provided in libcryptoapialt-static-arm.a
- This is linked with the binary that will run onto the STM32F4 in the CubeIDE project
- Sources can be found in the corrisponding repository CSIC Crypto-API
The project can be imported into CubeIDE and run onto the STM32F4
A few parameters can be configured in the file qubip.h
To choose whether or not to use the physical SE
#define HW_IMPLEMENTATION 0 //1=ON, 0=OFF
To choose which certificates to use. They need to match the server ones.
// OPTIONS: CERTS_PQ_44, CERTS_PQ_65, CERTS_CLASSIC
#define CERTS_PQ_44
The remote server IP and hostname can be configured as:
//#define BROKER_IP "192.168.1.12"
#define BROKER_IP "broker.dm.qubip.eu"
#define BROKER_HOSTNAME "broker.dm.qubip.eu"
The STM32 prints its output onto its serial port on PIN PD8 which can be found on the back of the board
This document explains how to configure the QUBIP C project for benchmarking and describes the expected output formats.
The project configuration is managed via macros in the qubip.h file. Below are the key settings you can modify:
#define HW_IMPLEMENTATION 1 // 1 = ON (Hardware), 0 = OFF (Software)- 1 (ON): Uses Hardware acceleration for Post-Quantum (PQ) and Classic cryptography.
- 0 (OFF): Uses Software implementation.
Note: Software implementation for PQ is currently available in the
SW_ONLYbranch.
#define SCP03 1 // 1 = ON, 0 = OFFEnables or disables the SCP03 protocol for secure communication with the hardware security module.
You can choose between Classic and Post-Quantum configurations by defining one of the following:
#define CERTS_CLASSIC // Use Classic certificates (Ed25519 / X25519)
//#define CERTS_PQ_44 // Use Post-Quantum certificates (ML-DSA-44 / ML-KEM-768)The MQTT broker details are automatically selected based on the certificate type, but can be overridden:
- Classic: Defaults to
broker.smartfactory.it - PQ: Defaults to
broker.dm.qubip.eu
SWAP_ORDER: Defined to handle specific byte-ordering requirements.FORCE_CRL_CHECK: Set to1to mandate a Certificate Revocation List (CRL) check during the handshake.
When FORCE_CRL_CHECK is enabled, the system is configured to trigger a CRL validation process where the server's certificate is intentionally revoked.
Important Behavior:
- Handshake Failure: Because the certificate is revoked, the TLS handshake will not complete successfully.
- MQTT Limitation: Since the handshake fails, the device cannot establish a secure connection to the MQTT broker. Consequently, benchmark data for CRL validation is not published to the MQTT channel.
- Data Collection: To obtain the CRL validation benchmark, you must monitor the Serial/Terminal output directly.
- Software PQ (Post-Quantum): Does not support CRL validation. The memory footprint required to store all necessary data in flash memory exceeds available capacity.
The benchmark results are delivered through two channels: MQTT and the Terminal.
The MQTT client connects to the configured broker and publishes benchmark data to a dedicated channel:
- Topic:
<DEVICE_NAME>/benchmark(e.g.,sfc10002/benchmark) - Payload: Contains the benchmark metrics collected during the TLS handshake and cryptographic operations.
If the publication fails, the client will close the session and attempt to reconnect.
The benchmark results are also printed to the terminal in the following format:
#############################################
Benchmarks <Classic|Hybrid PQ> <HW|SW>
Connected in <total_handshake_us> us
Server Cert parsing <server_crt_parse_us> us
CRL verified in <crl_verify_us> us
#############################################
- Benchmarks Type: Displays whether the execution used Classic or Hybrid PQ algorithms, and whether it was Hardware (HW) or Software (SW) accelerated.
- Connected in: Total time taken for the TLS handshake in microseconds.
- Server Cert parsing: Time spent parsing the server's certificate.
- CRL verified in: Time spent performing the Certificate Revocation List check.