Revise top-level README

- Simplify.
- Update links.
- Remove DCO link
This commit is contained in:
Michael Cardell Widerkrantz 2024-10-17 16:27:02 +02:00 committed by Daniel Jobson
parent 86aedcce69
commit ebd6b17966
No known key found for this signature in database
GPG Key ID: 3707A9DBF4BB8F1A

176
README.md
View File

@ -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/).