mirror of
https://github.com/tillitis/tillitis-key1.git
synced 2024-10-01 05:45:38 +00:00
8dca845bc1
The links to firmware.md disappeared earlier so this change incorporates some of the the text there in under the Firmware heading in software.md. Also changes the names of the commands in the state machine to the same names as in the rest of software.md. Mention the Zmmul extension and what it means and possible workarounds for people developing with clang < version 15.
86 lines
3.5 KiB
Markdown
86 lines
3.5 KiB
Markdown
# Tillitis Key
|
|
|
|
## Introduction
|
|
|
|
Tillitis Key (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.
|
|
|
|
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/).
|
|
|
|
Each TKey device contains a Unique Device Secret (UDS), which
|
|
together with the application measurement, and an optional
|
|
user-provided seed, 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-provided seed 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.
|
|
|
|
The TKey platform is based around a 32-bit RISC-V processor and has
|
|
128 KB of RAM. The current firmware is designed to load an app that is
|
|
up to 100 KB in size, and gives it a stack of 28 KB. A smaller app may
|
|
move itself in memory to get larger continuous memory.
|
|
|
|
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.
|
|
|
|
![Tillitis Key 1 PCB, first implementation](doc/images/mta1-usb-v1.jpg)
|
|
*The TK1 PCB, the first implementation of the TKey.*
|
|
|
|
|
|
## Documentation
|
|
|
|
### Getting started
|
|
|
|
* [Quickstart](doc/quickstart.md) to program the TKey
|
|
* [Toolchain setup](doc/toolchain_setup.md)
|
|
* [Release Notes](doc/release_notes.md)
|
|
|
|
Applications and host programs that communicate with the apps are kept
|
|
in this repository: https://github.com/tillitis/tillitis-key1-apps
|
|
|
|
### In-depth technical information
|
|
|
|
* [System Description](doc/system_description/system_description.md)
|
|
* [Threat Model](doc/threat_model/threat_model.md)
|
|
* [Framing Protocol](doc/framing_protocol/framing_protocol.md)
|
|
* [Boards](doc/system_description/boards.md)
|
|
* [Boards](doc/system_description/boards.md)
|
|
* [FPGA](doc/system_description/fpga.md)
|
|
* [Software](doc/system_description/software.md)
|
|
* [QEMU](https://github.com/tillitis/qemu/tree/tk1) (branch `tk1` in
|
|
separate repository)
|
|
|
|
Note that development is ongoing. For example, changes might be made
|
|
to the measuring and derivation of key material, causing the
|
|
public/private keys of a signer app to change. To avoid unexpected
|
|
changes, 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 hardware, software and utilities written as
|
|
part of the TKey. It is structured as monolithic repository, or
|
|
"monorepo", where all components live in one repository.
|
|
|
|
## 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).
|