Fprint: Difference between revisions
(Add simplified Chinese translation link) |
m (→Troubleshooting: Move newer entry to the bottom + expand shortening) |
||
(26 intermediate revisions by 14 users not shown) | |||
Line 1: | Line 1: | ||
{{Lowercase title}} | {{Lowercase title}} | ||
[[Category:Input devices]] | [[Category:Input devices]] | ||
[[ | [[es:Fprint]] | ||
[[ja:Fprint]] | [[ja:Fprint]] | ||
[[pt:Fprint]] | [[pt:Fprint]] | ||
Line 18: | Line 18: | ||
== Prerequisites == | == Prerequisites == | ||
{{Note|The list of supported devices is not updated regularly and is not complete. It is worth testing your device using the instructions on this page even if it does not appear on that list, prior to resorting to [[AUR]] packages.}} | |||
You can check if your device is supported by checking the [https://fprint.freedesktop.org/supported-devices.html list of supported devices] or the [https://gitlab.freedesktop.org/libfprint/wiki/-/wikis/Unsupported-Devices list of unsupported devices]. To check which one you have, type: | |||
$ lsusb | $ lsusb | ||
{{ | The ''lsusb'' tool is available inside the {{Pkg|usbutils}} package. | ||
== Installation == | == Installation == | ||
Line 28: | Line 30: | ||
[[Install]] the {{Pkg|fprintd}} package. {{Pkg|imagemagick}} might also be needed. | [[Install]] the {{Pkg|fprintd}} package. {{Pkg|imagemagick}} might also be needed. | ||
Some devices require a different fork of {{Pkg|libfprint}} | Some devices require a different fork of {{Pkg|libfprint}}, not (yet?) merged with the main ''libfprint'': | ||
* {{App|libfprint-tod|For touch-based sensors.|https://gitlab.freedesktop.org/3v1n0/libfprint/-/tree/tod|{{AUR|libfprint-tod-git}}}} | |||
* {{App|libfprint-elanmoc2|For ELAN {{ic|04f3:0c4c}} waiting [https://gitlab.freedesktop.org/libfprint/libfprint/-/merge_requests/330 merge].|https://gitlab.freedesktop.org/Depau/libfprint/-/tree/elanmoc2|{{AUR|libfprint-elanmoc2-git}}}} | |||
* {{App|libfprint-elanmoc2-newdrvs|'''Experimental''' for {{ic|04f3:0c4c}} or a {{ic|04f3:0c00}}, waiting [https://gitlab.freedesktop.org/Depau/libfprint/-/merge_requests/1 merge].|https://gitlab.freedesktop.org/geodic/libfprint/-/tree/elanmoc2|{{AUR|libfprint-elanmoc2-newdrvs-git}}}} | |||
== Configuration == | == Configuration == | ||
Line 49: | Line 55: | ||
This tries to use fingerprint login first, and if it fails or if it finds no fingerprint signatures in the given user's home directory, it proceeds to password login. | This tries to use fingerprint login first, and if it fails or if it finds no fingerprint signatures in the given user's home directory, it proceeds to password login. | ||
You can also modify other files in {{ic|/etc/pam.d/{login,su,sudo,gdm,lightdm}<nowiki/>}} in the same way | You can also modify other files in {{ic|/etc/pam.d/{login,su,sudo,gdm,lightdm}<nowiki/>}} in the same way. For example {{ic|/etc/pam.d/polkit-1}} for [[polkit]] based authentication (GNOME & many other desktop environments) or {{ic|/etc/pam.d/kde}} for unlocking KDE's lockscreen. | ||
Adding {{ic|pam_fprintd.so}} as ''sufficient'' to any configuration file in {{ic|/etc/pam.d/}} when a fingerprint signature is present will only prompt for fingerprint authentication. This prevents the use of a password if you cannot {{ic|Ctrl+c}} fingerprint authentication (due to the lack of a shell). In order to use either a password or a fingerprint in a graphical interface, add the following line to the top of any files required: | Adding {{ic|pam_fprintd.so}} as ''sufficient'' to any configuration file in {{ic|/etc/pam.d/}} when a fingerprint signature is present will only prompt for fingerprint authentication. This prevents the use of a password if you cannot {{ic|Ctrl+c}} fingerprint authentication (due to the lack of a shell). In order to use either a password or a fingerprint in a graphical interface, add the following line to the top of any files required: | ||
Line 83: | Line 89: | ||
# fprintd-enroll ''user'' | # fprintd-enroll ''user'' | ||
To verify the newly created fingerprint, use: | |||
$ fprintd-verify | |||
For more information, see {{man|1|fprintd}}. | For more information, see {{man|1|fprintd}}. | ||
Line 120: | Line 130: | ||
Ensure your device's firmware is up to date with [[Fwupd]]. | Ensure your device's firmware is up to date with [[Fwupd]]. | ||
=== gdm hangs when revealing login prompt after suspend === | |||
This issue is described [https://gitlab.freedesktop.org/libfprint/libfprint/-/issues/426 in libfprint repository]. The developers answer is: | |||
:My guess right now is that we are disconnecting the BT USB dongle while it is being initialised. Then everything gets stuck while btusb is trying to load the firmware (this has a 10s timeout, explaining the just under 10s hang that we are seeing). Disconnecting the bluetooth dongle like this is expected to happen when the rfkill switch is toggled, so that is normal. It just seems that the case where the device suddenly disconnects is not handled properly and times out. | |||
The proposed fix is to [[create]]: | |||
{{hc|/etc/modprobe.d/bluetooth-blacklist.conf|blacklist btusb}} | |||
Or execute straight away: | |||
# rmmod btusb | |||
Then it should not try to initialize the device. | |||
=== Unexpected error while suspending device === | |||
This issue is described [https://gitlab.freedesktop.org/libfprint/libfprint/-/issues/538 in libfprint repository]: | |||
:You need to set your laptop to not suspend to RAM but to do s2idle. You might need to switch the BIOS into "Windows mode". | |||
=== Fingerprint authentication is not taking effect in the Polkit agent. === | |||
After adding fingerprint rules to Linux PAM, fingerprint recognition only works for [[SDDM]] and [[sudo]], but not for [[polkit]]. | |||
Copy the {{ic|50-default.rules}} file to {{ic|/etc/}} and change group name {{ic|wheel}} to your user group. | |||
# cp /usr/share/polkit-1/rules.d/50-default.rules /etc/polkit-1/rules.d/ | |||
{{hc|/etc/polkit-1/rules.d/50-default.rules|<nowiki> | |||
polkit.addAdminRule(function(action, subject) { | |||
return ["unix-group:wheel"]; | |||
}); | |||
</nowiki>}} | |||
=== Debug === | |||
Use the following environment variable and command line flag: | |||
# G_MESSAGES_DEBUG=all /usr/lib/fprintd -t | |||
=== fprintd starts before fingerprint reader device is initialized after resuming from sleep === | |||
Create and [[enable]] the following systemd service, replacing {{ic|3-3}} with the bus ID and port of your fingerprint reader, which you can find using {{ic|lsusb -t}}: | |||
{{hc|/etc/systemd/system/fingerprint.service|<nowiki> | |||
[Unit] | |||
Description=Kill fprintd and enable USB persist before sleep | |||
Before=sleep.target | |||
[Service] | |||
ExecStart=/usr/bin/sh -c "killall fprintd; echo 1 > /sys/bus/usb/devices/3-3/power/persist" | |||
[Install] | |||
WantedBy=sleep.target | |||
</nowiki>}} | |||
=== Enrolling works but verifying does not === | |||
Some touch-based fingerprint readers generate images too small for fprint's algorithm to work properly. A common workaround for those is swiping instead of touching the sensor, but the speed at which a good image is generated may vary. Some sensors require a slower swipe and some a faster one. Here are some tips regarding [https://github.com/iafilatov/libfprint#common-problems what a good image should look like]. | |||
If you want to practice with different speeds to see which generates a better image, try dumping the images with the script [https://gitlab.freedesktop.org/libfprint/libfprint/-/blob/master/examples/img-capture.c examples/img-capture] and comparing it with the examples from above (you will need to compile libfprint from source). | |||
See also https://gitlab.freedesktop.org/libfprint/libfprint/-/issues/174 |
Latest revision as of 17:13, 10 April 2024
From the fprint homepage:
- The fprint project aims to plug a gap in the Linux desktop: support for consumer fingerprint reader devices.
The idea is to use the built-in fingerprint reader in some notebooks for login using PAM. This article will also explain how to use regular password for backup login method (solely fingerprint scanner is not recommended due to numerous reasons).
Prerequisites
You can check if your device is supported by checking the list of supported devices or the list of unsupported devices. To check which one you have, type:
$ lsusb
The lsusb tool is available inside the usbutils package.
Installation
Install the fprintd package. imagemagick might also be needed.
Some devices require a different fork of libfprint, not (yet?) merged with the main libfprint:
- libfprint-tod — For touch-based sensors.
- libfprint-elanmoc2 — For ELAN
04f3:0c4c
waiting merge.
- libfprint-elanmoc2-newdrvs — Experimental for
04f3:0c4c
or a04f3:0c00
, waiting merge.
- https://gitlab.freedesktop.org/geodic/libfprint/-/tree/elanmoc2 || libfprint-elanmoc2-newdrvs-gitAUR
Configuration
Login configuration
- If you use GDM, the fingerprint-option is already available in the login menu (if not add yourself to the
input
user group). You can skip this section! - If you use SDDM, see SDDM#Using a fingerprint reader.
Add pam_fprintd.so
as sufficient to the top of the auth section of /etc/pam.d/system-local-login
:
/etc/pam.d/system-local-login
auth sufficient pam_fprintd.so auth include system-login ...
This tries to use fingerprint login first, and if it fails or if it finds no fingerprint signatures in the given user's home directory, it proceeds to password login.
You can also modify other files in /etc/pam.d/{login,su,sudo,gdm,lightdm}
in the same way. For example /etc/pam.d/polkit-1
for polkit based authentication (GNOME & many other desktop environments) or /etc/pam.d/kde
for unlocking KDE's lockscreen.
Adding pam_fprintd.so
as sufficient to any configuration file in /etc/pam.d/
when a fingerprint signature is present will only prompt for fingerprint authentication. This prevents the use of a password if you cannot Ctrl+c
fingerprint authentication (due to the lack of a shell). In order to use either a password or a fingerprint in a graphical interface, add the following line to the top of any files required:
auth sufficient pam_unix.so try_first_pass likeauth nullok auth sufficient pam_fprintd.so ...
This will prompt for a password; pressing Enter
on a blank field will proceed to fingerprint authentication.
If you want to prompt for fingerprint and password input at the same time, you can use pam-fprint-grosshackAUR. This may be needed for some graphical programs which do not allow blank password input, such as Gnome's built-in polkit agent. To use this package, add the following lines to the top of any files required:
auth sufficient pam_fprintd_grosshack.so auth sufficient pam_unix.so try_first_pass nullok ...
Create fingerprint signature
You will need to have an authentication agent running before being able to enroll.
To add a signature for a finger, run:
$ fprintd-enroll
or create a new signature for all fingers:
$ fprintd-delete "$USER" $ for finger in {left,right}-{thumb,{index,middle,ring,little}-finger}; do fprintd-enroll -f "$finger" "$USER"; done
You will be asked to scan the given finger. Swipe your right index finger five times. After that, the signature is created in /var/lib/fprint/
.
You can also enroll without an authentication agent:
# fprintd-enroll user
To verify the newly created fingerprint, use:
$ fprintd-verify
For more information, see fprintd(1).
Restrict enrolling
By default every user is allowed to enroll new fingerprints without prompting for the password or the fingerprint. You can change this behavior using polkit rules.
There are two locations that contains the polkit configuration files:
/etc/polkit-1/rules.d/
/usr/share/polkit-1/rules.d/
/usr/share/polkit-1/rules.d/
because they will be overwritten on update. Copy them to /etc/polkit-1/rules.d/
first.In the following example only root can enroll fingerprints:
/etc/polkit-1/rules.d/50-net.reactivated.fprint.device.enroll.rules
polkit.addRule(function (action, subject) { if (action.id == "net.reactivated.fprint.device.enroll") { return subject.user == "root" ? polkit.Result.YES : polkit.Result.NO } })
Troubleshooting
No devices available
If your supported device cannot be found or is claimed to be already open (in use), check the fprintd.service
logs in the journal.
You may find log entries like:
fprintd[2936592]: Corrupted message received fprintd[2936592]: Ignoring device due to initialization error: unsupported firmware version
Ensure your device's firmware is up to date with Fwupd.
gdm hangs when revealing login prompt after suspend
This issue is described in libfprint repository. The developers answer is:
- My guess right now is that we are disconnecting the BT USB dongle while it is being initialised. Then everything gets stuck while btusb is trying to load the firmware (this has a 10s timeout, explaining the just under 10s hang that we are seeing). Disconnecting the bluetooth dongle like this is expected to happen when the rfkill switch is toggled, so that is normal. It just seems that the case where the device suddenly disconnects is not handled properly and times out.
The proposed fix is to create:
/etc/modprobe.d/bluetooth-blacklist.conf
blacklist btusb
Or execute straight away:
# rmmod btusb
Then it should not try to initialize the device.
Unexpected error while suspending device
This issue is described in libfprint repository:
- You need to set your laptop to not suspend to RAM but to do s2idle. You might need to switch the BIOS into "Windows mode".
Fingerprint authentication is not taking effect in the Polkit agent.
After adding fingerprint rules to Linux PAM, fingerprint recognition only works for SDDM and sudo, but not for polkit.
Copy the 50-default.rules
file to /etc/
and change group name wheel
to your user group.
# cp /usr/share/polkit-1/rules.d/50-default.rules /etc/polkit-1/rules.d/
/etc/polkit-1/rules.d/50-default.rules
polkit.addAdminRule(function(action, subject) { return ["unix-group:wheel"]; });
Debug
Use the following environment variable and command line flag:
# G_MESSAGES_DEBUG=all /usr/lib/fprintd -t
fprintd starts before fingerprint reader device is initialized after resuming from sleep
Create and enable the following systemd service, replacing 3-3
with the bus ID and port of your fingerprint reader, which you can find using lsusb -t
:
/etc/systemd/system/fingerprint.service
[Unit] Description=Kill fprintd and enable USB persist before sleep Before=sleep.target [Service] ExecStart=/usr/bin/sh -c "killall fprintd; echo 1 > /sys/bus/usb/devices/3-3/power/persist" [Install] WantedBy=sleep.target
Enrolling works but verifying does not
Some touch-based fingerprint readers generate images too small for fprint's algorithm to work properly. A common workaround for those is swiping instead of touching the sensor, but the speed at which a good image is generated may vary. Some sensors require a slower swipe and some a faster one. Here are some tips regarding what a good image should look like.
If you want to practice with different speeds to see which generates a better image, try dumping the images with the script examples/img-capture and comparing it with the examples from above (you will need to compile libfprint from source).
See also https://gitlab.freedesktop.org/libfprint/libfprint/-/issues/174