BiometryService 2.0.0

dotnet add package BiometryService --version 2.0.0
NuGet\Install-Package BiometryService -Version 2.0.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="BiometryService" Version="2.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add BiometryService --version 2.0.0
#r "nuget: BiometryService, 2.0.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install BiometryService as a Cake Addin
#addin nuget:?package=BiometryService&version=2.0.0

// Install BiometryService as a Cake Tool
#tool nuget:?package=BiometryService&version=2.0.0

Biometry Service

License Version Downloads

This library offers a simple contract to use the biometry across Android, iOS and Windows (UWP & WinUI).

Getting Started

  1. Install BiometryService nuget package.

  2. Get an IBiometryService instance.

    IBiometryService is implemented by BiometryService. The constructor of BiometryService is different on each platform.

    Windows

    On Windows there are no parameters.

     _biometryService = new BiometryService();
    

    Android

    On Android, you need to provide a fragmentActivity and a promptInfoBuilder.

    var promptBuilder = () => new BiometricPrompt.PromptInfo.Builder()
        .SetTitle("TODO: Title")
        .SetSubtitle("TODO: Subtitle")
        .SetNegativeButtonText("Cancel")
        .SetAllowedAuthenticators(AndroidX.Biometric.BiometricManager.Authenticators.BiometricStrong)
        .Build();
    
    var biometryService = new BiometryService(
        fragmentActivity: MainActivity.Instance,
        promptInfoBuilder: promptBuilder,
        loggerFactory: null
    );
    

    iOS

    On iOS, you first need to set NSFaceIDUsageDescription (key/value) in the Info.plist file.

    
      <key>NSFaceIDUsageDescription</key>
      <string>TODO: Biometry would like to use Face Id</string>
    

    Then, instantiate of the service for iOS.

    _biometryService = new BiometryService(
        useOperationPrompt: "TODO: Subtitle",
        laContext: null,
        localAuthenticationPolicy: LAPolicy.DeviceOwnerAuthenticationWithBiometrics,
        loggerFactory: null
    );
    
  3. Use ScanBiometry to prompt the native experience. This will use automaticaly use the native biometric service of that device (FaceID, TouchID, Android Fingerprint, ect.).

    try
    {
       await _biometryService.ScanBiometry(CancellationToken.None);
       // TODO: Handle the case when biometry is recognized.
    }
    catch (BiometryException biometryException)
    {
       // TODO: Handle the case when biometry is not recognized.
       Console.WriteLine($"{biometryException.Reason} : {biometryException.Message}");
    }
    

Notes on Instantiation

Android

  • Face authentication is only available when using .SetAllowedAuthenticators(AndroidX.Biometric.BiometricManager.Authenticators.BiometricWeak) in the BiometricPrompt.PromptInfo.Builder instantiation that is required for the service. Please note that if you are using .SetAllowedAuthenticators(AndroidX.Biometric.BiometricManager.Authenticators.BiometricStrong) in the BiometricPrompt.PromptInfo.Builder Facial authentification is exclusively accessible on phones equipped with Class 3 Biometric capabilities. (Pixel 4 and 8 for now).

  • Please note that Encrypt and Decrypt methods are only available when using .SetAllowedAuthenticators(AndroidX.Biometric.BiometricManager.Authenticators.BiometricStrong) in the BiometricPrompt.PromptInfo.Builder instantiation that is required for the service.

  • Please also note that the prompt builder SetTitle and SetSubtitle are used for both Fingerprint and Face biometry. We suggest that you use something generic enough for both cases.

iOS

  • The laContext parameter (local authentication context) can be set by creating a new LAContext.
    var laContext = new LAContext
    {
     	LocalizedReason = "This app wants to use biometry for ...",
     	LocalizedFallbackTitle = "Fallback Title",
     	LocalizedCancelTitle = "Cancel Title"
    };
    
  • Please note that the subtitle passed via useOperationPrompt is only displayed on devices using TouchID.

Features

Platform Compatibilities

The IBiometryService has severals methods.

As of now, this is the list of features available per platform.

Methods iOS Android WinUI UWP
GetCapability
ScanBiometry
Encrypt
Decrypt
Remove

