Git-Mirrors/tillitis-key
1
0
Fork 0
mirror of https://github.com/tillitis/tillitis-key1.git synced 2025-09-26 11:21:02 -04:00
Code Issues Projects Releases Packages Wiki Activity

Rename to TK1

Browse source
This commit is contained in:
Daniel Lublin 2022-10-20 14:50:21 +02:00
parent 5e80b4ae15
commit 4b4f014d38
No known key found for this signature in database
GPG key ID: 75BD0FEB8D3E7830
27 changed files with 281 additions and 284 deletions
Download patch file Download diff file Expand all files Collapse all files

58
doc/framing_protocol/framing_protocol.md
View file

@ -7,21 +7,21 @@
## 1 Introduction
This document describes a proposal for a transport level communication
protocol for the mta1_mkdf USB connected secure application device. The
proposal describes the different endpoints, the different levels in the
stack, framing and encoding.
protocol for the TK1 USB connected secure application device. The
proposal describes the different endpoints, the different levels in
the stack, framing and encoding.
## 2 System description and problem statement
The mta1_mkdf is a USB connected device. The device provides a secure
compute platform and environment for applications providing some service
and function to (the user of) the USB host. Examples of applications
that can be implemented are AUTH token generators, Root of Trust, and
signing oracles.
The TK1 is a USB connected device. The device provides a secure
compute platform and environment for applications providing some
service and function to (the user of) the USB host. Examples of
applications that can be implemented are AUTH token generators, Root
of Trust, and signing oracles.
The mta1_mkdf is implemented using FPGA devices, and the computer
functionality is based on RISC-V. Conceptually, the mta1_mkdf consists
of three levels:
The TK1 is implemented using FPGA devices, and the computer
functionality is based on RISC-V. Conceptually, the TK1 consists of
three levels:
1. The hardware level. The actual FPGA devices and the hardware
implemented in them, for example the RISC-V core, the application and
@ -29,33 +29,33 @@ of three levels:
hardware access control.
2. The mta1_mkdf firmware and SDK level. The mta1_mkdf contains SW
functionality (called firmware - FW) used to set up the application
environment, but also provide the applications with things like host
communication (the protocol described in this document), key
2. The TK1 firmware and SDK level. The TK1 contains SW functionality
(called firmware - FW) used to set up the application environment,
but also provide the applications with things like host
communication (the protocol described in this document), key
generation, timers etc.
Similarly, the SDK provides similar convenience functions for the
host side applications. Allowing host side applications to load
applications on the mta1_mkdf, and then communicate with, use the
applications running on the mta1_mkdf.
applications on the TK1, and then communicate with, use the
applications running on the TK1.
3. The applications running on the mta1_mkdf, the corresponding host SW.
3. The applications running on the TK1, the corresponding host SW.
The hardware, the FW as well as the applications can be endpoints with
which programs on the host may communicate. This means that we need to
be able to address different endpoints in the mta1_mkdf. And, crucially,
the applications and their corresponding host SW may communicate using
be able to address different endpoints in the TK1. And, crucially, the
applications and their corresponding host SW may communicate using
custom protocols that are not known today.
This means that we need a general transport mechanism for commands to,
and responses from the endpoints in the mta1_mkdf. Due to the
constrained environment the transport mechanism must be “light”, that is
both easy to implement and to require few resources
and responses from the endpoints in the TK1. Due to the constrained
environment the transport mechanism must be “light”, that is both easy
to implement and to require few resources
### 2.1 mta1_mkdf system description details
The mta1_mkdf consists of two FPGA devices - interface_fpga and
### 2.1 TK1 system description details
The TK1 consists of two FPGA devices - interface_fpga and
application_fpga.
The interface_fpga contains a USB core and FPGA-local control
@ -91,9 +91,9 @@ and sending responses.
## 3 Protocol description
The communication is driven by the host and the protocol is
command-response based. The host sends a command, and the mta1_mkdf must
always send a response to a given command. Commands are processed by the
mta1_mkdf in order. If the host sends a new command before receiving a
command-response based. The host sends a command, and the TK1 must
always send a response to a given command. Commands are processed by
the TK1 in order. If the host sends a new command before receiving a
response to the previous command, it is the responsibility of the host
to determine to which command a received response belongs to.
@ -154,7 +154,7 @@ Some examples to clarify endpoints and commands:
* 0x1a: A command to the application running in the application_fpga
with 32 bytes of data. The data could be a 32 byte challenge to be
signed using a private key derived in the mta1_mkdf.
signed using a private key derived in the TK1.
### 3.2 Response frame format

9
doc/system_description/software.md
View file

