The templates live on the persist partition and survive a reflash; the
finger-name map lives on the rootfs and does not. A reflashed phone comes
back with the trustlet holding every template it had and the daemon
knowing none of them by name -- and with five of them the group is full, so
every enrolment from Settings answered -207 "Up to the limit" (fennek182,
2026-10-13). No D-Bus client could get out of that: the list answered from
the map, delete removed only the fids the map knew, and ENUMERATE was sent
with an empty payload and read for its count alone.
A finger re-enrolled under its old name produced the same state one
template at a time: the map took the new fid and the old template stayed
in its slot.
ENUMERATE now asks with room for every slot the group can hold, and the
reply names the templates: one 8-byte entry per loaded one, its fid in the
second word. Verified live: the three fids the map names came back among
the four listed. With the list in hand:
- An enrolment removes the templates no name accounts for before ENROLL.
They can match nothing (a verify filters on the map's fids, standby
arms from them), and each is a slot the enrolment may need or the
duplicate the trustlet would refuse it for.
- Deleting every finger deletes them too, and the job is posted even
when the map is empty, which after a reflash it is.
- Re-enrolling a finger drops its name at EnrollStart, so the old
template is unnamed and goes under the first rule. The trustlet forces
the order: with duplicate checking on, a re-enrolment of a finger it
still holds does not complete (2026-09-04: one attempt 0 accepted of 7
presses, another stalled at sample 8 of 20).
- The claim log counts them: "4 template(s) loaded, 1 of them unnamed".
The map now decides what an enrolment keeps, so the Store module says so,
and three rules keep that from turning a damaged map into lost templates.
A line the decoder cannot use -- a typo in a hand rebuild, a finger named
twice -- makes the map untrusted, and no enrolment removes anything on its
account. A line it cannot read at all is written back, word for word, by
every save but a delete of every finger, so the distrust outlasts the next
enrolment; a line it can read but not seat, the repeated name or a sixth
finger, is kept as the finger and fid it names and goes with that finger's
delete, template included, instead of coming back as the finger's name;
and the finger named twice now answers to its FIRST line, where before
the last line's fid replaced the earlier one's. A file that will not open
or read, for any reason but its absence, refuses
enrolment and deletion outright and is never written over. And the map is
written with GLib's g_file_set_contents_full under its consistent and
durable flags, and a save that did not land is reported: the old map
stays, a re-enrolment whose name drop did not land is refused with the
name put back, a delete whose save did not land removes nothing, and an
enrolment whose name did not land is reported to the client as failed,
not completed. Of the daemon's own paths, deleting every finger is the
one removal of unnamed templates on the user's word rather than the
map's: in a managed group it takes every template, named or not. A delete is refused while the
claimant's enrolment or verify for that user is in progress, because the
running job's keep-list came from the claim's map; a standby verify for
that user is stopped and the delete goes ahead. Group 0 is never tidied:
every daemon path that removes a template the map does not name, and the
name drop before a re-enrolment, asks one predicate, and it says no for
group 0 -- root's,
which no session user is, and the group a stock Android install's primary
user also writes. Root re-enrolling a finger behaves as it did before.
The --probe-remove diagnostic removes the fid it is given in any group,
with no map involved, as before.
A result belongs to the operation that asked for it. EnrollStart and
VerifyStart number the operation, the job and every event it posts carry
the number, and a Stop or the claim's end clears it: a job still queued
under a cleared number exits at dequeue instead of running an operation
nobody wants, and a result still in flight is neither named nor reported
-- its template, unnamed, goes with the group's next enrolment. Without
this, a stop followed by a new start could name a late result under the
new finger and remove the just-saved template as unnamed. An enrolment is
also refused before anything changes when the store is read-only, and the
claim's map is re-read from disk at every EnrollStart, so a file rebuilt
by hand under a held claim counts.
The probe passes the loaded list as the named one. A diagnostic does not
tidy the group it is probing. fplearn.sh's header no longer says that
re-enrolment adds a template with no trustlet-side remove, and its `enrol`
refusal gives the protocol's own reason (a template with no history)
instead of the trustlet's duplicate refusal.
Tested on the dev phone. An earlier build of this change, before the
shared predicate and the damaged-map rule, removed the phone's one stray
template at an EnrollStart for a finger not in the map (fid 1313616972,
8 -> 6 containers), reloaded the group as the three named ones, got rc=0
from ENROLL and cancelled cleanly. A build of this series then ran the
same claim and EnrollStart on the group it left behind: three loaded, none
unnamed, nothing removed, ENROLL rc=0, cancelled cleanly. The build of this
series' tip then enrolled a fourth finger to completion (20 samples
accepted, one refused), which the map saved and listed, and deleted it
again under the same claim: its template removed, the group and the map
back to the three they started with.
FF_CMD_TA_REMOVE, recovered the way AUTHENTICATE was: read the stub, read the
handler. The 0x2006 stub at 0xa15c is a bare `ldp w0, w1, [payload]`, so the
request is two u32s -- gid at +0, fid at +4 -- and the 0x2000 dispatcher
validates no length. Walking the jump table reproduces authenticate at 0xa180,
which is the address already on record, so the table read is sound.
Three preconditions, all the trustlet's own. The gid must be the ACTIVE group
(it compares against device+0x30, the field SET_ACTIVE_GROUP writes). The fid
must be non-zero: zero is not "remove all", it is an error the trustlet logs
and refuses. And the fid must be among the loaded templates, because it
removes by the SLOT INDEX it finds, not by id.
It persists: on a hit the trustlet formats ff_template_<gid>_<slot>.bin and
calls ff_file_delete, which arrives on our gpfile listener as an unlink -- so
this only works with the store served writable.
Proven harmlessly first. --probe-remove sends one command with no map
involvement, and a fid the group does not hold answers rc=-2 with the real
template untouched -- which is what established that both words are read where
we send them, before anything was deleted.
Then for real, through fprintd-delete: both 347202-byte containers and their
.bak companions unlinked, templates loaded 1 -> 0, and a re-enrolment
afterwards completed 20 stages with SAVE_DATA rc=0, so the store is consistent
after a removal rather than merely emptier.
The ordering the transcript shows is worth keeping: the group index is
rewritten and the RPMB anti-rollback counter bumped BEFORE each unlink. That
is precisely why an orderly removal leaves a valid store where restoring an
older container leaves a tampered one -- the counter has already moved past
it.
The delete reply now waits for the worker, because only that thread invokes
the trustlet and fprintd's Delete methods are synchronous. Names are dropped
before templates on purpose: a template that survives a failed removal is a
slot leak, while a name that survives a successful one keeps offering a finger
that can no longer match.
Stock rewrites the stored template on every successful press. Its post-match
loop is QUERY_FINGER_STATUS, CAPTURE_IMAGE, 0x1015 UPDATE_TEMPLATE while the
finger stays down, with no REPORT_EVENT in it -- so the matcher does not re-run
and the verdict cannot change. Forty-six of those against eighty-six captures in
one reference session, and the stored body measurably grows: 333278 bytes at
enrolment, 360822 at the next session's load, 371734 after one authentication
session. This daemon sent none of them.
The command shares REPORT_EVENT's event context. The stock wrapper memsets 732
bytes and writes six fields: a zero byte at +0x2a4, the scan-slot count, a zero
word, the count of frames folded so far in this press, a flags word of
0x00080000 with bit 6 set on the frame whose event was FingerTouched, and a zero
at +0x2d8. Declared length 0x2dc.
+0x2d8 is the one that matters, and it matters by staying zero. The dispatcher
stub reads it after the handler returns and only if it is non-zero does it read
+0x2dc and make that the response length. Every earlier attempt in this project
set both fields and varied the declared length across 0x2e0, 0x400 and 0x1000;
all of them answered -90, the trustlet gone, and the conclusion recorded was
"do not retry until a template is loaded". A loaded template was necessary but
not sufficient. The stock HAL sets neither field.
Measured on the device with two templates loaded and no finger: both branches
answer rc=0 and ENUMERATE still reports 2, so the app did not fault.
Those fields are little endian, assembled low-address-first by the handler. An
earlier reading called them big endian, off the bfi order, and was wrong.
Bit 6 selects which algorithm entry runs: clear takes libfp_template_x_update,
set takes the other, which also reads the scan-slot count.
Enrolment is the first thing here that writes: template containers through the
gpfile listener and counter records through RPMB. It refuses to run unless both
--sfs-writable and --rpmb-write are given, and it refuses to call SAVE_DATA if
the sample count did not reach zero, because a partial template is worse than
none.
The sequence is stock's: cancel, reset-lockout, authenticate, cancel,
reset-lockout, PRE_ENROLL, authenticate, cancel, ENROLL, the sample loop,
POST_ENROLL, SAVE_DATA with bit 30 set. AUTHENTICATE is what arms the capture
session, which is why it appears in an enrolment at all.
Enrolment takes one sample per PRESS: touch on the rising edge, release on the
falling one, nothing in between. Stock's entire enrolment trace contains no
image-ready event, and feeding every held frame gives the algorithm
near-duplicate images from a single press.
Two things named honestly. The ENROLL payload's u32 at +69 was recorded here as
a "timeout"; the trustlet reports it back as the GROUP ID, and filling a
mislabelled field with a plausible number is the entire provenance of gid 60.
It is the gid now, so an enrolment can choose its own group.
And --group-path exposes the namespace key the trustlet hashes into the group's
directory name. It defaults to Android's, which is where this device's existing
store lives and how that template is readable. But SAVE_DATA rewrites the
group's index container, and an index QTEE later fails to verify takes every
template listed in it -- so enrolling into a DIFFERENT namespace is complete
isolation from a store we did not write.
Arms a scan session and drives the frame loop: capture, decide finger from the
calibrated floor, report the touch edges, classify the verdict.
It needs no writes of any kind -- no SAVE_DATA, no RPMB write, no SFS write --
so it runs safely against an existing template with the store read-only. That
is what makes it the right thing to try before enrolment rather than after.
Verified armed on the phone: the template loads, the floor calibrates, and
AUTHENTICATE returns rc=0, which also proves the gid agrees with the one
SET_ACTIVE_GROUP used (a mismatch answers -200). With no finger present the
loop correctly reports nothing: no touch edge, no event, no terminal frame.
The fid field is poisoned before every REPORT_EVENT, because a zero-initialised
buffer cannot distinguish "the matcher never ran" from "the matcher ran and
rejected" -- the failure path writes zero there too.
The tally reports terminal frames as the denominator and presses separately,
so a run cannot be read as having rejections it did not have.
The whole storage path now works from the daemon. On the phone, against the
real store:
listener 0x7000 sb=516096 -> result=0 REGISTERED
listener 0x2000 sb=25600 -> result=0 REGISTERED
SET_ACTIVE_GROUP gid=60 path='/data/vendor_de/0/fpdata'
gpfile READ .../1lPrxAL0vXRvWPeDkW2c off=4096 len=252114
...
CMD 0x2005 -> result=0 rc=1
templates loaded: 1
QTEE read a 252114-byte enrolled template through our gpfile listener, verified
it, and loaded it. Since QTEE unlinks any container whose keyed integrity tag
fails, a load is proof the framing is right -- the read/write offset split, the
container chunking, and the RPMB anti-rollback read that has to succeed before
QTEE will trust any of it.
RPMB is served too: SECURITY PROTOCOL IN/OUT against the RPMB well-known LUN,
retrying the unit attention the LUN raises once after a reset. Writes are
refused unless asked for, because they advance a counter that cannot be moved
back, and key programming is refused unconditionally.
The store was served READ-ONLY throughout, which is the point. A listener that
serves bytes at the wrong offset does not merely fail: QTEE deletes the
container it cannot verify, and that is an enrolled fingerprint gone. Read-only
makes a wrong build harmless, so it is the default and writing is opt-in.
Two ordering facts, both of which produce -2 with no storage read at all --
indistinguishable from a broken listener:
* a template reload needs the device init chain to have run FIRST, because
that chain allocates the per-slot array the reload writes through;
* SET_ACTIVE_GROUP's second field is a NAMESPACE path, not a filesystem one
and not the gid again. The trustlet hashes it into the group's directory
name, so it has to match what the store was written under.
Also: a positive rc is not an error code. ENUMERATE returns the template count
there, and running that through the error table printed "unknown" for a good
answer.
The finger-free path is complete. On the phone, from a cold start:
client env -> loader -> trustlet -> config -> sensor rail -> init chain
calibrating the idle floor (5 samples)
idle 1/5: rc=-11 metric=133
...
idle floor = 133, finger threshold = 266
133 is the number the journal records for this sensor, so the port reproduces
the reference measurement rather than merely producing one.
Two things had to be right at once, and the first attempt had neither.
The memory region: CAPTURE_IMAGE reads an output-buffer pointer out of
payload+0x00, and QTEE only patches an address there if the location is named
in embeddedBufOffsets and the region handed over in an object slot. The
instrumented dump shows it working -- payload+0x00 came back holding
0x088db98000 -- which is what made the remaining failure legible instead of
mysterious.
And two fields inside the capture payload that an all-zero request leaves
unset: a frame count at +0x0c and a branch selector at +0x10. Selector 0
returns metric 0. Sending zeros gets -201 with the region correctly attached,
which reads exactly like a broken region and is not one. They are named
constants now, with the note that the metric is PER FRAME so a threshold
calibrated at one frame count means nothing at another.
The flags word at payload+0x18 stays past the declared length of 0x14 on
purpose: the trustlet range-checks that length to exactly 0x14 and reads the
flags anyway.
--verbose keeps the region and reqOut dumps, which is what turned this from
guesswork into reading.
On the phone, end to end from the daemon:
lookupTA('focal64') -> result=23 (nothing to unload)
trustlet loaded from /lib/firmware/focal64.mbn, distName='fingerprint'
config /lib/firmware/fingerprintd.json: 349 bytes
CMD 0x100d -> result=0 rc=0 (Success)
CMD 0x2005 -> result=0 rc=0 (Success)
The config is the one fp6fpcfg.py --daemon generates, so the reduction of nine
hand-edited ffcfg files to one generator is confirmed against the trustlet
rather than only against the files it replaced.
A stale instance is unloaded before loading, which is what stops a crashed
experiment costing a reboot; result=23 is the clean-slate answer.
The request envelope moves into Fingerprintd:Ta with the rest of the layouts:
command id at +0, declared length at +4, payload at +0x10, and on the way back
the trustlet's own rc at +8 and the capture metric at +0x0c. Both are HEADER
fields ahead of the payload -- the metric has been miscalled "payload+12" in
this project's notes, and every recorded finger number depends on reading it
where it actually is.
ENUMERATE answering rc=0 is correct here and not a regression: no group is
active and no storage listeners are registered yet, so there are no templates
to count.
Fingerprintd:Ta is the second core module: request payloads, response fields,
the error table, and the rule that decides what a frame meant. Payload building
and response reading only -- no TEE, no transport.
Very little of this is guessable, so each constant carries where it came from.
Three were found only because QTEE recorded a fault naming the instruction that
read them:
* the event context's scan-slot count at +712, which do_enroll branches on to
skip the entire slot loop -- an all-zero payload logged "groups->,
results->" and read exactly like a gate failing deep in the trustlet, when
it was zero iterations;
* CAPTURE_IMAGE's flags at payload+0x18, without which preprocessing, the
classifier and the enrol grouper never run at all, whatever is on the
sensor;
* SYNC_STATISTICS, whose absence leaves g_statistics NULL so the first enrol
frame that gets far enough takes a data abort and every later command
answers -90.
The verdict rule gets the most attention because it was mislabelled three times
before the comparison producing it was read. A frame is one of three things and
only the third is a verdict: the poison intact means the matcher never ran,
rc=-11 means not identified yet with attempts remaining, and only rc=0 carries
a match or a rejection. The poison exists because a zero-initialised buffer
cannot tell a released finger from a rejected one.
The tests are in two halves that cannot prop each other up. Explicit wire
conditions pin the classifier; three recorded runs pin the counting policy,
which is what actually went wrong. In the stock-budget run 31 of 48 frames
answered "not identified yet" and every frame that carried an image matched --
counting those 31 as attempts turns 8-for-8 into 8-of-39 and reads as a flaky
sensor. The wrong-finger control pins zero false accepts.
Fixtures are verdict-line excerpts, not the 40 KB transcripts, which are thick
with the device's SFS container names the test has no use for.
Verified by mutation: classifying -11 as a rejection, dropping SYNC_STATISTICS
from the init chain, and forgetting the +0x10 response payload offset each fail
the suite.
