TFN OS GitHub

How it works

Your boards, your computer if you want one, and this site. Nothing else.

TFN OS has no accounts and no server of ours that talks to your boards. Each file that comes to a board has a signature, and the board checks it. A group of your boards trusts each other with keys that only you keep.

See it as diagrams: the trust map (a public user, a pool with its own apps, a developer).

The three places

Each part of TFN OS lives in one of these places. The lines show what goes between them.

One board, with nothing else

This is the start for each board. You need no computer and no pool.

  1. Install TFN OS from the install page. The board makes its own device key at the first start.
  2. The board gets the free apps from the store of this site. It checks the signature of each app before the install.
  3. New releases come from the update channel of this site, when the board is idle.
  4. Friends near you play with you by radio, with no internet and with no pool.

A board with no pool sends no beacons on your network. Other people on the network do not see it.

Each file has a signature

A board takes a file only when a key that it trusts signed it. The board does the check itself. A web page or a computer cannot tell it to skip the check.

The firmware

Each release image has a signature of the TFN OS release key. The board checks it before it starts the new image, and refuses an image for another board kind.

Each release has a security number. A board does not go back to an older number, so a person cannot put back an old image with a known fault.

A new image must pass its self-test. If it does not, the board goes back to the last good image.

The apps

Each app package has a signature of a store key. The board checks the signature, the board kind, the version of the system calls and the SHA-256 of each file.

The board trusts the key of the TFN OS store. You can add more keys, for example the key of your pool's own store, or your key as a developer.

An app is native code, so install only the apps of a store that you trust.

A finger on the glass

Some steps change who the board trusts: a new key, a JOIN of a pool, the developer mode. These steps need a tap of a real finger on the board.

A tap from the web page or from the network does not count. The USB cable counts, because a person with the cable can write any firmware to the board anyway.

Pools: boards that trust each other

A pool is a group of up to 16 boards, for example the boards of a home. Anyone can make a pool. There is no central list of pools.

What a pool has

The pool key
A random secret of the group. Each packet between the boards of the pool has a tag of this key and a counter. A board drops a packet with a bad tag or an old counter.
The pool list
The members, their roles and the address of the pool manager. The admin key of the pool signs it. A board takes only a newer list with a good signature.
Two admin keys
Key A signs the changes. Key R is for recovery: it stays in an encrypted file, so a lost computer does not lose the pool.
Roles
MEMBER, MANAGER, and CHILD (a CHILD board cannot leave the pool by itself).

How a board joins

  1. On the board: SETUP > POOL > JOIN.
  2. On your computer: poolmgr adopt.
  3. The board and the computer show the same 6 digits.
  4. When the digits are the same, tap ALLOW on the board with your finger.

The 6 digits stop a device between the board and the computer. If they are not the same, tap NO.

When a board leaves

The pool manager sends a new pool key to the other members. The board that left cannot read the pool any more.

Play together, also with no internet

The 2-board games and WALKIE talk board to board by radio (ESP-NOW). They need no router and no internet.

One meeting channel

When both boards open the same game, they meet on one radio channel. A board on a WiFi network stays on the channel of its network, and the other board comes to it.

Two different WiFi networks

If your friend's board is on another WiFi network, the lobby asks "YOUR FRIEND IS ON ANOTHER WIFI?". PLAY BY RADIO leaves the WiFi for the game, and joins it again after the game. Your saved networks do not change.

Inside a pool

The boards of a pool see each other, and each packet has the tag of the pool key. The boards of another pool cannot see them.

The pool manager on your computer

poolmgr is a free program in the TFN OS source. It runs on Windows, macOS, Linux or a Raspberry Pi, with Python 3.9 or later and nothing more to install.

What it does

  • init makes your pool, its keys and the first backup.
  • adopt adds a board with the 6 digits. Each member gets a random web password, and all other members as friends.
  • update sends a new release to your boards, one board at a time. It checks the signature first, and the board checks it again.
  • store keeps a copy of the store on your network, and adds the apps that you sign with your pool's own key.
  • backup and recover keep your pool when a computer is lost.
  • serve runs in the background and keeps the boards up to date.

What it does not do

  • It has no web page and no admin access on the network. A change comes only from a command on your computer.
  • It never adds a board by itself. Each board joins with the 6 digits and a tap on ALLOW.
  • It sends nothing to us. Your keys and your data stay in one folder on your computer.

The full guide is in the source: docs/poolmgr.md.

Where each part lives

PartWhereWho keeps it
The source of TFN OS, the SDK and poolmgrThe public repository, with a licence for each partEveryone can read it
The release images and the store appsThe releases of the repository and this siteSigned with the TFN OS keys; the private keys stay off line
The device key of a boardThe boardOnly that board
The pool key and the pool listThe members of the poolYour boards
The admin keys A and R of a poolYour computer (key R only in an encrypted file)Only you
Your WiFi, your files, your settingsThe boardOnly you. This site never sees them

Install TFN OS See the apps