A seeded map was reported as empty. The instrumented path shows why in one line:
`user` on postmarketOS is uid 10000, not 1000, so the daemon looked for
fingers-10000.map and the file I had written was fingers-1000.map. Two probe-mode
enrolments today also went into gid 1000 on the same assumption -- a group the
daemon will never select for that user, since gid is the uid by design.
Nothing to correct in the daemon; the assumption was mine, and the fix is to
enrol through the daemon rather than around it. The log line stays because
"which uid did we resolve and which file did we open" is the first question
every time this surface says a user has nothing enrolled.
The probe becomes the thing the plan was for. Three threads: the supplicant
services QTEE's callbacks; the worker owns the sensor rail, the QTEE session
and the trustlet and is the only thread that ever invokes it, so every
enrolment and authentication is serialised by construction; the main thread
runs the GLib loop and speaks fprintd's own D-Bus interface, never touching
the trustlet directly.
Session is the bring-up from a cold /dev/tee0 to a calibrated sensor, plus the
enrol and verify loops as methods that take a cancel flag and progress
callbacks. Worker is a job queue on a pthread with an 8 MiB stack -- musl's
default is 128 KiB and the session keeps request buffers on the stack. Results
come back through g_idle_add so signals are emitted on the thread that owns
the connection.
net.reactivated.Fprint is implemented rather than wrapped: Manager with
GetDevices/GetDefaultDevice, Device with Claim/Release, EnrollStart/Stop,
VerifyStart/Stop, ListEnrolledFingers and the three Delete variants, the three
signals, and the five properties. Owning fprintd's name is what lets
pam_fprintd, the Plasma KCM and fprintd-enroll work unmodified.
Two honest limits. Authorisation is the conservative rule -- you may act on
your own prints, root on anyone's -- because polkit is not in this milestone.
And DeleteEnrolledFingers removes the finger's NAME only: FF_CMD_TA_REMOVE
exists but its payload is not reverse-engineered, and guessing at a command
that writes to the store is exactly how an index got invalidated earlier
today. A deleted finger loses its name and stops being offered; its template
still occupies a slot in the group. Logged as such.
The finger-name map is written per user under the state directory, tmp-file
and rename. An enrolment records the fid the trustlet reported in the touch
event's response; if none was reported the finger cannot be named yet, and
the daemon says so rather than inventing one.
Verified on the phone as a systemd unit: owns the bus name, init chain
complete, floor calibrated, ready.
SAVE_DATA now returns rc=0: 24 gpfile writes, 13 RPMB writes, no rollback.
The last fault was collecting the RPMB result frame into a local array. QTEE
reads it at req + req[0x0c] -- the same place the request frames were -- so
into a local means QTEE never sees the device's answer, fails the whole
transaction with an I/O error, and rolls back, having already committed the
counter. The reference passes the shared buffer as both source and result
destination for exactly this reason.
Also: req+0x14 is not always a usable chunk size. The reference falls back to
the whole block count when it is zero or exceeds nblocks, and refusing instead
aborts a legitimate write.
--cal-save drives a calibration save, which writes a real container through the
entire storage stack and needs NO FINGER. Three faults were found and fixed
with it in minutes, each of which would otherwise have cost a person ten
press-and-lift cycles to reach.
A process note worth more than the code. An earlier attempt at this appeared to
die mid-transaction; it did, and I killed it -- piping the phone's output
through `head` closed the pipe, SIGPIPE travelled back through tee, and the
daemon was terminated during an RPMB write sequence. That is precisely the
state the journal warns leaves a store inconsistent with a counter that cannot
be moved back. Never truncate a long-running device command's output; let it
finish and read its transcript.
A store with no enrolments has no group directory, and open(O_CREAT) creates
the file but never its parent. A first enrolment into a fresh store therefore
failed with ENOENT, which QTEE reports as an I/O error -- indistinguishable
from a real storage fault, and the same -5 a refused RPMB write produces.
An enrolment collected all ten samples and then SAVE_DATA answered -5. The
cause was not the sensor or the storage framing: ServeRpmb only ever
implemented Op::Read. A write fell through the branch with rc still -1 and was
refused, whatever --rpmb-write said. QTEE could not commit the anti-rollback
record, so it rolled the transaction back -- after it had already rewritten the
group's index container on disk.
The write sequence is per chunk: the data frames out, a Result Read Request
out, the result frame back. A remainder is refused rather than partially
committed, and a non-zero device result aborts instead of continuing into
further chunks, because at that point the counter state is not what we think it
is.
The refusal was not the only failure. Two assumptions were wrong and both are
recorded in the journal:
--group-path does NOT isolate the group directory. The writes went to the
Android group, the one holding the working template, not to a new group derived
from the namespace path. Isolation has to come from pointing the SFS root at a
separate tree, not from the namespace key.
And the rolled-back transaction left the index rewritten, so QTEE rejected it
and the template became unreachable -- ENUMERATE 0, and repeated unlink
attempts refused only because the mount had been switched back to read-only.
Restoring the index from the pre-enrolment backup brought it back: templates
loaded 1.
The RPMB counter never moved, which is why restoring an older index worked at
all. Had the write path been implemented, it would have.
Two problems from a real attempt, one mine and one the tool failing to explain
itself.
A sample is taken on the RISING edge only. Holding the finger down produces no
further touch events however long it stays there, so a run with the finger
almost permanently down collects one sample: 55 finger frames across 60, three
touch events, two samples accepted. The loop now says which state it is in on
every line -- press, hold, or LIFT -- shows accepted-of-total as it goes, and
calls out a finger that has been held for several frames, because that is the
state where nothing is happening and nothing on screen said so.
And the total is now read from the config instead of inferred. `rem` is
reported after the sample is processed, so the first reading of a healthy
enrolment is already 9, and a session that takes the first reading as its total
is permanently off by one -- it reported "1 of 9 accepted" when two samples had
been accepted out of ten. common.max_enrolling_samples is stated explicitly in
the generated config so both sides agree on the number rather than one of them
guessing.
Also recorded: not every press is accepted. The third touch of that run
reported the same count as the second, which is the algorithm rejecting a
sample, and is normal.
A three-tap enrolment declared itself complete. The transcript says why:
frame 2: metric=308 FINGER ev5 rem=10
frame 3: metric=187 ev6 rem=0
samples: 10 of 10 accepted
The release event never enters do_enroll, so its response leaves
samples-remaining untouched at 0 -- which is indistinguishable from "none
remaining, you are finished". The session believed it, stopped after one press,
and called SAVE_DATA on an algorithm holding no template. That answered -1 and
wrote nothing, so the store was undamaged, but only by luck: the guard meant to
prevent a partial save was itself satisfied by the bogus count.
A reading is only meaningful when it came from the event that runs the enrol
path, and nothing about the value says so -- the caller has to. Observe now
takes that as an argument. Two further guards: a FIRST reading of 0 is an
unpopulated field rather than a finished enrolment, and the count only ever
falls, so an increase is noise.
Verified by mutation: trusting the release event's count, and accepting a
leading zero, each fail the suite.
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.
A correct-finger run matched on frame 1 -- twice, on both the touch and the
image-ready event, with the right gid and fid -- and then answered "not
identified yet" for the remaining 39 frames without ever producing another
verdict. The matcher was never the problem; our loop wedged after the first
result.
The reference frame loop is {QUERY_EVENT_STATUS, CAPTURE_IMAGE, REPORT_EVENT,
QUERY_EVENT_STATUS, REPORT_EVENT}. Ours queried only at the top of the frame.
QUERY_EVENT_STATUS answers in rc -- 5 while an event is pending, 0 once
REPORT_EVENT has consumed it -- so the trailing query is what acknowledges the
trustlet's event state before the next frame. Without it the state is never
cleared and every later frame is refused.
Both status values are now printed per frame, so the state machine is visible
rather than inferred.
This also explains the wrong-finger control reading as 40 rescans and no
rejection: a session that never resolves has nothing to acknowledge, so it
looked the same either way and told us less than it appeared to.
PoisonFid takes the payload and offsets to the fid field internally. It was
being handed a span already offset by the payload offset, so the poison landed
at payload+0x20 and the real fid field stayed zero. A frame where the matcher
never ran then looks exactly like a frame where it ran and rejected -- which is
the specific failure this project has recorded three times and is precisely
what the poison exists to prevent.
Visible in a real run: the frames marked REJECTED were 138, 138, 133, 137, 134
against a floor of 136, i.e. every one of them was a finger-RELEASE frame with
nothing on the sensor. Five rejections that never happened.
The two offsets are numerically equal, which is why double-applying is silent,
so the test now pins both directions: poisoning the payload marks the fid
field, and poisoning an already-offset span leaves it zero and misclassifies.
Also adds --rescan=N, which patches common.max_authentication_rescan_times into
the config. The stock budget lets a whole run end with no terminal verdict --
correct for shipping, useless as a measurement, because a wrong-finger control
that never reaches a verdict has not demonstrated a rejection. Forcing 0 makes
every frame terminal. It prints MEASUREMENT ONLY because a rate taken that way
is a per-frame figure with the retry mechanism disabled, and is not a shipping
reject rate.
A run whose result nobody recorded is a run that has to be repeated on a
human's finger, and this daemon printed to stdout and nowhere else. Two real
authentication runs -- an enrolled finger and a wrong-finger control -- were
performed and their output is simply gone.
A single shared log path would be worse than none: the next run, including a
quick control, overwrites the interesting one. That very nearly cost this
project the transcript of its first successful authentication, which is why
the harness moved to per-run files.
Teeing is done at the file-descriptor level rather than by wrapping a stream.
std::println writes to stdout through C stdio, so an ostream wrapper captures
nothing; routing fd 1 through tee catches every line, including whatever the
library prints.
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.
The daemon now powers the sensor and initialises the trustlet against it. On
the phone, every step of the chain returning rc=0:
gpiochip 'f100000.pinctrl' is /dev/gpiochip5 (168 lines)
sensor powered, reset released, irq=1
CMD 0x1006 INIT_SPI rc=0
CMD 0x100a PROBE_DEVICE rc=0
CMD 0x100b INIT_DEVICE rc=0
CMD 0x1004 TA_INIT rc=0
CMD 0x1020 WORK_MODE rc=0
CMD 0x100e SYNC_STATISTICS rc=0
GPIO v2 chardev ioctls directly rather than libgpiod, which is on neither the
phone nor the sysroot and would be a dependency for three lines.
The chip is found by label, and the label is not what the device tree calls it:
the node is pinctrl@f100000 so the chardev advertises "f100000.pinctrl", while
every DT reference says "tlmm". Matching on "tlmm" finds nothing, which is how
the first run failed. There is a second check on the line count, because this
SoC has another pinctrl with 23 lines and driving line 75 of the wrong
controller is not something you recover from over ssh.
The XPU guard is enforced where the line is actually opened, not only asserted
in the core. gpio8-11 are the fingerprint SPI pads and touching one is an
immediate SError with the phone rebooting where it stands, so a refusal has to
sit in front of the ioctl.
Owning the rail is what makes the session recoverable at all: one reset buys
exactly one trustlet init and a second answers -205, so a failed session needs
the rail cycled rather than the chain retried. The harness split these across
two processes and every run began by restarting the one holding the rail.
CAPTURE_IMAGE answers -201 here and that is correct, not a regression: it needs
a shared memory region whose address QTEE patches into the payload, and none is
supplied yet. That is the next piece.
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's own code now talks to QTEE. On the phone:
root object on /dev/tee0
client env obtained (uid 0, 13-byte credentials)
QSEECOM-compat app loader (UID 122) opened
The credentials object is ours rather than libqcomtee's. Upstream's exists only
to build a thirteen-byte CBOR map and drags in QCBOR to do it, so
packaging/make-libqcomtee.sh compiles the two sources that matter and drops
credentials_obj.c entirely -- nothing else references it, and the library then
has no dependency beyond libc. The map is built in Fingerprintd:Tee where it is
pinned byte-for-byte against the string verified on-device, and the object's
two-op read protocol is served here.
Three interop details, all of which cost a build cycle:
* libqcomtee's headers carry no extern "C" guard, having only ever been
consumed from C, so everything came out C++-mangled. They also pull in
<stdatomic.h> and <stdio.h>, which under libc++ drag in templates that may
not appear inside extern "C" -- so those are included first.
* tee_call_t's second parameter is unsigned long on glibc and int on musl.
The native build is glibc and the phone is musl; both forms are compiled.
* On the callback path a UBUF_OUTPUT param arrives with addr = NULL. The
dispatcher supplies the buffer, so a handler POINTS the param at its own
storage rather than writing through the incoming address. Doing the latter
is a null dereference that takes the supplicant thread with it, which is
how the first run against real QTEE ended -- with the correct behaviour
already spelled out in the module comment above the code that ignored it.
That comment now says so in as many words.
fingerprintd will own the FP6's fingerprint sensor: the rail, the QTEE session,
the storage callbacks QTEE makes back into the normal world, and
net.reactivated.Fprint so pam_fprintd and the desktop need no changes. None of
that runs yet. What is here is the first core module and the machinery around
it.
Fingerprintd:Sfs is the gpfile listener's frame -- the callback that carries
47 of 66 storage requests during an enrolment. It is parse, reply and root
mapping only: no file I/O, no TEE, no allocation of the shared buffer. The
daemon shell supplies those, which is what lets every byte-level decision be
tested on a dev box with no phone.
The module exists mainly to hold one fact. READ answers at req+0x00c and WRITE
reads its payload from req+0x110, because the frame is a union: a WRITE still
needs its path while the payload is copied out, so it sits past the 256-byte
path field, while a READ has consumed the path and packs its reply over it.
Conflating them is wrong in both directions with the same symptom -- the
container does not round-trip, QTEE's HMAC check fails, and the file is
unlinked as tampered on the next session.
So the tests do not assert the constants against themselves. They load two real
containers off the phone -- one written correctly, one written with the offsets
conflated -- and re-derive the bug: the broken one opens with ASCII path text
rather than a binary HMAC, that text is the group name from character 8 because
the read offset is 8 bytes into the path field, and the real container sits
exactly 0x104 further in. Then a write-store-read round trip must be the
identity, and the same round trip through a single offset must not be.
O_TRUNC gets a static_assert of its own. QTEE writes a container as
write(0,4096), write(4096,N), write(0,4096), so truncating on open leaves 4096
bytes where a 258850-byte template belongs; it unlinks a file it means to
shorten rather than relying on the opener.
Verified by mutation: conflating the offsets, making DataOffset return the read
offset for writes, and setting O_TRUNC each fail the suite.
