Trusted display
Experimental. An RS-Key variant for a screen-and-touch RP2350 board (the reference target is the Waveshare RP2350-Touch-LCD-2.8). The screen turns the key into a trusted display: the operations that matter (approving a sign-in, typing a PIN) happen on the device’s own glass, not on the host. A compromised or phishing host cannot fake what you see or capture what you type. Concretely:
- An Approve / Deny prompt paints the real relying party for every
signature. A signature cannot be obtained without a physical tap on a screen
showing the true
rpId. - PINs are entered on-screen (a FIDO
clientPIN/UV, a device PIN, and the OpenPGP / PIV PINs over CCID) and never cross USB. - An on-device browser lets you inspect and prune credentials (delete a passkey, read the applet state) without a host.
The whole feature is dep:-gated. A standard key without a screen compiles
none of the UI or driver code (the gate asserts the rsk-ui crate is absent
from the default firmware image), so an ordinary build is byte-for-byte
unaffected.
The full GUI uses always-on antialiasing. Text uses four-bit IBM Plex Sans and Mono coverage data. Icons, circles, status rings, rounded cards, and controls blend their edges into the surface below them. The device does this with integer geometry even for controls narrower than their rounded corners. It uses retained panel writes without a framebuffer or a heap. A full page is recorded once as compact drawing commands. The firmware compares keyed 128-bit tags for 32×32 visual-state tiles and merges the changed tiles. Typed UI components can provide smaller exact damage before composition. Each changed rectangle uses two 8-row RGB565 buffers while PIO DMA sends the other buffer. Common background rows are copied from raster templates in flash instead of being generated for every band. The buffers use the active stack and do not reduce permanent RAM. RLE checkpoints and a vertical command index let each band start at its own data. One panel address window stays open for each rectangle. Small animations still use direct partial redraws, and there is no antialiasing setting to manage. A scene or SPI failure stops UI input before an incomplete prompt can stay active.
The display build runs the RP2350 at 160 MHz. A TX-only PIO program emits one serial bit every two cycles, for an 80 MHz panel clock. A complete 240×320 RGB565 transfer has a 15.36 ms wire-time floor. Both of those numbers are past what the parts are rated for — the RP2350 is specified to 150 MHz and this project had recorded 62.5 MHz as the ST7789’s write ceiling — so what that costs, and which of this repo’s measurements stop covering this flavor, is written down in limitations.md. A key without a screen sets no clock and is unaffected.
Try it without a board
The screens on this page are not photographs — they are what rsk_ui::render
draws, at the panel’s own 240×320. The same renderer runs in a window:
cargo run --manifest-path tools/emu/Cargo.toml --target "$HOST" -- --display
That is the whole flow, not a viewer. The ambient loop, the Approve/Deny hold,
the on-screen PIN pad and the Settings menu are the code the board runs
(crates/rsk-display); a mouse held on a button enters it through the same
TouchPad a finger does, and the power button is the space bar. So the ceremony
this page is about — a signature cannot be had without a tap on a screen naming
the true relying party — can be tried before deciding whether to buy the
hardware.
--taps <file> replaces the mouse with a script — one contact per line,
x,y[,hold_ms[,gap_ms]] in panel pixels, # for a comment — so a sequence that
takes six taps to reach can be replayed instead of performed:
# Settings → Security → FIDO PIN
209,301
119,123
119,123
The images themselves are regenerated with rsk-emu --screenshots docs/images
when a screen changes.
To run the compiled firmware itself, build the ordinary display image below,
then launch it with rsk-emu --image target/trustzone/combined.elf --display.
The window shows pixels captured from the firmware’s PIO serial output. Mouse
contacts become CST328 or CST3530 I2C reports; Space drives the board’s wake GPIO. Add
--headless for scripted runs. In image mode, tap-script hold and gap durations
follow the emulated clock, so a slow host cannot turn a short contact into a
long approval hold. See display image testing
for the runner and its limits.
This exercises firmware instructions, rendering and USB framing against models of the panel and touch controller. Physical display timing, electrical I2C behaviour and touch calibration still require the board.
Building and flashing
Use the package for your board revision. Both use the same ST7789 display, but their touch controllers have different I²C addresses and register maps. With the wrong image the screen draws normally and touches do not register.
| Board revision | Touch controller | I²C address | Nix package |
|---|---|---|---|
| V1 | CST328 | 0x1A | firmware-display |
| V2 | CST3530 | 0x58 | firmware-display-v2 |
Check the board silkscreen or the controller address to identify the revision. Waveshare board specifications
nix build .#firmware-display # V1 → result/firmware-display.uf2
nix build .#firmware-display-v2 # V2 → result/firmware-display-v2.uf2
# Build V2 from source with the TrustZone builder.
nix develop -c env BOARD=waveshare-touch-lcd DISPLAY_TP_CHIP=cst3530 \
bash scripts/build.sh --features display
The source build writes target/trustzone/combined.uf2. Omit
DISPLAY_TP_CHIP=cst3530 for V1. The board preset selects 16 MiB of flash
and disables the addressable LED, freeing GPIO16 for the backlight.
The board’s BAT_PWR button (GPIO25 by default) wakes and sleeps the panel.
Sleeping blanks the screen, locks the on-device UI when a device PIN is set,
and aborts any interrupted host prompt. See Build options for
WAKE_PIN and WAKE_ACTIVE_HIGH.
Flash it like any other image (BOOTSEL → picotool load, hardware.md).
Two notes:
- The build output is unsigned. On a secure-boot device you still
picotool seal --signit before loading (signing-keys.md, anti-rollback.md). The RP2350 boot ROM verifies the signature on boot. - You can reach BOOTSEL from the panel itself: Settings → Firmware → reboot to BOOTSEL (a deliberate hold). The reboot routes through the worker so live RAM secrets are scrubbed first.
What’s on screen
A bottom navigation bar carries four peer tabs, each captioned:
| Tab | What it shows |
|---|---|
| Home | A calm “Ready” and a status card: USB, whether a device PIN is set, and the resident-passkey count (cached, refreshed only at modal boundaries). |
| Passkeys | The resident credentials, one row per relying party. |
| Apps | A read-only browser for the OpenPGP / PIV / OATH applets. |
| Settings | Display, Security, Firmware, Audit log, Backup, Factory reset. |
Approve / Deny — the anti-phishing core
Any operation that needs user presence paints a trusted prompt naming the operation and the real relying party, and waits for a deliberate action:
- A WebAuthn registration shows a Save new passkey? card (relying party + account, Cancel / Save).
- A sign-in and the generic OpenPGP / PIV touch prompts share an approve
screen (shield + relying party + a hold-to-approve button). Deny refuses
with
OPERATION_DENIED.
Every prompt waits for the previous finger to lift before it will accept a tap, and a prompt that runs out of time is denied rather than approved — a finger resting on Save when the window expires cancels the registration, it does not confirm it. The release wait has a floor of its own, so shortening the presence timeout in the device config cannot shrink it away.
Because the device only knows the relying-party string (and its hash), it
shows that string verbatim, never a host-supplied brand logo. A relying-party id
too long for the box is clipped with a truncation marker, and the clip keeps
the registrable-domain suffix (a leading … ellipsis) rather than the head.
So a padded look-alike such as accounts.google.com.attacker.com can never hide
its real domain (…attacker.com) behind the cut.
This holds on every screen that
shows an attacker-chosen rpId: the approve and enrollment prompts and the
Passkeys manager’s list, service-detail title and Confirm-Delete card. A
device-local nickname (which you set, not the host) keeps its head instead.
Entering a PIN on the trusted screen
The panel has an on-screen numeric PIN pad: digits are masked, an eye toggle reveals them briefly so you can check before committing, and the minimum length shows as placeholder dots. Every PIN screen names which credential it is collecting in the header (Device PIN, FIDO PIN, PIV PIN / PIV PUK, or the OpenPGP PINs), so the independent PINs are never confused. The New / Confirm / current step rides in the caption beneath. The PIN never leaves the device.
Whichever way the PIN arrives — typed on the pad or sent by the host — the panel asks
before a pinUvAuthToken is issued (CTAP 2.1 §6.5.5.7 requires the consent on any
authenticator with a display). Declining ends the operation with OPERATION_DENIED
and costs no PIN retry, since the question comes before the PIN is checked. So
ykman fido and anything else needing a token waits on a tap here.
This backs four things:
- Built-in user verification. getInfo advertises
options.uv. A PIN typed on the pad mints apinUvAuthTokenviaclientPIN(getPinUvAuthTokenUsingUvWithPermissions), checked against the sameEF_PINthe hostclientPINpath uses. A platform can also skip the token:makeCredential/getAssertioncarryingoptions: {uv: true}collect the PIN on the pad directly (CTAP 2.1 §6.1.2 step 11.2), and that entry counts as the ceremony’s user presence, so the response setsupwithout the spec requiring a second gesture. The panel still asks: pad first, then the Approve / Deny card, because that card is the only screen naming the relying party — the pad carries a trusted, firmware-supplied title and never relying-party text. WithalwaysUvon, a request that brings nopinUvAuthParamtakes the same route instead of being refused withPUAT_REQUIRED. Declining on the pad ends the operation withOPERATION_DENIED— deliberately, since the code CTAP would have the device send instead (PUAT_REQUIRED) asks the host to prompt for the same PIN, which would make the refusal meaningless. A wrong PIN still falls back to the host path. - CCID secure PIN entry (pinpad). A display build advertises
bPINSupportand handlesPC_to_RDR_Secure, so GnuPG (OpenPGP PW1/PW3) and OpenSC (PIV PIN) collect the PIN on the trusted screen. The PIN never crosses USB in pinpad mode. Details and host-driver caveats: protocol.md §1.3. - U2F under alwaysUv. A screenless key has to switch CTAP1/U2F off once
alwaysUvis on, since a touch proves no verification. A pad with a PIN set is the exception CTAP 2.1 §7.2.4 allows, so U2F keeps working here — each register and authenticate names itself on screen (Register key? / Sign in?) and then collects the PIN on the panel. TurningalwaysUvon before setting a PIN still disables it; there would be nothing to verify against. - First-run onboarding. A fresh, PIN-less device offers a Set a PIN? screen
at first run. Declining is remembered (a flag in
EF_DISPLAY) so the offer isn’t repeated until a factory reset.
Passkeys
The Passkeys tab lists resident credentials by relying party (real rpId +
account count) and drills into a per-account detail where a passkey can be
deleted on-device (gated by the device PIN, then a hold), decrypted on the
device, never on the host. The detail’s pencil opens a character-wheel rename
that sets a short device-local nickname for the relying party, shown in place
of its rpId. The nickname is sealed at rest (a dedicated EF_RPNICK region),
wiped by a reset, and (unlike a host updateUserInformation) never re-seals the
credential, so the passkey keeps working. The trade-off: the nickname is
device-local and not seen by host credential managers.
Apps — a read-only credential browser
The Apps tab reads applet state without a PIN. No key material, PIN or public point is ever shown, and no OATH code is computed (the device has no clock).
- OpenPGP: the Signature / Encryption / Authentication slots with each one’s algorithm, the signature counter and PW1/PW3 attempts; a per-slot detail with the SHA-1 fingerprint and touch policy; and a Card holder row (name / login / URL / language).
- PIV: the 9A/9C/9D/9E slots with algorithm and PIN/PUK attempts, a per-slot
detail (PIN/touch policy, key origin, cert presence), and a Retired & F9 row
listing the populated retired key-management slots (82–95) and F9. From it,
Generate key creates a key (EC P-256/P-384, Ed25519, X25519, or RSA
2048/3072/4096) into the next free retired slot, gated by the device PIN and
a hold, restricted to empty slots (add-only, never overwrite). It writes the key
alone, as a host generate does; make its certificate from the host. A slot whose key
was moved or deleted still holds its certificate, so it is not free until that
certificate is deleted (
ykman piv certificates delete 82). There is no management-key auth: physical presence at the panel is the authorisation. - OATH: the stored credentials (label, TOTP/HOTP, a padlock when touch-gated), each with a detail (type, HMAC algorithm, digits, TOTP step).
Settings
Grouped into three domains, plus the journal / backup / reset actions:
- Display: backlight brightness (PWM), the display-sleep timeout, and the
touch timeout, each adjusted live. All three persist across reboots:
brightness and sleep in an
EF_DISPLAYflash record; the touch timeout inEF_PHY’sPresenceTimeout, the same fieldrsk hw --touch-timeoutwrites, so the panel and the host tool stay in sync. A configuration lock shuts the host tool’s write and not the panel’s, which no host can reach. - Security: set / change the device PIN and the FIDO clientPIN (each
chosen entirely on the panel). Changing the clientPIN asks for the current one
first, and that prompt is the card’s
changePINcheck: a wrong entry spends a retry and ends anypinUvAuthTokena plugged-in platform holds, exactly as a wrong old PIN sent over USB does — the platform just asks for the PIN again. Then a PIV PIN sub-menu: change the PIV PIN, change the PUK, unblock a blocked PIN with the PUK, or protect the management key. Protect mgmt key generates a random AES-256 management key, seals it and marks it PIN-protected, the ykman--protectscheme, so a host then uses the management key with just the PIV PIN (which alone grants management access, a trade-off the panel states and gates behind the device PIN and a hold). Any existing hostPivmanData(its PIN-change timestamp and other flags) is preserved (the obsolete derived-key salt is dropped, exactly as ykman does). Last on the page, Scramble PIN pad — a toggle, off by default. On, the ten digit keys are laid out afresh at random for every PIN entry (and again between the “New PIN” and “Confirm PIN” steps), so a fingerprint trail, a worn patch of glass, or an onlooker who sees your hand but not the panel learns nothing from where you tapped. It buys nothing against anyone who can see the screen — they read the digits off it — and it costs muscle memory: entry is slower and mistyping is likelier, against a limit of three wrong PINs per power cycle. That trade is the owner’s to make, which is why it ships off. - Firmware: the installed
bcdDevicebuild and chip serial, the real OTP secure-boot fuse state (it warns when secure boot is off rather than claiming a check it isn’t doing), and the hold-to-reboot into BOOTSEL for an over-USB update.
- Audit log: the most recent device-journal events (sign-ins, passkeys added, PIN changes, lockouts, resets, power cycles), colour-coded, newest first.
- Backup. An honest view of the recovery-seed export window: whether a
seed is present and whether its one-time export has been sealed. While the
window is open, Show recovery (gated by the device PIN) paints a 24-word
BIP-39 phrase or a
T-of-NSLIP-39 share set on the trusted screen, derived on the device, never crossing USB, behind a hold + warning, wiped the instant they’re shown. Seal backup closes the window for good (until a factory reset). See seed-backup.md.
- Factory reset: erases every applet’s data (FIDO, PIV, OpenPGP, OATH), scrubs the flash, and reboots to a blank device (gated by the device PIN, then a hold). Only the org attestation and the fused OTP / secure-boot state survive.
A display build is also exempt from the power-up window
that makes a screenless key refuse a host authenticatorReset more than ten
seconds after it was plugged in. That window exists to stop a wipe being approved
by a press collected under some other pretext; here the panel names the operation,
so a host reset is accepted whenever you confirm it on screen — no replug.
Security model
The device PIN (EF_DEVICE_PIN, its own sealed record + retry counter) gates the
on-device UI (unlock, on-device delete, factory reset) independently of FIDO.
The device boot-locks when a device PIN is set. A forgotten device PIN is
cleared only by a host authenticatorReset (the sole recovery, since the lock
gates on-device Settings). Every device-driven ceremony (a granted Approve, an
on-device delete, a factory wipe) ends on a brief success confirmation.
This is an experimental variant. Read threat-model.md and limitations.md for what the trusted display does and does not defend against.
See also
- Build options: the
displayfeature and its knobs. - Hardware: boards and flashing.
- Host protocol §1.3: CCID pinpad secure PIN entry.
- FIDO2 / WebAuthn · PIV · OpenPGP · Seed backup.