LionKey: An open-source FIDO2 USB Security Key

A working FIDO2/WebAuthn USB hardware external authenticator (also called “security key”) 🔑 implemented on STM32H533.

In terms of WebAuthn, LionKey is a roaming authenticator with cross-platform attachment using CTAP 2.1 over USB 2.0 (CTAPHID) as the communication protocol, supporting user verification using PIN (CTAP2 ClientPIN), and capable of storing passkeys (client-side discoverable credentials).

Key features:

• Fully compliant implementation of CTAP 2.1.
  • Implements all mandatory features.
  • Written in C.
  • No dynamic memory allocations.
  • Designed for use in resource-constrained environments.
  • MCU independent, easily portable, can be used as a library (see the core dir).
  • Just a single external dependency (TinyCBOR).
• Running on the NUCLEO-H533RE board with the STM32H533RET6 MCU.
• Uses STM32CubeH5.
• Hardware-accelerated cryptography on STM32H533 (using the RNG, PKA, AES, SHA peripherals).

Warning

🚧 This is still a work in progress. The security key is already usable. More detailed documentation will be added soon. The main missing feature is state persistence to the flash memory on STM32H533 (currently all state is reset when power is lost).

Content

• Development
  • Requirements
  • Cloning the Project
  • Build from the Command Line
  • Using IDE
  • SVD file for the MCU
• STM32CubeH5

Development

Requirements

• CMake (tested with version 3.30.5)

  • Note: CLion has a bundled CMake so there is no need to install it.

• Arm GNU Toolchain (tested with Version 14.2.Rel1)

  • Download AArch32 bare-metal target (arm-none-eabi) from the Arm website here.
  • On macOS, brew install --cask gcc-arm-embedded can be used.

• OpenOCD or any other tool for programming and debugging Arm Cortex-M microcontrollers, such as pyOCD or ST-LINK_gdbserver (a part of STM32CubeIDE).

Caution

STM32H5 does not work with the original OpenOCD. Currently, it only works with the STMicroelectronics' fork STMicroelectronics/OpenOCD, which has to be built from source, see 👉 this guide for the instructions.

Cloning the Project

The project uses Git submodules to manage some of the external dependencies (see .gitmodules).

There are two options how to get the contents of the submodules:

When cloning the project, you can use:

git clone --recurse-submodules https://github.com/pokusew/lionkey.git

If you already cloned the project and forgot --recurse-submodules, you can use:

git submodule update --init --recursive

Build from the Command Line

It is possible to build, flash and start the whole project from the command line.

Building is done via cmake since this project is a standard CMake project (see CMakeLists.txt). We also included a CMakePresets.json to simplify passing common options.

Here is an example how to build the executable for the NUCLEO-H533RE board with the STM32H533RET6 MCU.

# configure step (only has to be done once)
cmake --preset stm32h533-debug
# build step
cmake --build --preset stm32h533-debug

Flashing can be done for example using openocd like this (run from the project root):

openocd -s /usr/local/share/openocd/scripts -f targets/stm32h533/st_nucleo_h5.cfg -c 'tcl_port disabled' -c 'gdb_port disabled' -c 'program "build/stm32h533-debug/targets/stm32h533/lionkey_stm32h533.elf"' -c reset -c shutdown

Using IDE

Use JetBrains CLion (free for non-commercial use) for development. The project is already imported and fully configured, use File > Open... to just open it.

If you have all the tools installed, you should be able to open, build and run the project from CLion.

You can read more in this CLion's Embedded development with STM32CubeMX projects guide.

Note that CLion bundles CMake (and other tools). Those can be used outside CLion from terminal as well. On a x64 macOS system, the CLion's cmake binary is located at /Applications/CLion.app/Contents/bin/cmake/mac/x64/bin/cmake. If you add the /Applications/CLion.app/Contents/bin/cmake/mac/x64/bin/ dir to your PATH, then you can run CLion's CMake just by typing cmake in your terminal.

SVD file for the MCU

CLion and other IDEs support SVD files for describing the layout of registers for debugging.

See the README in the tools/svd dir which lists the available SVD files you can use.

STM32CubeH5

We use the STM32CubeH5 package (CMSIS, HAL, LL) via the STM32CubeMX generator.

The STM32CubeH5 includes the CMSIS modules (for the Arm Cortex-M33 core and for the STM32H5 MCUs), and the HAL (hardware abstraction layer) and LL (low-level) drivers for the STM32H5 MCUs.

Relevant resources:

• see STM32CubeH5 GitHub repo
• see product page with docs on st.com
• see UM3132 Description of STM32H5 HAL and low-layer drivers