smallsolar/u-boot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

tkey: Add a command

Browse Source 
Add a new 'tkey' command that provides an interface to interact with
Tillitis TKey security tokens. Subcommands include:

   - info: Display device information (UDI, name, version, mode)
   - load: Load and run applications on the TKey
   - pubkey: Get the public key from a signer app
   - getkey: Derive disk encryption keys with password and USS

This command enables U-Boot to use TKey devices for secure key
derivation for full-disk encryption.

Co-developed-by: Claude <noreply@anthropic.com>
Signed-off-by: Simon Glass <sjg@chromium.org>
This commit is contained in:
Simon Glass
2025-10-19 03:49:38 +01:00
parent c34b52c8a1
commit b7d758612a
7 changed files with 625 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

247
doc/usage/cmd/tkey.rst Normal file
View File

@@ -0,0 +1,247 @@
.. SPDX-License-Identifier: GPL-2.0+:
.. index::
single: tkey (command)
tkey command
============
Synopsis
--------
::
tkey connect
tkey fwmode
tkey getkey <uss> [verify-hash]
tkey info
tkey loadapp [uss]
tkey signer
tkey wrapkey <password>
Description
-----------
The *tkey* command provides an interface to interact with Tillitis TKey
security tokens. The TKey is a USB security device that can be used for
cryptographic operations, particularly for deriving encryption keys in a
secure and reproducible manner.
The TKey operates in two modes:
Firmware mode
The device starts in this mode after being plugged in. In firmware mode,
the device provides access to its Unique Device Identifier (UDI) and allows
loading applications.
App mode
After an application is loaded, the device enters app mode. The UDI is no
longer accessible, but the loaded app can perform cryptographic operations.
The primary use case is full disk encryption (FDE) key derivation, where the
TKey combines a User-Supplied Secret (USS, typically a password) with its
internal UDI to generate deterministic encryption keys.
tkey connect
~~~~~~~~~~~~
Test connectivity to a TKey device. This command attempts to find and connect
to the first available TKey device in the system.
tkey fwmode
~~~~~~~~~~~
Check whether the TKey device is currently in firmware mode or app mode.
Firmware mode
The device has just been plugged in or reset. The UDI is accessible and
apps can be loaded.
App mode
An application has been loaded and is running. The UDI is not accessible.
tkey getkey
~~~~~~~~~~~
Derive a disk encryption key by loading the embedded signer app with a
User-Supplied Secret (USS). This is the main command for full-disk-encryption
workflows.
The command performs these steps:
#. Loads the embedded signer app with the provided USS
#. Retrieves the public key from the signer app
#. Derives the disk encryption key (BLAKE2b hash of the public key)
#. Computes a verification hash (BLAKE2b hash of the disk key)
The USS is typically a user password or passphrase. The same USS always produces
the same disk encryption key, making this suitable for unlocking encrypted
disks.
If a verification hash is provided as the second argument, the command verifies
that the USS is correct by comparing the computed hash with the expected hash.
This is useful for validating user passwords before attempting to decrypt a
disk.
uss
User-Supplied Secret (password/passphrase) for key derivation
verify-hash
Optional 64-character hex string to verify the USS is correct
The command outputs:
Public Key
32-byte Ed25519 public key derived from USS
Disk Key
32-byte encryption key (BLAKE2b-256 of public key)
Verification Hash
32-byte hash of disk key (save this for later verification)
tkey info
~~~~~~~~~
Display information about the TKey device, including its name, version, and
Unique Device Identifier (UDI).
The UDI is only available in firmware mode. If the device is in app mode, the
command will report that the UDI is not available and suggest replugging the
device.
tkey loadapp
~~~~~~~~~~~~
Load the embedded signer application to the TKey device. This can only be done
when the device is in firmware mode.
An optional USS (User-Supplied Secret) can be provided, which will be used by
the signer app for key derivation. If no USS is provided, the app loads without
a secret.
After loading, the device transitions to app mode and the UDI becomes
inaccessible.
uss
Optional User-Supplied Secret for the signer app
tkey signer
~~~~~~~~~~~
Display information about the embedded signer application binary that is
compiled into U-Boot.
tkey wrapkey
~~~~~~~~~~~~
Derive a wrapping key from a password and the device's UDI. This uses the
BLAKE2b-256 hash function to combine the UDI with the password.
The wrapping key can be used to encrypt/decrypt other secrets. Unlike getkey,
this command does not load an app - it only requires the UDI, so it must be
run in firmware mode.
The same password always produces the same wrapping key for a given device,
but different TKey devices (with different UDIs) will produce different
wrapping keys even with the same password.
password
Password to combine with UDI for key derivation
Example
-------
Connect to device::
=> tkey connect
Connected to TKey device
Check device mode::
=> tkey fwmode
firmware mode
=> tkey loadapp
Loading signer app (a9c bytes)...
=> tkey fwmode
app mode
Get device information (firmware mode)::
=> tkey info
Name0: tk1 Name1: mkdf Version: 4
UDI: a0a1a2a3a4a5a6a7
Get device information (app mode)::
=> tkey info
Name0: tk1 Name1: sign Version: 4
UDI not available - replug device
Derive disk encryption key without verification::
=> tkey getkey mypassword
Public Key: 1a2b3c4d...
Disk Key: 9f8e7d6c...
Verification Hash: 5a4b3c2d...
Derive disk encryption key with verification (correct password)::
=> tkey getkey mypassword 5a4b3c2d1e0f...
Public Key: 1a2b3c4d...
Disk Key: 9f8e7d6c...
password correct
Derive disk encryption key with verification (wrong password)::
=> tkey getkey wrongpassword 5a4b3c2d1e0f...
Public Key: aaaa1111...
Disk Key: bbbb2222...
wrong password
Expected: 5a4b3c2d1e0f...
Got: cccc3333...
Load app without USS::
=> tkey loadapp
Loading signer app (a9c bytes)...
Load app with USS::
=> tkey loadapp mypassword
Loading signer app (a9c bytes) with USS...
Show signer binary information::
=> tkey signer
signer binary: a9c bytes at 0x1234-0x5678
Derive wrapping key from password::
=> tkey wrapkey mypassword
Wrapping Key: 95229cd376898f3fb022a627349dc985bc4675da580d2696bdd6f71f488e306c
Configuration
-------------
The tkey command is available if CONFIG_CMD_TKEY is enabled. The command
requires a TKey driver to be configured (USB or serial).
See also
--------
* `Tillitis TKey documentation <https://tillitis.se/>`_

1
doc/usage/index.rst
View File

@@ -130,6 +130,7 @@ Shell commands
cmd/source
cmd/tcpm
cmd/temperature
cmd/tkey
cmd/tftpput
cmd/trace
cmd/true