9c97e30ef6
Enhance the 'tkey connect' command to allow the device name to be specified. This will be useful in tests. Signed-off-by: Simon Glass <simon.glass@canonical.com>
264 lines
6.5 KiB
ReStructuredText
264 lines
6.5 KiB
ReStructuredText
.. SPDX-License-Identifier: GPL-2.0+:
|
|
|
|
.. index::
|
|
single: tkey (command)
|
|
|
|
tkey command
|
|
============
|
|
|
|
Synopsis
|
|
--------
|
|
|
|
::
|
|
|
|
tkey connect [device-name]
|
|
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 and optionally select a specific device for
|
|
subsequent commands.
|
|
|
|
When called without arguments, this command connects to the first available TKey
|
|
device in the system. When a device name is provided, it connects to that
|
|
specific device.
|
|
|
|
Once connected, the selected device is remembered and will be used by all
|
|
subsequent tkey commands (info, getkey, loadapp, etc.) until a different device
|
|
is selected with another connect command.
|
|
|
|
device-name
|
|
Optional name of a specific TKey device to connect to
|
|
|
|
|
|
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 the first available device::
|
|
|
|
=> tkey connect
|
|
Connected to TKey device
|
|
|
|
Connect to a specific device by name::
|
|
|
|
=> tkey connect tkey@0
|
|
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/>`_
|