tillitis-key/doc/release_notes.md

# Release Notes

Descriptions of the tagged TKey releases.


## TK1-23.03
This is the official release of the "Bellatrix" version of
the Tillitis TKey device. This version is ready for general
use.

Given the OCI image `ghcr.io/tillitis/tkey-builder:1` built from
`contrib/Dockerfile` and the generic UDS.hex and UDI.hex, a clean
build should generate the following digest:

```
shasum -a256 application_fpga.bin
f11d6b0f57c5405598206dcfea284008413391a2c51f124a2e2ae8600cb78f0b  application_fpga.bin
```


### New and improved functionality

- (ALL) The TKey HW design, FW, protocol and first applications has
  been audited by a third party. No major issues was found, but the
  audit has lead to several updates, changes and fixes to improve
  the security and robustness. The third party report will be
  published when completed.

- (APPS) Applications can now use the whole 128 kByte RAM.

- (FW) The firmware now use the `FW_RAM` for the stack. It keeps no
  .bss or .data segments and only uses RAM for loading the
  application.

- (FW) The firmware has been hardened and the state machine simplified
  to reduce the number of commands that can be used and in which
  order. It exits early on failure to a fail state indicated by the
  RGB LED blinking red on error in an eternal loop.

- (FW) Steady white LED while waiting for initial commands. LED off
  while loading app.

- (HW) The memory system now has an execution monitor. The monitor
  detects attempts at reading instructions from the firmware ram.
  The execution monitor can also, when enabled by an application,
  detect attempts at reading instructions from the application
  stack. If any such attempt is detected, the memory system will
  force the CPU to read an illegal instruction, triggering the
  trap state in the CPU.

  Note that the execution monitor can only be enabled, not
  disabled. The address range registers defining the region
  protected by the monitor can only be set when the monitor
  has not yet been enabled.

- (HW) The CPU trap signal is now connected to an illegal instruction
  trap indicator. When an illegal instruction is detected, the RGB LED
  will start flashing red. Note that the CPU will stay in the trap
  state until the TKey device is disconnected.

- (HW) The RAM memory now includes an initial adress and scrambling
  mechanism to make it harder to find assets generated by and
  stored in the RAM by applications. The address space layout
  randomizarion (ASLR) and data value scrambling is set up by the
  firmware before the application is loaded, and does not affect
  how applications executes.

- (HW) The UART Rx FIFO now allows applications to read out the
  number of bytes received and not yet consumed by the application.

- (HW) The FPGA bitstream can now be stored in the non volatile
  configuration memory (NVCM). This is done using of a new icestorm
  tool developed partly in the project and sponsored by Tillitis
  and Mullvad. The tool supports locking down NVCM access after
  writing the FPGA bitstream to the memory.

- (TOOLS) There is now an OCI image
  (`ghcr.io/tillitis/tkey-builder:1`) and Dockerfile setting up all
  tools as needed to build the bitstream.

- (TOOLS) There is now a version of iceprog able to write to the FPGA
  bitstream to the NVCM and lock the NVCM from external access


### Bugs fixed
- No known bugs have been fixed. Numerous issues has been closed.


### Limitations

- The RAM address and data scrambling in this release is not
  cryptographically secure. It his however randomized every time
  a TKey device is powered up.


## engineering-release-2

### New and improved functionality

- (HW) The rosc TRNG has now been completed and tested. The TRNG
  can now be used to generate seeds by applicaitons.

- (HW) The main clock frequency has been increased to 18 MHz.

- (HW) The FW now has a separate RAM used during loading and
  measurement of applications.

- (HW) The UART Rx FIFO is now able to handle 512 bytes.

- (HW) The UART default bitrate has been increased to 62500 bps.

- (HW) Support for division instruction (div) was removed from
  PicoRV32. Please compile your programs with the Zmmul extension,
  `-march=rv32iczmmul` for `clang`.

- (HW) The UDI is locked down and can now only be accessed by
  firmware, not applications.

- (HW) The timer MMIO API now takes separate start and stop bits for
  triggering the respective action, mitigating a time-of-check to
  time-of-use (TOCTOU) issue.

- (FW) The firmware has been restructured to be a Finite State
  Machine (FSM) with defined states for booting, loading
  applications, measure applications, calculate the CDI and
  start the loaded application.

  This change also changes the firmware protocol which now accepts a
  request to load a binary with an optional USS and automatically
  returns its digest and start the program when the last data chunk is
  received.

- (FW) A BLAKE2s hash function present in firmware is now exposed for use
  by TKey apps (through a function pointer located in MMIO `BLAKE2S`).
  See [software.md](system_description/software.md) for more
  information.

- (FW) To make warm boot attacks harder, the firmware sleeps for a
  random number of cycles before reading out the sensitive UDS into
  FW RAM.

## engineering-release-1

### Hardware

#### Limitations

- The entropy generated by the TRNG has not yet been thoroughly tested,
  and the generator has not been adjusted to generate good, unbiased
  randomness. Any application that wants to use the entropy source
  SHOULD NOT use the output directly, but only as seed to a Digital
  Random Bit Generator (DRBG), such as Hash_DRBG.

- The UART is currently running at 38400 bps. Future releases will
  increase the bitrate when communication at higher bitrates has
  been verified as stable and error free.

- The internal clock frequency is currently limited to 12 MHz.
  Future releases will increase the clock frequency to provide
  improved performance.

- The functionality in the firmware is currently not exposed to the
  applications via a stable name space, API. Future releases will
  provide access to FW functions such as the BLAKE2s hash function.

- The timer currently does not include a timeout interrupt. Applications
  using the timer must check the status in order to detect a timeout event.

- The timer currently does not provide a set of typical settings.
  Applications using the timer must set timer and prescaler as
  needed to get the desired time given the current clock speed.