mirror of
https://github.com/tillitis/tillitis-key1.git
synced 2025-04-27 10:29:22 -04:00
f87a70b87a
- Use tag fw-3 from https://github.com/tillitis/tkey-libs/ - New tkey-libs also affects testloadapp which means new allowed_app_digest and new default_partition.bin.
148 lines
4.7 KiB
Markdown
148 lines
4.7 KiB
Markdown
[](https://github.com/tillitis/tkey-libs/actions/workflows/ci.yaml)
|
|
|
|
# Device libraries for the Tillitis TKey
|
|
|
|
- C runtime: libcrt0.
|
|
- Common C functions including protocol calls: libcommon.
|
|
- Cryptographic functions: libmonocypher. Based on
|
|
[Monocypher](https://github.com/LoupVaillant/Monocypher) version
|
|
4.0.2
|
|
- BLAKE2s hash function: libblake2s.
|
|
|
|
Release notes in [RELEASE.md](RELEASE.md).
|
|
|
|
## Licenses
|
|
|
|
Unless otherwise noted, the project sources are copyright Tillitis AB,
|
|
licensed under the terms and conditions of the "BSD-2-Clause" license.
|
|
See [LICENSE](LICENSE) for the full license text.
|
|
|
|
Until Oct 8, 2024, the license was GPL-2.0 Only.
|
|
|
|
External source code we have imported are isolated in their own
|
|
directories. They may be released under other licenses. This is noted
|
|
with a similar `LICENSE` file in every directory containing imported
|
|
sources.
|
|
|
|
Imported sources:
|
|
|
|
- [Monocypher](https://github.com/LoupVaillant/Monocypher) (BSD-2) by
|
|
Loup Vaillant.
|
|
|
|
- blake2s (CC-0), originally based on the reference implementation in
|
|
[RFC 7693](https://www.rfc-editor.org/rfc/rfc7693.html) written by
|
|
Markku-Juhani O. Saarinen ([original
|
|
repository](https://github.com/mjosaarinen/blake2_mjosref). Imported
|
|
from [Joachim Strömbergson's
|
|
fork](https://github.com/secworks/blake2s/) used as a model for a
|
|
hardware implementation.
|
|
|
|
### SPDX tags
|
|
|
|
The project uses single-line references to Unique License Identifiers
|
|
as defined by the Linux Foundation's [SPDX project](https://spdx.org/)
|
|
on its own source files, but not necessarily imported files. The line
|
|
in each individual source file identifies the license applicable to
|
|
that file.
|
|
|
|
The current set of valid, predefined SPDX identifiers can be found on
|
|
the SPDX License List at:
|
|
|
|
https://spdx.org/licenses/
|
|
|
|
We attempt to follow the [REUSE
|
|
specification](https://reuse.software/).
|
|
|
|
## Hardware support
|
|
|
|
### Bellatrix and earlier
|
|
|
|
Please note that:
|
|
|
|
- For reading, only use the blocking `uart_read()`.
|
|
|
|
- Only `IO_UART` and `IO_QEMU` destinations are useful for writing as
|
|
in `write(IO_UART, ...)`, `puts(IO_UART, ...)`, and so on.
|
|
|
|
- Defining `QEMU_DEBUG` works with all the `debug_*` functions, but
|
|
`TKEY_DEBUG` does not.
|
|
|
|
## Building
|
|
|
|
In order to build, you must have the `make`, `clang`, `llvm`, and
|
|
`lld` packages installed.
|
|
|
|
Version 15 or higher of LLVM/Clang is necessary for the RV32IC\_Zmmul
|
|
architecture we are using. For more detailed information on the
|
|
supported build and development environment, please refer to the
|
|
[Developer Handbook](https://dev.tillitis.se/).
|
|
## Building using Podman
|
|
|
|
You can also build the libraries with our OCI image
|
|
`ghcr.io/tillitis/tkey-builder`.
|
|
|
|
The easiest way to build this is if you have `make` installed:
|
|
|
|
```
|
|
make podman
|
|
```
|
|
|
|
You can also specify a different image by using
|
|
`IMAGE=localhost/tkey-builder-local`.
|
|
|
|
Or use Podman directly:
|
|
|
|
```
|
|
podman run --rm --mount type=bind,source=.,target=/src -w /src -it ghcr.io/tillitis/tkey-builder:4 make -j
|
|
```
|
|
|
|
## Minimal application build
|
|
|
|
You will typically need to link at least the `libcrt0` C runtime
|
|
otherwise your program won't even reach `main()`.
|
|
|
|
We provide a linker script in `apps.lds` which shows the linker the
|
|
memory layout.
|
|
|
|
Minimal compilation would look something like:
|
|
|
|
```
|
|
clang -target riscv32-unknown-none-elf -march=rv32iczmmul -mabi=ilp32 \
|
|
-mcmodel=medany -static -std=gnu99 -O2 -ffast-math -fno-common \
|
|
-fno-builtin-printf -fno-builtin-putchar -nostdlib -mno-relax -flto \
|
|
-Wall -Werror=implicit-function-declaration \
|
|
-I ../tkey-libs/include \
|
|
-I ../tkey-libs -c -o foo.o foo.c
|
|
|
|
clang -target riscv32-unknown-none-elf -march=rv32iczmmul -mabi=ilp32 \
|
|
-mcmodel=medany -static -ffast-math -fno-common -nostdlib \
|
|
-T ../tkey-libs/app.lds \
|
|
-L ../tkey-libs -lcrt0 \
|
|
-I ../tkey-libs -o foo.elf foo.o
|
|
|
|
```
|
|
|
|
## Makefile example
|
|
|
|
See `example-app/Makefile` for an example Makefile for a simple device
|
|
application.
|
|
|
|
## Debug output
|
|
|
|
If you want to have debug prints in your program you can use the
|
|
`debug_putchar()`, `debug_puts()`, `debug_putinthex()`,
|
|
`debug_hexdump()` and friends. See `include/tkey/debug.h` for list of
|
|
functions.
|
|
|
|
These functions will be turned on if you define either of these when
|
|
compiling your program and linking with `libcommon`:
|
|
|
|
- `QEMU_DEBUG`: Uses the special debug port only available in qemu to
|
|
print to the qemu console.
|
|
- `TKEY_DEBUG`: Uses the extra HID device.
|
|
|
|
Note that if you use `TKEY_DEBUG` you *must* have something listening
|
|
on the corresponding HID device. It's usually the last HID device
|
|
created. On Linux, for instance, this means the last reported hidraw
|
|
in `dmesg` is the one you should do `cat /dev/hidrawX` on.
|