-
Notifications
You must be signed in to change notification settings - Fork 27
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Simplify. - Update links. - Remove DCO link
- Loading branch information
1 parent
9f7b206
commit 3800540
Showing
1 changed file
with
68 additions
and
68 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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.* | ||
| 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 | ||
|
|
||
| ## Getting started | ||
| The official website is [tillitis.se](https://tillitis.se). | ||
| See [LICENSES](./LICENSES/README.md) for more information about | ||
| the projects' licenses. | ||
|
|
||
| The Tkey can be purchased at | ||
| [shop.tillitis.se](https://shop.tillitis.se). | ||
| ## Repositories | ||
|
|
||
| TKey software developer documentation is available in the [TKey | ||
| Developer Handbook](https://dev.tillitis.se). | ||
| 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. | ||
|
|
||
| ## 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 | ||
| 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 firmware are kept in: | ||
| The TP1 (TKey programmer 1) PCB design files and the firmware sources | ||
| are kept in: | ||
|
|
||
| https://github.com/tillitis/tp1 | ||
|
|
||
| ## Other noteworthy links | ||
| 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. | ||
|
|
||
| * [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. | ||
| ## Measured boot | ||
|
|
||
| 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 key behind guaranteeing security even as a general computer is the | ||
| unconditional measured boot. This means that we have a small, | ||
| unchangable, 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. | ||
|
|
||
| ## About this repository | ||
| We call this identity the Compund Device Identity (CDI). The CDI is a | ||
| cryptograpic mix of: | ||
|
|
||
| This repository contains the FPGA design, firmware/bootloader, and the | ||
| USB controller firmware. | ||
| 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*. | ||
|
|
||
| The PCB design files, device and client applications are kept in other | ||
| repositories. See: | ||
| CDI is computed using the BLAKE2s hash function: | ||
|
|
||
| https://github.com/tillitis | ||
| CDI = BLAKE2s(UDS, BLAKE2s(application loaded in RAM), USS) | ||
|
|
||
| ## Licensing | ||
| 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. | ||
|
|
||
| See [LICENSES](./LICENSES/README.md) for more information about | ||
| the projects' licenses. | ||
| - 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. | ||
|
|
||
| All contributors must adhere to the [Developer Certificate of Origin](dco.md). | ||
| 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/). |