Git-Mirrors/tillitis-key
1
0
Fork 0
mirror of https://github.com/tillitis/tillitis-key1.git synced 2025-01-01 19:06:22 -05:00
Code Issues Packages Projects Releases Wiki Activity

Update system description to match all changes

Browse Source 
Signed-off-by: Joachim Strömbergson <joachim@assured.se>
This commit is contained in:
Joachim Strömbergson 2022-11-29 13:42:13 +01:00
parent 579a8fd053
commit 8227f585af
1 changed files with 52 additions and 133 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

185
doc/system_description/system_description.md
View File

@ -2,9 +2,9 @@
## Purpose and Revision ## Purpose and Revision
The purpose of this document is to provide a description of the 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 Tillitis Key (TKey). What it is, what is supposed to be used for, by
whom, where and possible use cases. The document also provides a whom, where and possible use cases. The document also provides a
functional level description of features and components of the TK1. functional level description of features and components of the TKey.
Finally, the document acts as a requirement description. For the Finally, the document acts as a requirement description. For the
requirements, the document follows requirements, the document follows
@ -12,20 +12,20 @@ requirements, the document follows
requirement levels. requirement levels.
The described functionality and requirements applies The described functionality and requirements applies
to version one (v1) of the TK1. to version one of the TKey (TK1)
The intended users of this document are: The intended users of this document are:
- Implementors of the TK1 hardware, firmware and SDKs - Implementors of the TKkey hardware, firmware and SDKs
- Developers of secure applications for the TK1 - Developers of secure applications for the TKey
- Technically skilled third parties that wants to understand the - Technically skilled third parties that wants to understand the
TK1 TKey
## Introduction ## Introduction
The TK1 is a USB-connected, RISC-V based application platform. The The TKey is a USB-connected, RISC-V based application platform. The
purpose of the TK1 is to provide a secure application environment purpose of the TKey is to provide a secure environment
for applications that provides some security functionality needed by the for applications that provides some security functionality needed by the
user. Some examples of such security functionality are: device user. Some examples of such security functionality are:
- TOTP token generators - TOTP token generators
- Signing oracles - Signing oracles
@ -33,75 +33,85 @@ user. Some examples of such security functionality are:
### Measured Based Security ### Measured Based Security
The key, unique feature of the TK1 is that it measures the secure The key, unique feature of the TKey is that it measures the secure
application when the application is being loaded onto the device. The application when the application is being loaded onto the device. The
measurement (a hash digest), combined with a Unique Device Secret measurement (a hash digest), combined with a Unique Device Secret
(UDS) is used to derive secrets for the application. (UDS) is used to derive a base secret for the application.
The consequence of this is that if the application is altered, the keys The consequence of this is that if the application is altered,
derived will also change. Conversely, if the keys derived are the same as the base secret derived will also change. Conversely, if the keys
last time the application was loaded onto the same device, the derived from the base secret are the same as the last time the
application can be trusted not to have been altered. application was loaded onto the same device, the application can
be trusted not to have been altered.
Note that since the UDS is per-device unique, the same application Note that since the UDS is per-device unique, the same application
loaded onto another TK1 device will cause a different set of keys loaded onto another TKey device will derive a different set of keys.
to be derived. This ties keys to a specific device. This ties keys to a specific device.
The derivation can also be combined with a User Supplied Secret The derivation can also be combined with a User Supplied Secret
(USS). This means that keys derived are both based on something the user (USS). This means that keys derived are both based on something the user
has - the specific device, and something the user knows (the USS). And has - the specific device, and something the user knows (the USS). And
the keys are protected and can be trusted because of the measurement the derived can be trusted because of the measurement being used
being used in the derivation. by the derivation, thereby verifying the intergrity od the application.
### Assets ### Assets
The TK1 store and use the following assets internally: The TKey store and use the following assets internally:
- UDS - Unique Device Secret. Provisioned and stored during - UDS - Unique Device Secret. 256 bits. Provisioned and stored during
device manufacturing. Never to be replaced during the life time of device manufacturing. Never to be replaced during the life time of
a given device. Used to derive application secrets. Must never leave a given device. Used to derive application secrets. Must never leave
the device. Tillitis must NOT store a copy of the UDS. the device. Tillitis will NOT store a copy of the UDS. Can be read
by firmware once between power cycling
- UDI - Unique Device ID. Provisioned and stored during - UDI - Unique Device ID. 64 bits. Provisioned and stored during device
device manufacturing. Never to be replaced or altered during the life manufacturing. Accessible by FW and applications. Never to be replaced
time of a given device. May be copied, extracted, read from the device. or altered during the life time of a given device. May be copied,
extracted, read from the device.
- UDA - Unique Device Authentication Secret. Provisioned and stored during - CDI - Compound Device Identity. Dervied by the FW when an application
device manufacturing. Never to be replaced during the life time of is loaded using the UDS and the application binary. Used by the
a given device. Used to authenticate a specific device. Must never application to derive secrets, keys as needed. The CDI should never
leave the device. Tillitis MUST have a copy of the UDA. be exposed outside of the application_fpga
Additionally the following asset could be provided from the host: Additionally the following asset could be provided from the host:
- USS - User Supplied Secret. Provisioned by the application. May - USS - User Supplied Secret. May possibly be replaced many times.
possibly be replaced many times. Supplied from the host to the Supplied from the host to the device. Should not be revealed to a
device. Should not be revealed to a third party. third party.
### Subsystems and Components ### Subsystems and Components
The TK1 as a project, system and secure application platform The TKey as a project, system and secure application platform
consists of a number of subsystems and components, modules, support consists of a number of subsystems and components, modules, support
libraries etc. Roughly these can be divided into: libraries etc. Roughly these can be divided into:
- TK1 boards. PCB designs for development and general usage - TKey boards. PCB designs including schematics, Bill of Material (BOM)
and layout, as needed for development, production and and general usage
of the TKey devices
- USB to UART controller - TKey programmer. SW, PCB designs including schematics, Bill of
Material (BOM) and layout, as needed for development, production
and and provisioning, programming general usage
- application_fpga. FPGA design with cores including CPU and memory - USB to UART controller. FW for the MCU implementing the USB host
interface on the TKey
- application_fpga FW. The base software running on the CPU to boot, load - application_fpga. FPGA design with cores including CPU and memory that
applications, derive keys etc implements the secure application platform
- application_fpga secure application. One or more applications loaded - application_fpga FW. The base software running on the CPU as needed to
into the application_fpga to provide some functionality to the user of boot, load applications, measure applications, dderive base secret etc
the host
- One or more applications loaded onto the application_fpga to provide
some functionality to the user of the host
- host side application loader. Software that talks to the FW in the - host side application loader. Software that talks to the FW in the
application_fpga to load a secure application application_fpga to load a secure application
- host side boot, management. Support software to boot, authenticate - host side boot, management. Support software to boot, authenticate
the TK1 board connected to a host the TKey device connected to a host
- host side secure application. Software that communicates with the - host side secure application. Software that communicates with the
secure application running in the application_fpga as needed to solve secure application running in the application_fpga as needed to solve
@ -118,97 +128,7 @@ libraries etc. Roughly these can be divided into:
examples to support development of the host applications examples to support development of the host applications
## Application FPGA Hardware Functionality
The Application FPGA hardware should provide the following:
1. Fixed information
- Unique Device ID (UDI)
- 64 bits
- Readable via API before application start
- 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 Tillitis
- Unique Device Secret (UDS)
- 256 bits
- Readable by HW before application start
- Generated but NOT stored by Tillitis
- NAME
- 64 bits. ASCII string. "TK1 MKDF"
- Readable via API before application start
- 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 Tillitis as part of FPGA design
2. Communication
- Rx-FIFO with status (data_available)
- 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 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
3. I/O
- LED (RGB)
- Status and control in LED address
- Readable and writable by FW and application
4. Counter
- One general purpose counter
- Prescaler (for counting cycles and seconds)
- Start value, alternatively reset
- Saturating max, alternatively stop at zero
- Readable and writable by FW and application
5. TRNG
- ROSC based internal entropy source
- Von Neumann decorrelation
- Simple self-testing ability
- 32 bit data
- Status (data_ready, error)
- Readable by FW and application
6. Introspection
- Address och size of loaded application
- Readable by FW and application
## Application FPGA Firmware Functionality
The firmware in the application should provide the following
functionality:
- Read access to fixed values:
- application_fpga name and version strings
- Unique Device ID (UDI)
- Read and write to test register used for debugging
- Respond to challenge/response based device authentication commands
- Receive and store a 32 byte User Supplied Secret (USS)
- Receive, store and measure a secure application
- Derive Compound Device Identifier (CDI) given measurement, UDS and USS
- Provide hashing using Blake2s
- Start a loaded application. This includes locking down access to UDS,
UDA etc
## References ## References
More detailed information about the software running on the device More detailed information about the software running on the device
(referred to firmware, SDK, and secure application), can be found in (referred to firmware, SDK, and secure application), can be found in
the [software document](software.md). the [software document](software.md).
@ -227,7 +147,6 @@ scratched.
- Push button - Push button
- User Supplied Secret (USS) - User Supplied Secret (USS)
- Open Questions to be investigated, handled - Open Questions to be investigated, handled
- Terminology - naming things - Terminology - naming things
- How to create trust in the SDKs - How to create trust in the SDKs