TKey Hardware Design #
The TKey hardware design consists of an FPGA device and some support components mounted on the PCB. The FPGA design contain the TKey System on Chip (SoC) where device applications are loaded and executed. Communication between the TKey SoC and a client app (running on the host computer) is handled by a small microcontroller (MCU) that handles conversion between USB and UART.
The SoC, called application_fpga consists of a CPU and a number of cores attached through the memory subsystem. The following is a description of the CPU, the cores, and the functionality they implement from a developer point of view.
The CPU of the TKey is a modified version of PicoRV32, 32-bit RISC-V running at 18 MHz. Modifications includes a fast 32x32 multiplier implemented using the multiplier blocks in the iCE40 DSPs as well as a HW trap function.
The supported instruction set supported by the CPU is a subset of RV32I. Specifically it includes compressed instructions, but excludes instructions for:
- CSR access
- Change level
- Trap redirect
The instruction set implemented by the CPU also includes
multiplication instructions from the RV32IC_Zmmul
-march=rv32iczmmul) extension. Division is not supported.
Any illegal, unsupported instruction will halt the CPU. The halted CPU is detected by the hardware, which will blink the RGB LED with red to indicate the error state. There is no way for the CPU to exit the trap state besides a power cycle of the device.
Note that the CPU has no support for interrupts. No instructions, ports or logic.
Execution Monitor #
The execution monitor can be used by TKey apps to prevent the CPU from trying to execute instructions from a defined memory area. When the execution monitor detects that the CPU is requesting instructions from the area, the monitor will force the CPU to read an illegal instruction. This will halt the CPU until it is reset.
The execution monitor is set up by writing the start and end addresses to the registers in the TK1 core. When the addresses have been set, the monitor is enabled by writing to the monitor control register. When enabled, the monitor cannot be disabled, and the addresses can’t be altered.
Note that the monitor also protects the FW (firmware) RAM. This area is always protected.
Firmware ROM #
The ROM (Read-Only Memory) contains the firmware. After a reset, the CPU will start executing the code at the beginning of the ROM, thus running the firmware. The firmware is then responsible for receiving, measuring and starting a device application. The ROM image is part of the FPGA bitstream.
The RAM is 128 kiB. The firmware clears and fills the RAM with a random word on power up.
Address Randomisation #
The TKey hardware includes a simple form of RAM memory protection from external threats. This might mitigate some of the problems of a warm boot attack potentially reading out all the RAM contents.
The memory protection is based on two separate mechanisms:
- Address randomisation
- Address dependent data scrambling
The address randomisation is implemented by XORing the CPU address
with the contents of the
ADDR_RAM_ASLR register in the TK1 core. The
result is used as the RAM address. This is set up by the firmware as
part of loading the TKey device app. The addresses will be transparent
to the device app and developers don’t have to do anything to use it.
For more information about this, please see the Tillitis Key system description (in the tillitis-key1 repository).
Note that this is not ASLR in the sense of randomising offsets to the stack or well-known functions. This is address randomisation as seen from outside of the running process.
RAM Scrambler #
The data scrambling is implemented by XORing the data written to the
RAM with the contents of the
ADDR_RAM_SCRAMBLE register in the TK1
core as well as XORing with the CPU address. This means that the same
data written to two different addresses will be scrambled differently.
The same pair or XOR operations is also performed on the data read out
from the RAM.
The data scrambling is set up by the firmware as part of loading the TKey device app. The scrambling will be transparent to the app and developers don’t have to do anything to use it.
A general purpose 32-bit timer. The timer will count down every cycle, from the initial value down to one. In order to handle long time sequences (minutes, hours, days) there is also a 32-bit prescaler. If the prescaler is set to 18_000_000, the timer ticks every second because the CPU is running at 18 MHz.
A standard UART (Universal Asynchronous Receiver/Transmitter) interface is used for sending and receiving bytes to a TKey device app via the interface microcontroller on the TKey. The UART default configuration is:
|0, 1, 2
All configuration, except for parity, can be configured by the device app. Note that the client app must set the same configuration.
The UART contains a 512-bit Rx-FIFO with status (data available).
The device app can read from the UART by polling
until it is non-zero. The received byte is then available in the LSB
(Least Significant Byte) of the
Writing is done by polling
UART_TX_STATUS until it is non-zero. The
byte to transmit can then be written to the LSB of the
True Random Number Generator (TRNG) #
The True Random Number Generator (TRNG) ring oscillator based internal entropy source.
The TRNG generates randomness with a fairly good quality. However for security related use cases, for example generating keys, the TRNG should not be used directly. Instead use it to create a seed for a Digital Random Bit Generator (DRBG), also known as a Cryptographically Safe Pseudo Random Number Generator (CSPRNG). Examples of such generators are Hash_DRGG, CTR_DRBG, HKDF.
Getting a word of entropy is done by polling
non-zero, then reading the word from
Touch Sensor #
The touch_sense core provides an interface to the touch sensor on the TKey device. Using the core, the firmware as well as applications can get information about touch events and manage detection of events.
It is recommended to start handling touch events by acknowledging any stray event before signalling to the user that a touch event is expected, and then start waiting for the event.
The TKey core contains several functions, and acts as the main hardware interface between firmware and device applications. The core has:
Read access to the 64 bit FPGA design name, expressed as ASCII chars:
Read access to the 32 bit FPGA design version, expressed as an integer:
Control of and status access for the RGB LED on the TKey, called
LEDin the memory map.
- Setting bit 0 high turns on the Blue LED.
- Setting bit 1 high turns on the Green LED.
- Setting bit 2 high turns on the Red LED.
Control of and status access for the 4 GPIO (General-purpose Input/Output) pins on the TKey. Called
GPIOin the memory map.
GPIO 1 and 2 are inputs and provide read access to the current sampled value digital values on the pins.
GPIO 3 and 4 are outputs. The digital value written to the bits is presented on the pins.
Application read access to information about the loaded application. The information is written by the firmware.
- Start address, called
APP_ADDRin the memory map.
- Size of device app, called
APP_SIZEin the memory map.
- Start address, called
Application read access to the Compound Device Identifier (CDI) generated and written by the firmware when the application is loaded. Called
CDI_LASTin the memor map.
Application-Firmware execution mode control. Can be written to by the firmware, and read by device app. When the firmware writes to it, the hardware will switch to application mode. Called
SWITCH_APPin the memory map.