Git-Mirrors/tillitis-key
1
0
Fork 0
mirror of https://github.com/tillitis/tillitis-key1.git synced 2024-10-01 01:45:38 -04:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'main' of github.com:tillitis/tillitis-key1

Browse Source
This commit is contained in:
Joachim Strömbergson 2022-10-06 13:25:35 +02:00
commit f80aaa4e8a
3 changed files with 36 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
README.md
View File

@ -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 verify applications, it measures them (hashes a digest over the
binary), before running them on its open hardware security processor. binary), before running them on its open hardware security processor.
Each security token contains a Unique Device Secret (UDS), Each security token contains a Unique Device Secret (UDS), which
which together with an application measurement, and an optional together with an application measurement, and an optional
user-provided seed, is used to derive key material unique to each user-provided seed, is used to derive key material unique to each
application. This allows users to build and load their own apps, while application. This allows users to build and load their own apps, while
ensuring that each app loaded will have its own cryptographic ensuring that each app loaded will have its own cryptographic
identity. The design is similar to TCG DICE. The Tillitis Key 1 identity. The design is similar to TCG DICE. The Tillitis Key 1
platform allows for applications up to 64 KB. platform has 128 KB of RAM. The current firmware design allows for
applications up to 64 KB with a 64 KB stack.
The first implementation is the Tillitis Key 1:
![The Tillitis Key 1 PCB](doc/images/mta1-usb-v1.jpg)
![Tillitis Key 1 PCB, first implementation](doc/images/mta1-usb-v1.jpg)
*Tillitis Key 1 PCB, first implementation*
## Documentation ## Documentation
@ -35,6 +35,16 @@ The first implementation is the Tillitis Key 1:
* [Quickstart](doc/quickstart.md) to program the Tillitis Key 1 * [Quickstart](doc/quickstart.md) to program the Tillitis Key 1
* [Release Notes](doc/release_notes.md) * [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 ## About this repository
This repository contains hardware, software and utilities written as This repository contains hardware, software and utilities written as

28
doc/system_description/software.md
View File

@ -18,13 +18,16 @@ firmware and the loaded app. All types are little-endian.
## Constraints ## Constraints
The application FPGA is a Lattice UP5K, with the following The application FPGA is a Lattice ICE40 UP5K, with the following
specifications: specifications:
* 32KB x 4 SPRAM => 128KB for Application * 30 EBR[^1] x 4 Kbit => 120 Kbit. PicoRV32 uses ~4 EBRs internally
* 4Kb x 30 EBR => 120Kb, PicoRV32 uses ~4 EBR internally => 13KB for => 13 KB for Firmware. We should probably aim for less; 8 KB
Firmware. We should probably aim for less; 8KB should be the should be the target.
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 ## 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. SIZE}` are not writable for the application.
The software on the Tillitis Key communicates to the host via the The software on the Tillitis Key communicates to the host via the
`{RX,TX}_FIFO` registers, using the framing protocol described in `UART_{RX,TX}_{STATUS,DATA}` registers, using the framing protocol
[Framing Protocol](../framing_protocol/framing_protocol.md). described in [Framing
Protocol](../framing_protocol/framing_protocol.md).
The firmware defines a protocol (command/response interface) on top of The firmware defines a protocol (command/response interface) on top of
the framing layer, which is used to bootstrap the application onto the the framing layer, which is used to bootstrap the application onto the
@ -57,8 +61,8 @@ between the host and the device.
## Firmware ## Firmware
The device has 128 kB RAM. The current firmware loads the app at the 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. 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 The firmware is part of FPGA bitstream (ROM), and is loaded at
`0x0000_0000`. `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_0000` and upwards. A stack is also initialized, starting at
0x4000_fff0 and downwards. When the initialization is finished, the 0x4000_fff0 and downwards. When the initialization is finished, the
firmware waits for incoming commands from the host, by busy-polling 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. read, the firmware executes the command.
### Loading an application ### Loading an application
@ -296,7 +300,7 @@ Examples:
| `UDS_NAME0` | r | invisible | | | | ID of core | | `UDS_NAME0` | r | invisible | | | | ID of core |
| `UDS_NAME1` | r | invisible | | | | ID of core | | `UDS_NAME1` | r | invisible | | | | ID of core |
| `UDS_VERSION` | r | invisible | | | | Version 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 | | `UDS_LAST` | | invisible | | | | The last word of the UDS |
| `UART_NAME0` | r | r | | | | ID of core | | `UART_NAME0` | r | r | | | | ID of core |
| `UART_NAME1` | 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_START` | r/w | r | 32B | u8[32] | | Compound Device Identifier (CDI). UDS+measurement... |
| `CDI_LAST` | | r | | | | Last word of CDI | | `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.

8
doc/system_description/system_description.md
View File

@ -149,13 +149,13 @@ The Application FPGA hardware should provide the following:
2. Communication 2. Communication
- Rx-FIFO with status (data_available) - Rx-FIFO with status (data_available)
- 8 bit data in RX_FIFO_DATA address - 8 bit data in UART_RX_DATA address
- Byte received status bit in RX_FIFO_AVAILABLE address - Byte received status bit in UART_RX_STATUS address
- Readable by FW and application - Readable by FW and application
- Tx-FIFO with capacity (fifo_ready) - Tx-FIFO with capacity (fifo_ready)
- 8 bit data in TX_FIFO_DATA address - 8 bit data in UART_RX_DATA address
- Ready to store byte status bit in TX_FIFO_READY address - Ready to store byte status bit in UART_TX_STATUS address
- Status readable by FW and application - Status readable by FW and application
- Data writable by FW and application - Data writable by FW and application