From ebd6b17966dbd7e466f8cdd4a22df5db20efd8b9 Mon Sep 17 00:00:00 2001 From: Michael Cardell Widerkrantz Date: Thu, 17 Oct 2024 16:27:02 +0200 Subject: [PATCH] Revise top-level README - Simplify. - Update links. - Remove DCO link --- README.md | 176 +++++++++++++++++++++++++++--------------------------- 1 file changed, 88 insertions(+), 88 deletions(-) diff --git a/README.md b/README.md index 6ce2509..ce77ef3 100644 --- a/README.md +++ b/README.md @@ -1,106 +1,106 @@ - [![ci](https://github.com/tillitis/tillitis-key1/actions/workflows/ci.yaml/badge.svg?branch=main&event=push)](https://github.com/tillitis/tillitis-key1/actions/workflows/ci.yaml) # Tillitis TKey +![TK1 PCB](doc/images/tkey-open-lid.png) *The TK1 PCB, also known as +TKey.* + ## Introduction -The Tillitis TKey is a new kind of USB security token. What makes the -TKey unique is that it allows a user to load and run applications on -the device, while still providing security. This allow for open-ended, -flexible usage. Given the right application, the TKey can support use -cases such as SSH login, Ed25519 signing, Root of Trust, FIDO2, TOTP, -Passkey, and more. +The Tillitis TKey is an open source, open hardware FPGA-based USB +security token using +[DICE-like](https://trustedcomputinggroup.org/work-groups/dice-architectures/) +unconditional measured boot that can run generic applications while +still guaranteeing the security of its cryptographic assets. -During the load operation, the device measures the application -(calculates a cryptographic hash digest over it) before running -it on the open hardware security processor. This measurement -is similar to [TCG DICE](https://trustedcomputinggroup.org/work-groups/dice-architectures/). +[TKey Threat Model](doc/threat_model/threat_model.md). -Each TKey device contains a Unique Device Secret (UDS), which -together with the application measurement, and an optional -User-Supplied Secret (USS), is used to derive key material unique to each -application. This guarantees that if the integrity of the application -loaded onto the device has been tampered with, the correct keys -needed for an authentication will not be generated. +With the right application, the TKey can be used for: -Key derivation with a User-Supplied Secret allows users to build and -load their own apps, while ensuring that each app loaded will have -its own cryptographic identity, and can also be used for authentication -towards different services. +- authentication, +- cryptographic signing, +- encryption, +- root of trust, +- and more: it's a general computer! -The TKey platform is based around a 32-bit RISC-V processor and has -128 KB of RAM. Firmware can load and start an app that is as large as -RAM. +If you want to know more about Tillitis and the TKey, visit: -All of the TKey software, firmware, FPGA Verilog source code, schematics -and PCB design files are open source. Like all trustworthy security software -and hardware should be. This in itself makes it different, as other -security tokens utilize at least some closed source hardware for its -security-critical operations. +- Main web: https://tillitis.se/ +- Shop: https://shop.tillitis.se/ +- Developer Handbook: https://dev.tillitis.se/ +- Officially supported apps: https://tillitis.se/download/ +- Other known apps: https://dev.tillitis.se/projects/ -![Tillitis Key 1 PCB](doc/images/tkey-open-lid.png) *The TK1 PCB, also -known as TKey.* - - -## Getting started -The official website is [tillitis.se](https://tillitis.se). - -The Tkey can be purchased at -[shop.tillitis.se](https://shop.tillitis.se). - -TKey software developer documentation is available in the [TKey -Developer Handbook](https://dev.tillitis.se). - -Specific documentation regarding implementation is kept close to the -code/design in README files, typically in the same directory. - -## Tkey Device Apps -Officially supported apps can be found at -[tillitis.se](https://tillitis.se/download/) - -The source and other projects from us can be found here at our -[GitHub](https://github.com/tillitis). - -Other known (but not all) projects can be found at -[dev.tillitis.se](https://dev.tillitis.se/projects/). - -## PCB and programmer - -The TKey PCB [KiCad](https://www.kicad.org/) design files are kept in -a separate repository: - -https://github.com/tillitis/tk1-pcba - -The TP1 (TKey programmer 1) PCB design files and firmware are kept in: - -https://github.com/tillitis/tp1 - -## Other noteworthy links - -* [Threat Model](doc/threat_model/threat_model.md) -* [Release Notes](doc/release_notes.md) -* [Quickstart for the DevKit](doc/quickstart.md). Initial programming -if you have the "old" DevKit. - -Note that development is ongoing. To avoid unexpected changes of -derived key material, please use a tagged release. Read the [Release -Notes](doc/release_notes.md) to keep up to date with changes and new -releases. - -## About this repository - -This repository contains the FPGA design, firmware/bootloader, and the -USB controller firmware. - -The PCB design files, device and client applications are kept in other -repositories. See: - -https://github.com/tillitis +All of the TKey software, firmware, FPGA Verilog code, schematics and +PCB design files are open source, just like all trustworthy security +software and hardware should be. ## Licensing See [LICENSES](./LICENSES/README.md) for more information about the projects' licenses. -All contributors must adhere to the [Developer Certificate of Origin](dco.md). +## Repositories + +This repository contains the FPGA design, the source of the +firmware/bootloader, and the source of the USB controller firmware. + +Specific documentation regarding implementation is kept close to the +code/design in README files, typically in the same directory. + +Note that development is ongoing. To avoid unexpected changes of +derived key material, please use a tagged release. Read the [Release +Notes](doc/release_notes.md) to keep up to date with changes and new +releases. + +The TKey PCB [KiCad](https://www.kicad.org/) design files are kept in +a separate repository: + +https://github.com/tillitis/tk1-pcba + +The TP1 (TKey programmer 1) PCB design files and the firmware sources +are kept in: + +https://github.com/tillitis/tp1 + +Note that the TP1 is only used for provisioning the FPGA bitstream +into flash or the FPGA configuration memory. It's not necessary if you +just want to develop apps for the TKey. + +## Measured boot + +The key behind guaranteeing security even as a general computer is the +unconditional measured boot. This means that we have a small, +unchangeable, trusted firmware in ROM that creates a unique identity +before starting the application. This identity is used as a seed for +all later cryptographic keys. + +We call this identity the Compound Device Identity (CDI). The CDI is a +cryptographic mix of: + +1. the Unique Device Secret (UDS), a hardware secret, unique per + device, something the user *has*, +2. the hash digest of the TKey device application that has been + loaded, the *integrity* of the application, and, +3. an optional User Supplied Secret (USS), something the user *knows*. + +CDI is computed using the BLAKE2s hash function: + +CDI = BLAKE2s(UDS, BLAKE2s(application loaded in RAM), USS) + +When firmware is about to start the device application it changes the +TKey to a less permissive hardware mode, application mode. In +application mode the UDS and the User Supplied Secret are no longer +available, but the device application can use the CDI as a seed to +deterministically generate any cryptographic keys it needs. + +- If the wrong application has been loaded, or the original + application has been tampered with, the generated keys will be + different. +- If the USS is not the same, the generated keys will be different. +- If the same USS and device application is used on a different TKey, + the generated keys will be different. + +The TKey unconditional measured boot is inspired by, but not exactly +the same as part of [TCG +DICE](https://trustedcomputinggroup.org/work-groups/dice-architectures/).