From The Apple Wiki
Private Framework
Availabile7.0 – present
Class PrefixBiometricKit

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.)

Classes[edit source]

BiometricKitIdentity[edit source]

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

BiometricKitMatchInfo[edit source]

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[edit source]

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

BiometricKitEnrollProgressCoordinates[edit source]

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

Uses[edit source]

Querying the enrolled fingerprints[edit source]

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

Getting scan results[edit source]

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

BiometricKit manager and delegate methods[edit source]

Simple to set up in your own apps. Note that if you decide to use the BiometricKit class and the BiometricKitDelegate in your own app, the app needs the entitlement of

SBLockScreenManager of SpringBoardUIServices[edit source]

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

XPC[edit source]

BiometricKitXPCClient - (void)matchResult:(BiometricKitIdentity *)result withDictionary:(NSDictionary *)dictionary

Issues after going into the TouchID settings[edit source]

For some unknown reason, no further message would be called upon scanning if the user enters the TouchID settings under 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: 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[edit source]

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

Tweak Basics[edit source]

Suggested method[edit source]

BiometricKit.manager'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.

SBUIBiometricEventMonitor 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:

@protocol SBUIBiometricEventMonitorDelegate
-(void)biometricEventMonitor:(id)monitor handleBiometricEvent:(unsigned)event;

In handleBiometricEvent: an int 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:

[[[objc_getClass("BiometricKit") manager] delegate] addObserver:MyObject];

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.


 #define TouchIDFingerDown  1
 #define TouchIDFingerUp    0
 #define TouchIDFingerHeld  2
 #define TouchIDMatched     3
 #define TouchIDNotMatched  9 // or 10 for iOS 7.1 & iOS 8.x, probably from now on
 @interface AwesomeTouchIDController : NSObject <SBUIBiometricEventMonitorDelegate>{
      BOOL _wasMatching;
      id _monitorDelegate;
      NSArray *_monitorObservers;
      BOOL isMonitoringEvents;
 @implementation AwesomeTouchIDController
 -(void)biometricEventMonitor: (id)monitor handleBiometricEvent: (unsigned)event
      switch (event)
           case TouchIDFingerDown: 
                //finger touchdown!
           case TouchIDFingerUp:
                // finger removed
           case TouchIDFingerHeld:
                // finger was held
           case TouchIDMatched:
                // positive match!
           case TouchIDNotMatched:
                // not matched!
     _monitorDelegate=[[objc_getClass("BiometricKit") manager] delegate];
     monitor=[objc_getClass("SBUIBiometricEventMonitor") sharedInstance];
     [[objc_getClass("BiometricKit") manager] setDelegate:monitor];
     _wasMatching=[[monitor valueForKey:@"_matchingEnabled"] boolValue];
     _monitorObservers=[[monitor valueForKey:@"observers"] copy];
     for (int i=0; i<_monitorObservers.count;  i++)
          [monitor removeObserver:[[monitor valueForKey:@"observers"] objectAtIndex:i]];
     [monitor addObserver:self];
     [monitor _setMatchingEnabled:YES];
     [monitor _startMatching];
     if (!isMonitoringEvents)
     SBUIBiometricEventMonitor *monitor=[[objc_getClass("BiometricKit") manager] delegate];
     [monitor removeObserver:self]; 
     for (id observer in _monitorObservers)
          [monitor addObserver:observer];
     [monitor _setMatchingEnabled:_wasMatching];
     [[objc_getClass("BiometricKit") manager] setDelegate:_monitorDelegate];
 . // cleanup and release as needed

References[edit source]

Examples[edit source]

Project Author
BioTesting Sassoty