From 429ac6877e554d2551ce323f1b0bd378180198b7 Mon Sep 17 00:00:00 2001 From: Daniel Lublin Date: Tue, 4 Oct 2022 11:07:44 +0200 Subject: [PATCH] Note about the importance of releases; clarify some docs --- README.md | 22 ++++++++++----- doc/system_description/software.md | 28 +++++++++++--------- doc/system_description/system_description.md | 8 +++--- 3 files changed, 36 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index c6344c6..547e541 100644 --- a/README.md +++ b/README.md @@ -12,17 +12,17 @@ What makes the Tillitis Key 1 security token unique is that it doesn’t verify applications, it measures them (hashes a digest over the binary), before running them on its open hardware security processor. -Each security token contains a Unique Device Secret (UDS), -which together with an application measurement, and an optional +Each security token contains a Unique Device Secret (UDS), which +together with an application measurement, and an optional user-provided seed, is used to derive key material unique to each application. This allows users to build and load their own apps, while ensuring that each app loaded will have its own cryptographic identity. The design is similar to TCG DICE. The Tillitis Key 1 -platform allows for applications up to 64 KB. - -The first implementation is the Tillitis Key 1: -![The Tillitis Key 1 PCB](doc/images/mta1-usb-v1.jpg) +platform has 128 KB of RAM. The current firmware design allows for +applications up to 64 KB with a 64 KB stack. +![Tillitis Key 1 PCB, first implementation](doc/images/mta1-usb-v1.jpg) +*Tillitis Key 1 PCB, first implementation* ## Documentation @@ -35,6 +35,16 @@ The first implementation is the Tillitis Key 1: * [Quickstart](doc/quickstart.md) to program the Tillitis Key 1 * [Release Notes](doc/release_notes.md) +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. + +Applications and host programs that communicate with the apps are kept +in this repository: https://github.com/tillitis/tillitis-key1-apps + ## About this repository This repository contains hardware, software and utilities written as diff --git a/doc/system_description/software.md b/doc/system_description/software.md index bfcd21c..2604003 100644 --- a/doc/system_description/software.md +++ b/doc/system_description/software.md @@ -18,13 +18,16 @@ firmware and the loaded app. All types are little-endian. ## Constraints -The application FPGA is a Lattice UP5K, with the following +The application FPGA is a Lattice ICE40 UP5K, with the following specifications: - * 32KB x 4 SPRAM => 128KB for Application - * 4Kb x 30 EBR => 120Kb, PicoRV32 uses ~4 EBR internally => 13KB for - Firmware. We should probably aim for less; 8KB should be the - target. + * 30 EBR[^1] x 4 Kbit => 120 Kbit. PicoRV32 uses ~4 EBRs internally + => 13 KB for Firmware. We should probably aim for less; 8 KB + should be the target. + * 4 SPRAM x 32 KB => 128 KB RAM for application/software + +[^1]: Embedded Block RAM residing in the FPGA, can configured as RAM + or ROM. ## Introduction @@ -41,8 +44,9 @@ which is outlined below. E.g. UDS isn't readable, and the `APP_{ADDR, SIZE}` are not writable for the application. The software on the Tillitis Key communicates to the host via the -`{RX,TX}_FIFO` registers, using the framing protocol described in -[Framing Protocol](../framing_protocol/framing_protocol.md). +`UART_{RX,TX}_{STATUS,DATA}` registers, using the framing protocol +described in [Framing +Protocol](../framing_protocol/framing_protocol.md). The firmware defines a protocol (command/response interface) on top of the framing layer, which is used to bootstrap the application onto the @@ -57,8 +61,8 @@ between the host and the device. ## Firmware -The device has 128 kB RAM. The current firmware loads the app at the -upper 64 kB. The lower 64 kB is currently set up as stack for the app. +The device has 128 KB RAM. The current firmware loads the app at the +upper 64 KB. The lower 64 KB is currently set up as stack for the app. The firmware is part of FPGA bitstream (ROM), and is loaded at `0x0000_0000`. @@ -70,7 +74,7 @@ The PicoRV32 starts executing at `0x0000_0000`. Our firmware starts at `0x4000_0000` and upwards. A stack is also initialized, starting at 0x4000_fff0 and downwards. When the initialization is finished, the firmware waits for incoming commands from the host, by busy-polling -the `RX_FIFO_{AVAILABLE,DATA}`registers. When a complete command is +the `UART_RX_{STATUS,DATA}` registers. When a complete command is read, the firmware executes the command. ### Loading an application @@ -296,7 +300,7 @@ Examples: | `UDS_NAME0` | r | invisible | | | | ID of core | | `UDS_NAME1` | r | invisible | | | | ID of core | | `UDS_VERSION` | r | invisible | | | | Version of core | -| `UDS_START` | r[^1]| invisible | 4B | u8[32] | | First word of Unique Device Secret key. | +| `UDS_START` | r[^2]| invisible | 4B | u8[32] | | First word of Unique Device Secret key. | | `UDS_LAST` | | invisible | | | | The last word of the UDS | | `UART_NAME0` | r | r | | | | ID of core | | `UART_NAME1` | r | r | | | | ID of core | @@ -327,4 +331,4 @@ Examples: | `CDI_START` | r/w | r | 32B | u8[32] | | Compound Device Identifier (CDI). UDS+measurement... | | `CDI_LAST` | | r | | | | Last word of CDI | -[^1]: The UDS can only be read *once* per power-cycle. +[^2]: The UDS can only be read *once* per power-cycle. diff --git a/doc/system_description/system_description.md b/doc/system_description/system_description.md index ae8f03e..b07e4bb 100644 --- a/doc/system_description/system_description.md +++ b/doc/system_description/system_description.md @@ -149,13 +149,13 @@ The Application FPGA hardware should provide the following: 2. Communication - Rx-FIFO with status (data_available) - - 8 bit data in RX_FIFO_DATA address - - Byte received status bit in RX_FIFO_AVAILABLE address + - 8 bit data in UART_RX_DATA address + - Byte received status bit in UART_RX_STATUS address - Readable by FW and application - Tx-FIFO with capacity (fifo_ready) - - 8 bit data in TX_FIFO_DATA address - - Ready to store byte status bit in TX_FIFO_READY address + - 8 bit data in UART_RX_DATA address + - Ready to store byte status bit in UART_TX_STATUS address - Status readable by FW and application - Data writable by FW and application