From 49d4735f170db40246ad1e639857763e8579265d Mon Sep 17 00:00:00 2001 From: Daniel Lublin Date: Fri, 2 Dec 2022 07:17:14 +0100 Subject: [PATCH] Use TKey name Signed-off-by: Daniel Lublin --- LICENSES/README.md | 2 +- README.md | 6 ++-- doc/quickstart.md | 38 ++++++++++---------- doc/system_description/system_description.md | 11 +++--- doc/threat_model/threat_model.md | 12 +++---- hw/application_fpga/Makefile | 2 +- hw/application_fpga/core/trng/README.md | 2 +- hw/application_fpga/tools/tpt/README.md | 13 +++++-- 8 files changed, 47 insertions(+), 39 deletions(-) diff --git a/LICENSES/README.md b/LICENSES/README.md index 699ef20..9157089 100644 --- a/LICENSES/README.md +++ b/LICENSES/README.md @@ -1,4 +1,4 @@ -# Tillitis Key 1 Licensing +# Tillitis TKey Licensing ## Main license diff --git a/README.md b/README.md index 51f476e..33ce953 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ -# Tillitis Key +# Tillitis TKey ## Introduction -Tillitis Key (TKey) is a new kind of USB security token. What makes -the TKey unique is that it allows a user to load and run applications on +The Tillitis TKey is a new kind of USB security token. What makes the +TKey unique is that it allows a user to load and run applications on the device, while still providing security. This allow for open-ended, flexible usage. Given the right application, the TKey can support use cases such as SSH login, Ed25519 signing, Root of Trust, FIDO2, TOTP, diff --git a/doc/quickstart.md b/doc/quickstart.md index a1e17ff..bdc9f5f 100644 --- a/doc/quickstart.md +++ b/doc/quickstart.md @@ -1,31 +1,31 @@ -# TK1 Quickstart +# Tillitis TKey Quickstart This document describes how to build the FPGA bitstream, including the firmware, and get this programmed onto the flash memory of the -Tillitis Key 1 USB device. +Tillitis TKey USB device. -*Note well*: If you have an already flashed TK1 you don't need to do -anything unless you want to set your own Unique Device Secret (UDS). -You can start running apps on it immediately. See +*Note well*: If you have a TKey which already has been flashed, then +you don't need to do anything unless you want to set your own Unique +Device Secret (UDS). You can start running apps on it immediately. See [tillitis-key1-apps](https://github.com/tillitis/tillitis-key1-apps) for a few examples. -The Tillitis Key 1 kit includes: +The Tillitis TKey kit includes: -- Tillitis Key 1 USB stick with USB-C plug, marked MTA1-USB V1 +- Tillitis TKey USB stick with USB-C plug, marked MTA1-USB V1 - Programmer board based on Raspberry Pi Pico, with a white holder/jig - USB cable with micro-B plug, for connecting the programmer to computer - USB-C extension cable - USB-C to USB-A adapter -## Programming FPGA bitstream and firmware onto Tillitis Key 1 +## Programming FPGA bitstream and firmware onto TKey Connect the programmer to the computer using the USB cable with micro-B plug. -Place the Tillitis Key 1 (the USB stick) correctly in the programming -jig and close the hatch. +Place the TKey USB stick correctly in the programming jig and close +the hatch. The USB stick can remain in the jig during repeated development, programming and testing cycles. The USB stick should then be connected @@ -37,8 +37,8 @@ also that with this setup, to reset the USB stick back to firmware mode after loading an app, you need to unplug both the USB cable to the stick and the one to the programmer. Alternatively, you can try the script in `../hw/application_fpga/tools/reset-tk1` which pokes at -the TK1 that's sitting in the jig, leaving it in firmware mode so that -a new app can be loaded. +the TKey that's sitting in the jig, leaving it in firmware mode so +that a new app can be loaded. On Linux, `lsusb` should list the connected programmer as `cafe:4004 Blinkinlabs ICE40 programmer`. If the USB stick is also connected it @@ -50,7 +50,7 @@ refer to [toolchain_setup.md](toolchain_setup.md). You are now ready to generate the FPGA bitstream (including building the standard firmware) and program it onto the flash memory of the USB stick. Note that this will give a default Unique Device Secret. If you -want to personalize your TK1, see under Device personalization below +want to personalize your TKey, see under Device personalization below first. The following should be run as your regular non-root user, but @@ -63,10 +63,10 @@ $ cd tillitis-key1/hw/application_fpga $ make prog_flash ``` -After programming, the Tillitis Key 1 USB stick can be connected to -your computer (use the USB-C-to-A adapter if needed) and will boot the -firmware. When boot has completed it will start flashing the LED -white. This indicates that it is ready to receive and measure an app. +After programming, the TKey can be connected to your computer (use the +USB-C-to-A adapter if needed) and will boot the firmware. When boot +has completed it will start flashing the LED white. This indicates +that it is ready to receive and measure an app. To try out an app, continue to the README.md the apps repo: https://github.com/tillitis/tillitis-key1-apps#readme @@ -77,8 +77,8 @@ and [system_description/software.md](system_description/software.md). ## Device personalization - setting Unique Device Secret (UDS) -To personalize Tillitis Key 1 you need to modify the Unique Device -Secret (UDS) and, maybe, the Unique Device Identity (UDI). +To personalize your TKey you need to modify the Unique Device Secret +(UDS) and, maybe, the Unique Device Identity (UDI). The simplest way to generate a new UDS is to: diff --git a/doc/system_description/system_description.md b/doc/system_description/system_description.md index f8d06ec..0358845 100644 --- a/doc/system_description/system_description.md +++ b/doc/system_description/system_description.md @@ -1,18 +1,19 @@ # System Description ## Purpose and Revision + The purpose of this document is to provide a description of the -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 TKey. +Tillitis 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 TKey. Finally, the document acts as a requirement description. For the requirements, the document follows [RFC2119](https://datatracker.ietf.org/doc/html/rfc2119) to indicate requirement levels. -The described functionality and requirements applies -to version one of the TKey (TK1) +The described functionality and requirements applies to version 1 of +the TKey (TK1) The intended users of this document are: - Implementors of the TKkey hardware, firmware and SDKs diff --git a/doc/threat_model/threat_model.md b/doc/threat_model/threat_model.md index 8a25ea5..99639ca 100644 --- a/doc/threat_model/threat_model.md +++ b/doc/threat_model/threat_model.md @@ -1,11 +1,11 @@ # Threat model ## Introduction -The Tillitis Key 1 is a platform for running secure applications in a -restricted execution environment physically separate from the -device host. The secure applications provide functionality and -controlled access to derived secrets on the device. The purpose of the -device is to solve typical end user authentication problems. +The Tillitis TKey is a platform for running secure applications in a +restricted execution environment physically separate from the device +host. The secure applications provide functionality and controlled +access to derived secrets on the device. The purpose of the device is +to solve typical end user authentication problems. This document describes the threat model for device. Based on the system description and use cases, the threat model tries to capture and @@ -18,7 +18,7 @@ The threat model will get updated and expanded for each release. ### engineering-release-1 This is an early release aimed at developers interested -in writing applications for Tillitis Key 1. The design allows easy access to +in writing applications for Tillitis TKey. The design allows easy access to the board, and is even shipped with a programmer to download new FPGA bitstreams. diff --git a/hw/application_fpga/Makefile b/hw/application_fpga/Makefile index f2b2f1d..0ea5826 100644 --- a/hw/application_fpga/Makefile +++ b/hw/application_fpga/Makefile @@ -105,7 +105,7 @@ phony_explicit: .PHONY: phony_explicit #------------------------------------------------------------------- -# Personalization of the TK1 +# Personalization of the TKey #------------------------------------------------------------------- secret: diff --git a/hw/application_fpga/core/trng/README.md b/hw/application_fpga/core/trng/README.md index 330d02e..db31152 100644 --- a/hw/application_fpga/core/trng/README.md +++ b/hw/application_fpga/core/trng/README.md @@ -2,7 +2,7 @@ Implementation of the Tillitis True Random Number Generator (TRNG). ## Introduction -Applications running on the Tillitis Key device may have a need of random numbers. +Applications running on the Tillitis TKey device may have a need of random numbers. As unpredictable initial vectors, as challnges, random tokens etc. The Tillitis TRNG supports these applications by providing a hardware based diff --git a/hw/application_fpga/tools/tpt/README.md b/hw/application_fpga/tools/tpt/README.md index b4b508d..6a20e46 100644 --- a/hw/application_fpga/tools/tpt/README.md +++ b/hw/application_fpga/tools/tpt/README.md @@ -1,8 +1,15 @@ -# Tillitis Key Provisioning Tool +# Tillitis TKey Provisioning Tool ## Introduction -Tillis Key Provisioning Tool (tpt) is a program for generating the 32 byte Unique Device Secret (UDS). The tool will also generate the 8 byte Unique Device Identity. Both the UDS and the UDI are injected into the FPGA bitstream file during build. -The UDS is generated using HKDF (RFC 5869), and the user is expected to supply a secret as part of the input to the HKDF Extract operation. The Input Keying Material is generated by extracting 256 bytes using the Python secrets module. +TKey Provisioning Tool (tpt) is a program for generating the 32 byte +Unique Device Secret (UDS). The tool will also generate the 8 byte +Unique Device Identity. Both the UDS and the UDI are injected into the +FPGA bitstream file during build. + +The UDS is generated using HKDF (RFC 5869), and the user is expected +to supply a secret as part of the input to the HKDF Extract operation. +The Input Keying Material is generated by extracting 256 bytes using +the Python secrets module. The tool uses [python-hkdf](https://github.com/casebeer/python-hkdf).