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)
|
[](https://github.com/tillitis/tillitis-key1/actions/workflows/ci.yaml)
|
||||||
|
|
||||||
# Tillitis TKey
|
# Tillitis TKey
|
||||||
|
|
||||||
|
 *The TK1 PCB, also known as
|
||||||
|
TKey.*
|
||||||
|
|
||||||
## Introduction
|
## Introduction
|
||||||
|
|
||||||
The Tillitis TKey is a new kind of USB security token. What makes the
|
The Tillitis TKey is an open source, open hardware FPGA-based USB
|
||||||
TKey unique is that it allows a user to load and run applications on
|
security token using
|
||||||
the device, while still providing security. This allow for open-ended,
|
[DICE-like](https://trustedcomputinggroup.org/work-groups/dice-architectures/)
|
||||||
flexible usage. Given the right application, the TKey can support use
|
unconditional measured boot that can run generic applications while
|
||||||
cases such as SSH login, Ed25519 signing, Root of Trust, FIDO2, TOTP,
|
still guaranteeing the security of its cryptographic assets.
|
||||||
Passkey, and more.
|
|
||||||
|
|
||||||
During the load operation, the device measures the application
|
[TKey Threat Model](doc/threat_model/threat_model.md).
|
||||||
(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/).
|
|
||||||
|
|
||||||
Each TKey device contains a Unique Device Secret (UDS), which
|
With the right application, the TKey can be used for:
|
||||||
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.
|
|
||||||
|
|
||||||
Key derivation with a User-Supplied Secret allows users to build and
|
- authentication,
|
||||||
load their own apps, while ensuring that each app loaded will have
|
- cryptographic signing,
|
||||||
its own cryptographic identity, and can also be used for authentication
|
- encryption,
|
||||||
towards different services.
|
- root of trust,
|
||||||
|
- and more: it's a general computer!
|
||||||
|
|
||||||
The TKey platform is based around a 32-bit RISC-V processor and has
|
If you want to know more about Tillitis and the TKey, visit:
|
||||||
128 KB of RAM. Firmware can load and start an app that is as large as
|
|
||||||
RAM.
|
|
||||||
|
|
||||||
All of the TKey software, firmware, FPGA Verilog source code, schematics
|
- Main web: https://tillitis.se/
|
||||||
and PCB design files are open source. Like all trustworthy security software
|
- Shop: https://shop.tillitis.se/
|
||||||
and hardware should be. This in itself makes it different, as other
|
- Developer Handbook: https://dev.tillitis.se/
|
||||||
security tokens utilize at least some closed source hardware for its
|
- Officially supported apps: https://tillitis.se/download/
|
||||||
security-critical operations.
|
- Other known apps: https://dev.tillitis.se/projects/
|
||||||
|
|
||||||
 *The TK1 PCB, also
|
All of the TKey software, firmware, FPGA Verilog code, schematics and
|
||||||
known as TKey.*
|
PCB design files are open source, just like all trustworthy security
|
||||||
|
software and hardware should be.
|
||||||
|
|
||||||
## 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
|
|
||||||
|
|
||||||
## Licensing
|
## Licensing
|
||||||
|
|
||||||
See [LICENSES](./LICENSES/README.md) for more information about
|
See [LICENSES](./LICENSES/README.md) for more information about
|
||||||
the projects' licenses.
|
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