This solution is very similar to the way fingerprint readers work under Linux. So if you already configured your fingerprint reader on Linux chances are you will find these instructions familiar. However keep in mind than these instructions are for FreeBSD. In particular I did this on 11-CURRENT but it should also work on 10-RELEASE.
The libfprint library provides the support for the fingerprint readers. In particular it provides drivers for some fingerprint readers (you can find the list on their website), and an API to manipulate the device including the code to enroll/match a fingerprint. This library uses libusb-1.0 for communication with the device. FreeBSD 8 and above already include a reimplementation of this library. This also means that you do not have to enable the device kernel-side. As long as libfprint supports the device and you have access to it (/dev/ugen*), it should work.
The pam_fprint module allows you to use your fingerprint reader for authentication. When correctly configured, you are asked to swipe your fingerprint across the reader instead of a password prompt. This module relies on libfprint to access the device and reads the fingerprints from your home directory. However the sync mechanism used by this module can pose problems when multiple applications try to access the device at the same time.
To address this problem the fprintd daemon offers libfprint functionality via D-Bus. In the same way as pam_fprint, this daemon also provides a PAM module, pam_fprintd, for authentication. This module stores the fingerprints into the /var/lib/fprint directory with permission 700. In other words, this directory is not readable/browsable by other users. Also the fprintd daemon is launched by D-Bus with root permissions. Since it is this daemon in particular that accesses the device, you do not have to change the permissions for your user to access it.
In this article I will present you both method, the direct direct method through libfprint (pam_fprint) and the D-Bus method through fprintd (pam_fprintd). However I would strongly recommend the D-Bus method as it requires less configuration, it is more reliable and also more secure to my opinion.
Note that an application must use PAM in order to authenticate with the fingerprint reader. Some ports, for example xscreensaver, disable PAM authentication by default. So you need to recompile it with PAM enabled as described in a previous article.
Direct method
First you need to install the following ports:
- security/libfprint
- security/pam_fprint
You may also install security/fprint_demo which will come up handy to test that your fingerprint reader works correctly with libfprint.
Then you need to ensure that the device is accessible by the users. To do so, we first identify the usb port the fingerprint reader is attached to. Then we create a special group for the users that can access the device. After that we create a devfs rule to change the group and permission of the device’s usb port.
First we identify the usb port of the fingerprint reader:
# usbconfig
...
ugen0.3: <Biometric Coprocessor UPEK> at usbus0, cfg=0 md=HOST spd=FULL (12Mbps) pwr=ON (100mA)
...
Now we know it’s on ugen0.3. It’s time to add a special group for this kind of device:
# pw groupadd fprint
# pw groupmod -m user1,user2,user3
In this case, user1, user2 and user3 will have access to the fingerprint reader and so will be authenticated with their fingerprint. We can tell devfs to change the permission and group of ugen0.3 to fingerprint and 660. Note that /dev/ugen0.3 is a symlink to /dev/usb/0.3.0 so we change the group and permission of that file too:
/etc/rc.conf:
devfs_system_ruleset="localrules"
/etc/devfs.rules:
[localrules=10]
add path 'ugen0.3' mode 0660 group fprint
add path 'usb/0.3.0' mode 0660 group fprint
Now we take the changes into account and test that the device is accessible for say user1. However to make sure that the changes are enabled on all active session, you may as well just reboot your system:
# service devfs restart
# su user1
$ usbconfig
ugen0.3: <Biometric Coprocessor UPEK> at usbus0, cfg=0 md=HOST spd=FULL (12Mbps) pwr=ON (100mA)
If you installed fprint_demo you can also test that the fingerprint reader works via libfprint with this command. If it works, it will show the device, in my case “UPEK Eikon 2”, say it is ready to use and propose to enroll your fingerprints.
Note this solution is not ideal since the device may not always be attached to the same port. A better solution would be a devd rule that matches the device more precisely.with vendor/product id. I tried to do so but I’m still fairly new to devd and probably got it wrong. Since I found another method that does not involve changing the permissions, I did not look into this. If someone knows better he’s welcome to post his solution below.
Now that we have access to the device, we can tell PAM to authenticate the users with the fingerprint reader when possible. PAM looks for its modules in /usr/lib. However pam_fprint installs itself in /usr/local/lib. To avoid absolute path in the PAM configuration, I create the following symlink /usr/lib/pam_fprint.so -> /usr/local/lib/pam_fprint.so. It’s time to configure PAM. Most services (slim, xscreensaver, …) will refer to /etc/pam.d/system for their PAM configuration, so we only configure this one. We add the pam_fprint module as sufficient to authenticate the user, just before pam_unix (password authentication):
/etc/pam.d/system:
...
# auth
auth sufficient pam_fprint.so
auth required pam_unix.so no_warn try_first_pass nullok local_pass
...
Now we can enroll our fingerprints. You need to do this for each user that will authenticate with the fingerprint reader:
$ pam_fprint_enroll
This program will enroll your finger, unconditionally overwriting any selected print that was enrolled previously. If you want to continue, press enter, otherwise hit Ctrl+C
Found device claimed by UPEK Eikon 2 driver
Opened device. It's now time to enroll your finger.
You will need to successfully scan your Right Index Finger 5 times to complete the process.
Scan your finger now.
Enroll stage passed. Yay!
...
Scan your finger now.
Enroll complete!
Enrollment completed!
Finally we can test if everything works correctly. In this case we use sudo to authenticate with our own user:
$ sudo -i
Swipe your right index finger across the fingerprint reader
#
If you can do this, it works.
D-Bus method
In this method we use the fprintd deamon to access libfprint functionality via D-Bus. To my opinion, this method is simpler, more reliable and more secure than the direct method presented above. The only problems are that the D-Bus daemon is harder to understand and thus debug, also if you have a problem with D-Bus, you are stuck.
First you need to install the following ports:
- security/libfprint
- security/fprintd
You do not have to ensure that the device is accessible by the users as the fprintd daemon is launched by D-Bus with root permissions. The only thing we have to do now is to tell PAM to authenticate the users with the fingerprint reader when possible. PAM looks for its modules in /usr/lib. However fprintd installs the pam_fprintd module in /usr/local/lib. To avoid absolute path in the PAM configuration, I create the following symlink /usr/lib/pam_fprintd.so -> /usr/local/lib/pam_fprintd.so. It’s time to configure PAM. Most services (slim, xscreensaver, …) will refer to /etc/pam.d/system for their PAM configuration, so we only configure this one. We add the pam_fprintd module as sufficient to authenticate the user, just before pam_unix (password authentication):
/etc/pam.d/system:
...
# auth
auth sufficient pam_fprintd.so
auth required pam_unix.so no_warn try_first_pass nullok local_pass
...
Now we can enroll our fingerprints. You need to do this for each user that will authenticate with the fingerprint reader:
$ fprintd-enroll
Using device /net/reactivated/Fprint/Device/0
Enrolling right-index-finger finger.
Enroll result: enroll-stage-passed
...
Enroll result: enroll-completed
Finally we can test if everything works correctly. In this case we use sudo to authenticate with our own user:
$ sudo -i
Swipe your right index finger across the fingerprint reader
#
If you can do this, it works.
