mirror of
https://github.com/tillitis/tillitis-key1.git
synced 2024-12-24 15:09:27 -05:00
Revise top-level README
- Simplify. - Update links. - Remove DCO link
This commit is contained in:
Michael Cardell Widerkrantz
Daniel Jobson
parent
86aedcce69
commit
ebd6b17966
176
README.md
176
README.md
@ -1,106 +1,106 @@
|
||||
|
||||
[](https://github.com/tillitis/tillitis-key1/actions/workflows/ci.yaml)
|
||||
|
||||
# Tillitis TKey
|
||||
|
||||
 *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/
|
||||
|
||||
 *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/).
|
||||
|
||||
Loading…
Reference in New Issue
Block a user