{"id":13996062,"url":"https://github.com/tillitis/tillitis-key1","last_synced_at":"2026-01-12T13:08:13.989Z","repository":{"id":59683064,"uuid":"538359993","full_name":"tillitis/tillitis-key1","owner":"tillitis","description":"Board designs, FPGA verilog, firmware for TKey, the flexible and open USB security key 🔑","archived":false,"fork":false,"pushed_at":"2024-04-09T11:43:49.000Z","size":20056,"stargazers_count":380,"open_issues_count":29,"forks_count":24,"subscribers_count":10,"default_branch":"main","last_synced_at":"2024-04-12T09:04:41.903Z","etag":null,"topics":["fpga","open-hardware","security-token"],"latest_commit_sha":null,"homepage":"https://www.tillitis.se","language":"Verilog","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tillitis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSES/README.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-09-19T06:18:37.000Z","updated_at":"2024-03-29T16:01:21.000Z","dependencies_parsed_at":"2024-04-09T11:57:28.871Z","dependency_job_id":null,"html_url":"https://github.com/tillitis/tillitis-key1","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tillitis%2Ftillitis-key1","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tillitis%2Ftillitis-key1/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tillitis%2Ftillitis-key1/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tillitis%2Ftillitis-key1/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tillitis","download_url":"https://codeload.github.com/tillitis/tillitis-key1/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227190727,"owners_count":17745306,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fpga","open-hardware","security-token"],"created_at":"2024-08-09T14:03:47.515Z","updated_at":"2026-01-12T13:08:13.982Z","avatar_url":"https://github.com/tillitis.png","language":"Verilog","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"[![ci](https://github.com/tillitis/tillitis-key1/actions/workflows/ci.yaml/badge.svg?branch=main\u0026event=push)](https://github.com/tillitis/tillitis-key1/actions/workflows/ci.yaml)\n\n# Tillitis TKey\n\nRead about current work in progress\n[here](#current-work-in-progress-in-this-repository).\n\n![TK1 PCB](doc/images/tkey-open-lid.png) *The TK1 PCB, also known as\nTKey.*\n\n## Introduction\n\nThe Tillitis TKey is an open source, open hardware FPGA-based USB\nsecurity token using\n[DICE-like](https://trustedcomputinggroup.org/work-groups/dice-architectures/)\nunconditional measured boot that can run generic applications while\nstill guaranteeing the security of its cryptographic assets.\n\n[TKey Threat Model](doc/threat_model/threat_model.md).\n\nWith the right application, the TKey can be used for:\n\n- authentication,\n- cryptographic signing,\n- encryption,\n- root of trust,\n- and more: it's a general computer!\n\nIf you want to know more about Tillitis and the TKey, visit:\n\n- Main web: \u003chttps://tillitis.se/\u003e\n- Shop: \u003chttps://shop.tillitis.se/\u003e\n- Developer Handbook: \u003chttps://dev.tillitis.se/\u003e\n- Officially supported apps: \u003chttps://tillitis.se/download/\u003e\n- Other known apps: \u003chttps://dev.tillitis.se/projects/\u003e\n\nAll of the TKey software, firmware, FPGA Verilog code, schematics and\nPCB design files are open source, just like all trustworthy security\nsoftware and hardware should be.\n\n## Licensing\n\nUnless otherwise noted, the project sources are copyright Tillitis AB,\nbut you can redistribute it and/or modify it under the terms of the\nBSD-2-Clause license.\n\nUntil Oct 29, 2025, the license was GPL-2.0 Only.\n\nEach imported project is typically kept in its own directory with its\nown LICENSE file.\n\n### SPDX\n\nThe project uses single-line references to Unique License Identifiers\nas defined by the Linux Foundation's [SPDX project](https://spdx.org/).\nThe line in each individual source file identifies the license\napplicable to that file.\n\nThe current set of valid, predefined SPDX identifiers can be found on\nthe SPDX License List at:\n\nhttps://spdx.org/licenses/\n\nWe attempt to follow the [REUSE\nspecification](https://reuse.software/).\n\n### Notable imported projects\n\n- ch552 firmware: `hw/usb_interface/ch552_fw/`\n\n  Originally by WCH under MIT. Much changed by Tillitis.\n\n- picorv32: `hw/application_fpga/core/picorv32`\n\n  From https://github.com/YosysHQ/picorv32\n\n  ISC.\n\n- PicoRV32 custom ops: `hw/application_fpga/fw/tk1/picorv32/`\n\n  CC-1.\n\n- tkey-libs: `hw/application_fpga/tkey-libs/`\n\n  BSD2. From https://github.com/tillitis/tkey-libs\n\n## Repositories\n\nThis repository contains the FPGA design, the source of the\nfirmware/bootloader, and the source of the USB controller firmware.\n\nSpecific documentation regarding implementation is kept close to the\ncode/design in README files, typically in the same directory.\n\nNote that development is ongoing. To avoid unexpected changes of\nderived key material, please use a tagged release. Read the [Release\nNotes](doc/release_notes.md) to keep up to date with changes and new\nreleases.\n\nThe TKey PCB [KiCad](https://www.kicad.org/) design files are kept in\na separate repository:\n\n\u003chttps://github.com/tillitis/tk1-pcba\u003e\n\nThe TP1 (TKey programmer 1) PCB design files and the firmware sources\nare kept in:\n\n\u003chttps://github.com/tillitis/tp1\u003e\n\nNote that the TP1 is only used for provisioning the FPGA bitstream\ninto flash or the FPGA configuration memory. It's not necessary if you\njust want to develop apps for the TKey.\n\nWe use the tkey-libs libraries used for device app development in the\nfirmware, too:\n\nhttps://github.com/tillitis/tkey-libs\n\nbut keep our own copy of it in the repo. See below.\n\n## Building \u0026 flashing\n\nThese instructions assume you're using a Linux distribution. Most of\nthem also assume you're using our OCI image\n[tkey-builder](https://ghcr.io/tillitis/tkey-builder). If you want to\nrun native tools, look in `contrib/Dockerfile` and\n`contrib/buildtools.sh` for the tools and versions to use.\n\n### FPGA\n\nYou need a [TKey\nUnlocked](https://shop.tillitis.se/products/tkey-not-provisioned), a\n[the TP1 TKey Programmer\nboard](https://shop.tillitis.se/products/tkey-dev-kit), and probably a\n[Blinkinlabs CH55x Reset\nController](https://shop-nl.blinkinlabs.com/products/ch55x-reset-controller)\nto use this on real hardware.\n\nBuilding is probably easiest using make and Podman.\n\nTo build everything and then flash the resulting bitstream with the\ndefaultapp in app slot 0 and the partition table copies in one go,\nplace the TKey Unlocked in the TP1, then do:\n\n```\ncd contrib\nmake flash\n```\n\nThis uses the make target `prog_flash` in\n`hw/application_fpga/Makefile` behind the scenes, but mounts your TP1\ndevice into the container.\n\nIf you want to change the default app the TKey uses, change\n`FLASH_APP_0` in the `hw/application_fpga/Makefile`.\n\nTo see all container targets:\n\n```\ncd contrib\nmake\n```\n\nSee the [Tillitis Developer Handbook](https://dev.tillitis.se) for\nmore.\n\n### USB Controller\n\nThe TKey uses a WCH CH552 chip as a USB controller. It has its own\nfirmware.\n\nBuild:\n\n```\ncd contrib\nmake run\ncd hw/usb_interface/ch552_fw\nmake\n```\n\nTo flash the controller with new firmware you need hardware like the\n[Blinkinlabs CH55x Reset\nController](https://shop-nl.blinkinlabs.com/products/ch55x-reset-controller)\nand a USB-A to USB-C converter.\n\n[Reset Controller source](https://github.com/Blinkinlabs/ch55x_programmer).\n\nYou also need [chprog](https://github.com/ole00/chprog).\n\nThe bootloader identifies itself as USB VID 4348, PID 55e0. To be able\nto access it and run `chprog` without root you need to allow your user\nto access it. Place `contrib/99-tillitis.rules` in `/etc/udev/rules.d`\nand run `udevadm control --reload`. Now you can add your user to the\n`dialout` group and access it.\n\n1. Connect the Reset Controller to your computer through \"DUT\\_IN\"/\"PC\".\n2. Connect the TKey to \"DUT\\_OUT\"/\"DUT\".\n3. Press the \"Bootloader\" button.\n4. Run `make flash_patched` in `hw/usb_interface/ch552_fw` outside of\n   a container.\n\n## Updating and working with tkey-libs\n\nA copy of [tkey-libs](https://github.com/tillitis/tkey-libs) is kept\nin `hw/application_fpga/tkey-libs`. This is mostly to avoid the\nsubtleties of Git submodules.\n\nIf you want to change something in tkey-libs, always change in the\nupstream library at:\n\nhttps://github.com/tillitis/tkey-libs\n\nYou can build with an out-of-tree copy if you set `LIBDIR`, for\nexample:\n\n```\nmake LIBDIR=~/git/tkey-libs firmware.elf\n```\n\nWhen it's time to update the in-tree tkey-lib first tag the upstream\nrepo with an `fw` prefix, like `fw-1` even if it already has an\nofficial version tag.\n\nEasiest is probably to just remove the tkey-libs directory and then\ngit clone the desired tag. Use the entire repo, but remove the .-files\nlike `.git`, `.github`, et cetera. Something like:\n\n```\n$ rm -rf tkey-libs\n$ git clone git@github.com:tillitis/tkey-libs.git\n$ cd tkey-libs\n$ git checkout fw-3\n```\n\nNote that you need to change the optimization flag in the tkey-libs'\nMakefile to `-Os`.\n\n## Measured boot\n\nThe key behind guaranteeing security even as a general computer is the\nunconditional measured boot. This means that we have a small,\nunchangeable, trusted firmware in ROM that creates a unique identity\nbefore starting the application. This identity is used as a seed for\nall later cryptographic keys.\n\nWe call this identity the Compound Device Identity (CDI). The CDI is a\ncryptographic mix of:\n\n1. the Unique Device Secret (UDS), a hardware secret, unique per\n   device, something the user *has*,\n2. the hash digest of the TKey device application that has been\n  loaded, the *integrity* of the application, and,\n3. an optional User Supplied Secret (USS), something the user *knows*.\n\nCDI is computed using the BLAKE2s hash function:\n\nCDI = BLAKE2s(UDS, BLAKE2s(application loaded in RAM), USS)\n\nWhen firmware is about to start the device application it changes the\nTKey to a less permissive hardware mode, application mode. In\napplication mode the UDS and the User Supplied Secret are no longer\navailable, but the device application can use the CDI as a seed to\ndeterministically generate any cryptographic keys it needs.\n\n- If the wrong application has been loaded, or the original\n  application has been tampered with, the generated keys will be\n  different.\n- If the USS is not the same, the generated keys will be different.\n- If the same USS and device application is used on a different TKey,\n  the generated keys will be different.\n\nThe TKey unconditional measured boot is inspired by, but not exactly\nthe same as part of [TCG\nDICE](https://trustedcomputinggroup.org/work-groups/dice-architectures/).\n\n# Current Work in Progress in this repository\n\nWe are updating the FPGA and firmware on TKey as part of the Castor\nrelease. This update will simplify TKey’s usage, laying the groundwork\nfor future support of U2F/FIDO authentication.\n\nYou can track our progress through this\n[milestone](https://github.com/tillitis/tillitis-key1/milestone/1).\n\nNote that main branch is in development. We try to keep status of main\nbranch updated in the [release notes](/doc/release_notes.md#upcoming-release-castor).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftillitis%2Ftillitis-key1","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftillitis%2Ftillitis-key1","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftillitis%2Ftillitis-key1/lists"}