{"id":21730076,"url":"https://github.com/nventive/biometryservice","last_synced_at":"2025-04-13T00:14:42.508Z","repository":{"id":40557383,"uuid":"301747631","full_name":"nventive/BiometryService","owner":"nventive","description":"Service to simplify iOS FaceID/TouchID and Android's Biometry usage","archived":false,"fork":false,"pushed_at":"2025-03-29T04:53:43.000Z","size":1057,"stargazers_count":11,"open_issues_count":1,"forks_count":3,"subscribers_count":22,"default_branch":"main","last_synced_at":"2025-04-13T00:14:37.204Z","etag":null,"topics":["android","biometry","dotnet","ios","mobile","xamarin"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nventive.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-10-06T14:06:01.000Z","updated_at":"2024-06-28T09:56:15.000Z","dependencies_parsed_at":"2023-10-13T10:18:07.578Z","dependency_job_id":"fcd9d5f9-3b91-4e4f-b104-8924a4f3bc99","html_url":"https://github.com/nventive/BiometryService","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":"nventive/Template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nventive%2FBiometryService","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nventive%2FBiometryService/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nventive%2FBiometryService/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nventive%2FBiometryService/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nventive","download_url":"https://codeload.github.com/nventive/BiometryService/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248647274,"owners_count":21139086,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","biometry","dotnet","ios","mobile","xamarin"],"created_at":"2024-11-26T04:11:49.123Z","updated_at":"2025-04-13T00:14:42.482Z","avatar_url":"https://github.com/nventive.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Biometry Service\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square)](LICENSE) ![Version](https://img.shields.io/nuget/v/BiometryService?style=flat-square) ![Downloads](https://img.shields.io/nuget/dt/BiometryService?style=flat-square)\n\nThis library offers a simple contract to use the biometry across Android, iOS and Windows (UWP \u0026 WinUI).\n\n## Getting Started\n\n1. Install `BiometryService` nuget package.\n   \n1. Get an `IBiometryService` instance.\n\n   `IBiometryService` is implemented by `BiometryService`.\n   The constructor of `BiometryService` is different on each platform.\n\n   ### Windows\n\n   On Windows there are no parameters. \n\n   ``` cs\n    _biometryService = new BiometryService();\n   ```\n\n   ### Android\n\n   On Android, you need to provide a `fragmentActivity` and a `promptInfoBuilder`.\n\n   ``` cs\n   var promptBuilder = () =\u003e new BiometricPrompt.PromptInfo.Builder()\n\t   .SetTitle(\"TODO: Title\")\n\t   .SetSubtitle(\"TODO: Subtitle\")\n\t   .SetNegativeButtonText(\"Cancel\")\n\t   .SetAllowedAuthenticators(AndroidX.Biometric.BiometricManager.Authenticators.BiometricStrong)\n\t   .Build();\n\n   var biometryService = new BiometryService(\n   \t   fragmentActivity: MainActivity.Instance,\n   \t   promptInfoBuilder: promptBuilder,\n   \t   loggerFactory: null\n   );\n   ```\n   ### iOS\n\n   On iOS, you first need to set `NSFaceIDUsageDescription` (key/value) in the `Info.plist` file.\n\n   ``` xml\n     \u003c!-- info.plist --\u003e\n\t \u003ckey\u003eNSFaceIDUsageDescription\u003c/key\u003e\n\t \u003cstring\u003eTODO: Biometry would like to use Face Id\u003c/string\u003e\n   ```\n\n   Then, instantiate of the service for iOS.\n\n   ``` cs\n   _biometryService = new BiometryService(\n   \t   useOperationPrompt: \"TODO: Subtitle\",\n   \t   laContext: null,\n   \t   localAuthenticationPolicy: LAPolicy.DeviceOwnerAuthenticationWithBiometrics,\n   \t   loggerFactory: null\n   );\n   ```\n\n1. Use `ScanBiometry` to prompt the native experience. \n   This will use automaticaly use the native biometric service of that device (FaceID, TouchID, Android Fingerprint, ect.). \n\n   ``` csharp\n   try\n   {\n      await _biometryService.ScanBiometry(CancellationToken.None);\n      // TODO: Handle the case when biometry is recognized.\n   }\n   catch (BiometryException biometryException)\n   {\n      // TODO: Handle the case when biometry is not recognized.\n      Console.WriteLine($\"{biometryException.Reason} : {biometryException.Message}\");\n   }\n   ```\n\n## Notes on Instantiation\n\n### Android\n- 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).\n\n- 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.\n\n- 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.\n\n### iOS\n\n- The `laContext` parameter (local authentication context) can be set by creating a new [LAContext](https://developer.apple.com/documentation/localauthentication/lacontext#2930204).\n   ``` csharp\n   var laContext = new LAContext\n   {\n   \tLocalizedReason = \"This app wants to use biometry for ...\",\n   \tLocalizedFallbackTitle = \"Fallback Title\",\n   \tLocalizedCancelTitle = \"Cancel Title\"\n   };\n   ```\n- Please note that the subtitle passed via `useOperationPrompt` is only displayed on devices using TouchID.\n\n## Features\n\n### Platform Compatibilities\n\nThe `IBiometryService` has severals methods.\n\nAs of now, this is the list of features available per platform.\n\n| Methods          | iOS     | Android | WinUI   | UWP     |\n| ---------------- | :-----: | :-----: | :-----: | :-----: |\n| `GetCapability`  | ✔ | ✔ | ✔ | ✔ |\n| `ScanBiometry`\t | ✔ | ✔ | ✔ | ✔ |\n| `Encrypt`        | ✔ | ✔ | ✔ | ✔ |\n| `Decrypt`        | ✔ | ✔ | ❌ | ❌ |\n| `Remove`         | ✔ | ✔ | ✔ | ✔ |\n\n### Tests\n\nIt's also possible to use a fake implementation of `IBiometryService` named `FakeBiometryService` for testing purposes only.\n\nThis fake implementation doesn't actually encrypt anything, the key and value pairs are stored in memory.\n\nThe fake implementation behavior can be customized by using constructor parameters.\n\n``` csharp\nvar fakeBiometryService = new FakeBiometryService\n{\n   biometryType: BiometryType.None,\n   isBiometryEnabled: false,\n   isPasscodeSet: false\n};\n```\n\n### Error Handling\n\nPlease note that in case of error, a `BiometryException` is thrown. \n\nBiometry Exception Types:\n- `Failed`: Any other failures while trying to use the device biometrics.\n- `Unavailable`: The device biometrics is not available.\n- `NotEnrolled`: The device has not been enrolled to use biometrics.\n- `PasscodeNeeded`: The passcode needs to be set on the device.\n- `Locked`:\n  - The device has been locked from using his biometrics.\n  - Due mostly to too many attempts.\n  - User have to try again later or unlock his device again.\n- `KeyInvalidated`:\n  - Biometric information has changed (E.g. Touch ID or Face ID has changed).\n  - User have to set up biometric authentication again.\n\nIf it's a cancellation error, `OperationCanceledException` is thrown.\n\n### GetGapabilites\n\nThis method gets the device's current biometric capabilities.\n\nIt returns a struct `BiometryCapabilities` with the detailed device configuration.\n\n### ScanBiometry\n\nThis method attemps to scan the user's biometry.\n\n``` cs\nawait biometryService.ScanBiometry(CancellationToken.None);\n```\n\n### Encrypt\n\nThis method encrypts a value and stores it into the platform secure storage with the given key name.\n\n``` cs\nawait biometryService.Encrypt(CancellationToken.None, \"Key\", \"Value\");\n```\n\nOn 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.\nThe final step encodes the data in base64 and stores it in the shared preferences.\n\nOn 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.\n\n### Decrypt\n\nThis method decrypts and gets the data associated to the given key.\n\n``` cs\nawait biometryService.Decrypt(CancellationToken.None, \"Key\");\n```\n\nOn 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.\n\nOn 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. \n\n### Remove\n\nThis method removes the ecrypted value from the platform secure storage.\n\n``` cs\nbiometryService.Remove(\"Key\");\n```\n\nOn Android, the method removes the encrypted data from the shared preferences.\n\nOn iOS, the method removes the encrypted data from the `SecKeyChain`.\n\n## Breaking Changes\n\nPlease consult the [BREAKING CHANGES](BREAKING_CHANGES.md) for more information about breaking changes history.\n\n## License\n\nThis project is licensed under the Apache 2.0 license - see the\n[LICENSE](LICENSE) file for details.\n\n## Contributing\n\nPlease read [CONTRIBUTING.md](CONTRIBUTING.md) for details on the process for\ncontributing to this project.\n\nBe mindful of our [Code of Conduct](CODE_OF_CONDUCT.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnventive%2Fbiometryservice","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnventive%2Fbiometryservice","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnventive%2Fbiometryservice/lists"}