Tests

It's also possible to use a fake implementation of IBiometryService named FakeBiometryService for testing purposes only.

This fake implementation doesn't actually encrypt anything, the key and value pairs are stored in memory.

The fake implementation behavior can be customized by using constructor parameters.

var fakeBiometryService = new FakeBiometryService
{
   biometryType: BiometryType.None,
   isBiometryEnabled: false,
   isPasscodeSet: false
};

Error Handling

Please note that in case of error, a BiometryException is thrown.

Biometry Exception Types:

  • Failed: Any other failures while trying to use the device biometrics.
  • Unavailable: The device biometrics is not available.
  • NotEnrolled: The device has not been enrolled to use biometrics.
  • PasscodeNeeded: The passcode needs to be set on the device.
  • Locked:
    • The device has been locked from using his biometrics.
    • Due mostly to too many attempts.
    • User have to try again later or unlock his device again.
  • KeyInvalidated:
    • Biometric information has changed (E.g. Touch ID or Face ID has changed).
    • User have to set up biometric authentication again.

If it's a cancellation error, OperationCanceledException is thrown.

GetGapabilites

This method gets the device's current biometric capabilities.

It returns a struct BiometryCapabilities with the detailed device configuration.

ScanBiometry

This method attemps to scan the user's biometry.

await biometryService.ScanBiometry(CancellationToken.None);

Encrypt

This method encrypts a value and stores it into the platform secure storage with the given key name.

await biometryService.Encrypt(CancellationToken.None, "Key", "Value");

On Android, a new CryptoObject from AndroidX.Biometric is created with a key as a parameter. Then the data is encrypted and presented to the BiometricPrompt manager. The final step encodes the data in base64 and stores it in the shared preferences.

On iOS, the SecKeyChain is used to store a string linked to a key. The OS is in charge of securing the data with biometric authentication during the process.

Decrypt

This method decrypts and gets the data associated to the given key.

await biometryService.Decrypt(CancellationToken.None, "Key");

On Android, the method retrieves the shared preference encrypted data, then decrypts it with the secret as a parameter by presenting it to the BiometricPrompt manager.

On iOS, the method retrieves the encrypted data from the SecKeyChain with the secret as a parameter. iOS is in charge of decrypting the data with biometric authentication during the process.

Remove

This method removes the ecrypted value from the platform secure storage.

biometryService.Remove("Key");

On Android, the method removes the encrypted data from the shared preferences.

On iOS, the method removes the encrypted data from the SecKeyChain.

Breaking Changes

Please consult the BREAKING CHANGES for more information about breaking changes history.

License

This project is licensed under the Apache 2.0 license - see the LICENSE file for details.

Contributing

Please read CONTRIBUTING.md for details on the process for contributing to this project.

Be mindful of our Code of Conduct.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-android33.0 is compatible.  net7.0-ios was computed.  net7.0-ios16.1 is compatible.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net7.0-windows10.0.19041 is compatible.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed.  monoandroid12.0 is compatible. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Universal Windows Platform uap10.0.19041 is compatible. 
Xamarin.iOS xamarinios was computed.  xamarinios10 is compatible. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
2.0.0 146 3/5/2024
2.0.0-feature.net7.4 146 11/29/2023
2.0.0-feature.net7.2 61 11/24/2023
1.1.0 2,859 11/10/2023
1.0.0 425 11/1/2023
0.4.0-dev.122 81 10/24/2023
0.4.0-dev.120 1,519 5/3/2023
0.4.0-dev.118 6,413 2/28/2023
0.4.0-dev.103 115 10/19/2022
0.4.0-dev.95 113 8/23/2022
0.4.0-dev.91 116 5/2/2022
0.4.0-dev.90 122 3/31/2022
0.3.0-dev.88 129 3/28/2022
0.2.0-dev.83 4,109 12/6/2021
0.2.0-dev.80 153 12/2/2021
0.2.0-dev.76 181 10/29/2021
0.2.0-dev.74 149 10/4/2021
0.2.0-dev.67 194 5/13/2021
0.2.0-dev.56 153 5/4/2021