Skip to content

Cloning and building

Fobnail project consists of 3 main repositories with code:

There is also Fobnail SDK that simplifies building of firmware by using Docker container, but only one script from this repository is actually needed.

Following steps were successfully performed on Ubuntu 22.04.1 LTS.

Fobnail Token firmware

Start by installing prerequisites:

sudo apt -y install git

Log out of the desktop session then log in again - this is required after making the change to user groups. You may confirm it by running groups.

Clone the repository along with its submodules:

git clone https://github.com/fobnail/fobnail --recurse-submodules

Build process for Token firmware is by far the most complicated one. For that reason use of Fobnail SDK is strongly suggested. Follow these instructions to install it.

With the SDK installed, one can prepare for the build process itself. Firmware can be build for a physical Fobnail Token or simulated on PC, with different preparatory steps required.

If TPM simulator is to be used, steps from this document must be done before Token firmware is compiled. Instructions from the linked document result in creation of root CA certificate for EK chain, that certificate must be supplied as an input to Token build command. Physical TPMs require certificate provided by TPM vendor instead, those are included in fobnail repository.

Environment variables common for both targets

Fobnail Token firmware is configured with environment variables passed to build.sh.

Note that due to the way Docker mounts directories all files and directories pointed to by following variables must be located somewhere in fobnail directory.

  • FOBNAIL_PO_ROOT - required option, must point to valid PEM or DER file with Platform Owner's root certificate. See this document for description of PO certificate chain and instructions for building such. For Fobnail Token firmware it is enough to create only root CA certificate. The rest of chain will be required for provisioning.

  • FOBNAIL_EK_ROOT_DIR - points to directory with TPM root certificates. Fobnail repository includes such directory which normally should be used as FOBNAIL_EK_ROOT_DIR, but you may change it if certificates supplied in repository became outdated. Either this or FOBNAIL_EXTRA_EK_ROOT (or both) must be specified.

  • FOBNAIL_EXTRA_EK_ROOT - points to one specific TPM certificate. Useful when testing with TPM emulator, or to limit Fobnail usage to one specific TPM vendor. Either this or FOBNAIL_EK_ROOT_DIR (or both) must be specified.

Building and running firmware

For hardware setup instructions see Flashing preparation.

Building and flashing is performed by executing (from fobnail directory):

env FOBNAIL_PO_ROOT=root_ca.crt FOBNAIL_EK_ROOT_DIR=tpm_ek_roots \
    ./build.sh -t nrf --run

A console with Fobnail Token output will be displayed. It is not required for normal operation but can be useful for debugging. It can be closed with Ctrl-C at any point. After that, Token can be used without nRF52840-DK - just plug it wherever it's needed.

Make sure you have the network set up properly. See Networking setup for instructions. For firmware to work properly you need the fobnail0 network interface configured.

To build and run firmware execute the following commands (from fobnail directory).

env FOBNAIL_LOG=info FOBNAIL_PO_ROOT=root_ca.crt \
    FOBNAIL_EK_ROOT_DIR=tpm_ek_roots ./build.sh -t pc --run

FOBNAIL_LOG environment variable sets log level. The possible log levels are: error, warning, info, debug, trace. This variable is valid only for PC target.

Another variable used only on PC is FOBNAIL_DEVICE_ID - on hardware we used FICR registers to create a device ID, this gives a way of configuring it for emulation. This variable is optional, without it an ID of 0 is used.

build.sh automatically starts Token emulation. It runs until it's terminated with Ctrl-C.

PC applications

Platform Owner and Attester have similar set of prerequisites, listed below. Depending on use case, they may or may not be run on the same PC, so these steps may have to be repeated on different computers.

sudo apt -y install git make gcc autoconf automake pkg-config libtool libssl-dev

Both applications use libcoap with v3 API which isn't provided by main Linux distributions yet, so it has to be built from sources and installed:

git clone https://github.com/obgm/libcoap.git --recurse-submodules
cd libcoap
git checkout release-4.3.0
./autogen.sh && \
./configure --exec-prefix=/usr --disable-tests --disable-documentation \
    --disable-manpages --enable-dtls --with-tinydtls --enable-fast-install && \
make && sudo make install

Platform Owner

With prerequisites installed, building Platform Owner application is simple - just clone and build:

git clone https://github.com/fobnail/fobnail-platform-owner --recurse-submodules
cd fobnail-platform-owner
make

Produced binary is located in bin/fobnail-platform-owner, from where it can be moved to PATH or just started from there.

Attester

Attester requires additional packages to talk with TPM and download TPM's certificate chain from Internet:

sudo apt -y install libtss2-dev libcurl4-openssl-dev

After that, building is simple:

git clone https://github.com/fobnail/fobnail-attester --recurse-submodules
cd fobnail-attester
make

Two executables are produced in bin folder: fobnail-attester and fobnail-attester-with-provisioning. First one can be moved to PATH for easier use. The latter is expected to be run only once per Token, by an administrator in a controlled environment, and not for daily use, so it can be not installed to avoid confusion.

Summary and next steps

Congratulations, you have built all of the components of Fobnail! From here you should proceed to Token provisioning guide.