Dev:BiometricKit.framework

BiometricKit is the framework that handles TouchID, present on the iPhone 5s and newer devices. TouchID's internal codename is Mesa. It is a private framework compiled only for arm64. You can also Google "Biokit.h", and from the Gist you can find the headers for the BiometricKit.framework. (You can also dump them yourselves; it is shipped with the iOS 7.0 SDK on Xcode and of course on an iPhone 5s.)

BiometricKitIdentity
BiometricKitIdentity represents the enrolled fingerprints on the device. Properties for the user-defined name and UUID are available.

BiometricKitMatchInfo
A BiometricKitMatchInfo object has two properties:
 * A dictionary of details, including (presumably) the area of the enrolled fingerprint, the number of nodes on file, and whether the enrollment data have been updated just now from the latest scan.
 * An array of topology's of class BiometricKitEnrollProgressInfo. Currently observed to contain up to 15 "topology nodes".

BiometricKitEnrollProgressInfo
A BiometricKitEnrollProgressInfo object contains presumably the actual fingerprint digital representation as BiometricKitEnrollProgressCoordinates objects in its BKEPDNewNodeCoordinates key of messageDetails</tt> dictionary.

BiometricKitEnrollProgressCoordinates
A BiometricKitEnrollProgressCoordinates</tt> object is suspected to record the x and y coordinates and the angle (probably in radians) of the a particular fingerprint distinguishing feature.

Querying the enrolled fingerprints
You can get an array of all BiometricKitIdentity</tt>'s on file with [[BiometricKit manager] identities:nil]</tt>. Note that this will only give you the user-defined names and UUIDs, but not the actual fingerprint characteristics as in BiometricKitEnrollProgressInfo</tt>.

Getting scan results
There are at least three ways you can get the scan results from the TouchID sensor.

BiometricKit manager and delegate methods
Simple to set up in your own apps. Note that if you decide to use the BiometricKit</tt> class and the BiometricKitDelegate</tt> in your own app, the app needs the entitlement of com.apple.private.bmk.allow</tt>.

SBLockScreenManager of SpringBoardUIServices
SBLockScreenManager</tt> - (void)biometricEventMonitor:(SBUIBiometricEventMonitor *)monitor handleBiometricEvent:(unsigned)event</tt> would always be invoked after the screen is on and a fingerprint is registered.

XPC
BiometricKitXPCClient</tt> - (void)matchResult:(BiometricKitIdentity *)result withDictionary:(NSDictionary *)dictionary</tt>

Issues after going into the TouchID settings
For some unknown reason, no further message would be called upon scanning if the user enters the TouchID settings under Preferences.app</tt>. The device has to be slept and unlocked in order to receive messages from the aforementioned methods again.

(If you find a workaround please edit this out. --Jdoe (talk) 07:06, 4 January 2014 (PST))

Edit: Preferences.app</tt> initializes its own instance of BiometricKit during enrollment, hence the lack of any signs of activity on SpringBoard while enrolling. Since the bundle is loaded at a later time than the tweak's constructor firetime, in order to access the methods we may need to use _dyld_register_func_for_add_image or a similar approach. --Limneoselias (talk) 15:16, 14 January 2014 (PST)

Enrollment
(Not investigated, but there are some methods regarding enrollment in this framework. Also refer to the BiometricKitUI.framework</tt> --Jdoe (talk) 07:06, 4 January 2014 (PST))

Suggested method
BiometricKit.manager</tt>'s delegate is SBUIBiometricEventMonitor. It also has a delegate itself, which is always SBLockScreenManager.

Instead of everyone hooking these methods and adding their own code, probably causing conflicts to other TouchID related tweaks, a suggested approach that can easily maintain compatibility is to add our object as an "observer" to SBUIBiometricEventMonitor. Observers seem to only work inside of the SpringBoard process.

<tt>SBUIBiometricEventMonitor</tt> accepts observers, which we can think of as "multiple delegates", but usually with read-only or less privileged actions.

An observer must conform to this protocol:

In <tt>handleBiometricEvent:</tt> an <tt>int</tt> value is passed after a biometric event occurs, which is very convenient to interpret and covers most tweaks' needs.

0 = Finger up

1 = Finger down, scanning

2 = Device requests finger to be lifted

3 = Identity match succeeded

9 = Identity match failed (Note: appears to be 10 on iOS 7.1 & iOS 8.x. Maybe from now on?)

4 = Device unlocked following successful scan

5 = Passcode entry required

6 = Passcode entry required due to a lockout (max failed attempts)

7 = Passcode entry required due to expired print

8 = Passcode entry required due to a reboot

We can create our own object that conforms to the above protocol and add it to SBUIBiometricEventMonitor:

''We may need to enable or disable matching, as it is not always enabled by the system. (e.g. when no passcode is required at lock screen).''

So if any tweak that uses the above approach would conflict with our actions we can:


 * 1) Store all SBUIBiometricEventMonitor observers to a variable (or only the conflicting observer)
 * 2) Remove all observers (or only the conflicting observer)
 * 3) Add our object as the observer
 * 4) Perform our actions
 * 5) Replace all observers as they were before, from our stored variable

And this should work for most tweaks.

Example:

= References =