diff --git a/doc/system_description/system_description.md b/doc/system_description/system_description.md index 2c43ee9..b6385c3 100644 --- a/doc/system_description/system_description.md +++ b/doc/system_description/system_description.md @@ -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 +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 -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 requirements, the document follows @@ -12,20 +12,20 @@ requirements, the document follows requirement levels. 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: -- Implementors of the TK1 hardware, firmware and SDKs -- Developers of secure applications for the TK1 +- Implementors of the TKkey hardware, firmware and SDKs +- Developers of secure applications for the TKey - Technically skilled third parties that wants to understand the - TK1 + TKey ## Introduction -The TK1 is a USB-connected, RISC-V based application platform. The -purpose of the TK1 is to provide a secure application environment +The TKey is a USB-connected, RISC-V based application platform. The +purpose of the TKey is to provide a secure environment 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 - Signing oracles @@ -33,75 +33,85 @@ user. Some examples of such security functionality are: ### 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 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 -derived will also change. Conversely, if the keys derived are the same as -last time the application was loaded onto the same device, the -application can be trusted not to have been altered. +The consequence of this is that if the application is altered, +the base secret derived will also change. Conversely, if the keys +derived from the base secret are the same as the last time the +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 -loaded onto another TK1 device will cause a different set of keys -to be derived. This ties keys to a specific device. +loaded onto another TKey device will derive a different set of keys. +This ties keys to a specific device. The derivation can also be combined with a User Supplied Secret (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 -the keys are protected and can be trusted because of the measurement -being used in the derivation. +the derived can be trusted because of the measurement being used +by the derivation, thereby verifying the intergrity od the application. ### 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 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 - device manufacturing. Never to be replaced or altered during the life - time of a given device. May be copied, extracted, read from the device. +- UDI - Unique Device ID. 64 bits. Provisioned and stored during device + manufacturing. Accessible by FW and applications. Never to be replaced + 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 - 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. Tillitis MUST have a copy of the UDA. +- CDI - Compound Device Identity. Dervied by the FW when an application + is loaded using the UDS and the application binary. Used by the + application to derive secrets, keys as needed. The CDI should never + be exposed outside of the application_fpga Additionally the following asset could be provided from the host: -- USS - User Supplied Secret. Provisioned by the application. May - possibly be replaced many times. Supplied from the host to the - device. Should not be revealed to a third party. +- USS - User Supplied Secret. May possibly be replaced many times. + Supplied from the host to the device. Should not be revealed to a + third party. ### 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 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 - applications, derive keys etc +- application_fpga. FPGA design with cores including CPU and memory that + implements the secure application platform -- application_fpga secure application. One or more applications loaded - into the application_fpga to provide some functionality to the user of - the host +- application_fpga FW. The base software running on the CPU as needed to + boot, load applications, measure applications, dderive base secret etc + +- 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 application_fpga to load a secure application - 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 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 -## 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 - More detailed information about the software running on the device (referred to firmware, SDK, and secure application), can be found in the [software document](software.md). @@ -227,7 +147,6 @@ scratched. - Push button - User Supplied Secret (USS) - - Open Questions to be investigated, handled - Terminology - naming things - How to create trust in the SDKs