@ -184,7 +184,7 @@ Available commands/reponses:
#### `FW_{CMD,RSP}_VERIFY_DEVICE`
Verification that the device is an authentic Mullvad
Verification that the device is an authentic Tillitis
device. Implemented using challenge/response.
#### `FW_{CMD,RSP}_GET_APP_DIGEST`
@ -305,8 +305,7 @@ v v
The memory exposes SoC functionality to the software when in firmware
mode. It is a set of memory mapped registers (MMIO), starting at base
address `0xc000_0000`. For specific offsets/bitmasks, see the file
[mta1_mkdf_mem.h](../../hw/application_fpga/fw/mta1_mkdf_mem.h) (in
this repo).
[tk1_mem.h](../../hw/application_fpga/fw/tk1_mem.h) (in this repo).
Assigned core prefixes:
@ -320,7 +319,7 @@ Assigned core prefixes:
| UART | 0xc3 |
| TOUCH | 0xc4 |
| FW_RAM | 0xd0 |
| MTA1 | 0xff |
| TK1 | 0xff |
*Nota bene*: MMIO accesses should be 32 bit wide, e.g use `lw` and
`sw`. Exceptions are `FW_RAM` and `QEMU_DEBUG`.
@ -349,7 +348,7 @@ Assigned core prefixes:
| `UDA` | r | invisible | 16B | u8[16] | | Unique Device Authentication key. |
| `UDI` | r | r | 8B | u64 | | Unique Device ID (UDI). |
| `QEMU_DEBUG` | w | w | | u8 | | Debug console (only in QEMU) |
| `NAME0` | r | r | 4B | char[4] | "mta1" | ID of core/stick |
| `NAME0` | r | r | 4B | char[4] | "tk1 " | ID of core/stick |
| `NAME1` | r | r | 4B | char[4] | "mkdf" | ID of core/stick |
| `VERSION` | r | r | 4B | u32 | 1 | Current version. |
| `SWITCH_APP` | w | invisible? | 1B | u8 | | Switch to application mode. Write non-zero to trigger. |

26
doc/system_description/system_description.md
View file

@ -2,9 +2,9 @@
## Purpose and Revision
The purpose of this document is to provide a description of the
Tillitis Key 1 (TK1). What it is, what is supposed to be used for, by whom,
where and possible use cases. The document also provides a functional level
description of features and components of the mta1_mkdf.
Tillitis Key 1 (TK1). What it is, what is supposed to be used for, by
whom, where and possible use cases. The document also provides a
functional level description of features and components of the TK1.
Finally, the document acts as a requirement description. For the
requirements, the document follows
@ -60,7 +60,7 @@ The TK1 store and use the following assets internally:
- UDS - Unique Device Secret. Provisioned and stored during
device manufacturing. Never to be replaced during the life time of
a given device. Used to derive application secrets. Must never leave
the device. Mullvad must NOT store a copy of the UDS.
the device. Tillitis must NOT store a copy of the UDS.
- UDI - Unique Device ID. Provisioned and stored during
device manufacturing. Never to be replaced or altered during the life
@ -69,7 +69,7 @@ The TK1 store and use the following assets internally:
- UDA - Unique Device Authentication Secret. Provisioned and stored during
device manufacturing. Never to be replaced during the life time of
a given device. Used to authenticate a specific device. Must never
leave the device. Mullvad MUST have a copy of the UDA.
leave the device. Tillitis MUST have a copy of the UDA.
Additionally the following asset could be provided from the host:
@ -100,8 +100,8 @@ libraries etc. Roughly these can be divided into:
- host side application loader. Software that talks to the FW in the
application_fpga to load a secure application
- host side boot, management. Support software to boot, authenticate the
mta1_mkdf board connected to a host
- host side boot, management. Support software to boot, authenticate
the TK1 board connected to a host
- host side secure application. Software that communicates with the
secure application running in the application_fpga as needed to solve
@ -125,27 +125,27 @@ The Application FPGA hardware should provide the following:
- Unique Device ID (UDI)
- 64 bits
- Readable via API before application start
- Generated and stored by Mullvad
- Generated and stored by Tillitis
- Unique Device Authentication key (UDA)
- At least 128 bits number
- Readable by FW before application start
- Generated and stored by Mullvad
- Generated and stored by Tillitis
- Unique Device Secret (UDS)
- 256 bits
- Readable by HW before application start
- Generated but NOT stored by Mullvad
- Generated but NOT stored by Tillitis
- NAME
- 64 bits. ASCII string. "mta1_mkdf"
- 64 bits. ASCII string. "TK1 MKDF"
- Readable via API before application start
- Set by Mullvad as part of FPGA design
- Set by Tillitis as part of FPGA design
- VERSION: version
- 32 bits. 32 bit data, for example 1
- Readable via API before application start
- Set by Mullvad as part of FPGA design
- Set by Tillitis as part of FPGA design
2. Communication
- Rx-FIFO with status (data_available)