Skip to content

Commit ecab334

Browse files
LProulx86LProulx86
authored
Merge pull request #75 from nventive/dev/lapr/ReadmeUpdate
Update Readme, add path to package.
2 parents 95ad093 + 67ce465 commit ecab334

4 files changed

Lines changed: 142 additions & 104 deletions

File tree

‎BREAKING_CHANGES.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Breaking Changes

‎README.md‎

Lines changed: 124 additions & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -1,88 +1,123 @@
11
# Biometry Service
22

3-
<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
4-
5-
[![All Contributors](https://img.shields.io/badge/all_contributors-5-orange.svg?style=flat-square)](#contributors-)
6-
7-
<!-- ALL-CONTRIBUTORS-BADGE:END -->
3+
[![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)
84

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

11-
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
12-
13-
## Features
14-
15-
The Biometry Service Interface `IBiometryService` is made of the following methods:
16-
17-
- GetGapabilites
18-
- ScanBiometry
19-
- Encryt
20-
- Decrypt
21-
- Remove
22-
23-
As of now, this is the list of features available per platform.
24-
25-
| Feature | iOS | Android | UWP | WinUI |
26-
| ---------------- | ------- | ------- | ------- | ------- |
27-
| GetCapability | &check; | &check; | &check; | &check; |
28-
| ValidateIdentity | &check; | &check; | &cross; | &cross; |
29-
| Encrypt | &check; | &check; | &cross; | &cross; |
30-
| Decrypt | &check; | &check; | &cross; | &cross; |
31-
327
## Getting Started
338

34-
Install the latest stable version of `BiometryService` in your platform heads and `BiometryService.Abstractions` in your presentation layer if you are using MVVM pattern, and if not just install both in your platform heads.
35-
36-
A small sample Uno application is available as a playground with some basic command to test the service methods.
37-
They also provide some basic initialization but no dependency injection and more complex code.
38-
39-
### Instantiation
40-
41-
#### Android
42-
43-
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` Face authentication is only available on a Google Pixel 4 as of now.
44-
45-
Please note that Encrypt/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.
9+
1. Install `BiometryService` nuget package.
10+
11+
1. Get an `IBiometryService` instance.
12+
13+
`IBiometryService` is implemented by `BiometryService`.
14+
The constructor of `BiometryService` is different on each platform.
15+
16+
### Windows
17+
18+
On Windows there are no parameters.
19+
20+
``` cs
21+
_biometryService = new BiometryService();
22+
```
23+
24+
### Android
25+
26+
On Android, you need to provide a `fragmentActivity` and a `promptInfoBuilder`.
27+
28+
``` cs
29+
var promptBuilder = () => new BiometricPrompt.PromptInfo.Builder()
30+
.SetTitle("TODO: Title")
31+
.SetSubtitle("TODO: Subtitle")
32+
.SetNegativeButtonText("Cancel")
33+
.SetAllowedAuthenticators(AndroidX.Biometric.BiometricManager.Authenticators.BiometricStrong)
34+
.Build();
35+
36+
var biometryService = new BiometryService(
37+
fragmentActivity: MainActivity.Instance,
38+
promptInfoBuilder: promptBuilder,
39+
loggerFactory: null
40+
);
41+
```
42+
### iOS
43+
44+
On iOS, you first need to set `NSFaceIDUsageDescription` (key/value) in the `Info.plist` file.
45+
46+
``` xml
47+
<!-- info.plist -->
48+
<key>NSFaceIDUsageDescription</key>
49+
<string>TODO: Biometry would like to use Face Id</string>
50+
```
51+
52+
Then, instantiate of the service for iOS.
53+
54+
``` cs
55+
_biometryService = new BiometryService(
56+
useOperationPrompt: "TODO: Subtitle",
57+
laContext: null,
58+
localAuthenticationPolicy: LAPolicy.DeviceOwnerAuthenticationWithBiometrics,
59+
loggerFactory: null
60+
);
61+
```
62+
63+
1. Use `ScanBiometry` to prompt the native experience.
64+
This will use automaticaly use the native biometric service of that device (FaceID, TouchID, Android Fingerprint, ect.).
65+
66+
``` csharp
67+
try
68+
{
69+
await _biometryService.ScanBiometry(CancellationToken.None);
70+
// TODO: Handle the case when biometry is recognized.
71+
}
72+
catch (BiometryException biometryException)
73+
{
74+
// TODO: Handle the case when biometry is not recognized.
75+
Console.WriteLine($"{biometryException.Reason} : {biometryException.Message}");
76+
}
77+
```
78+
79+
## Notes on Instantiation
80+
81+
### Android
82+
- 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).
83+
84+
- 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.
85+
86+
- 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.
87+
88+
### iOS
89+
90+
- The `laContext` parameter (local authentication context) can be set by creating a new [LAContext](https://developer.apple.com/documentation/localauthentication/lacontext#2930204).
91+
``` csharp
92+
var laContext = new LAContext
93+
{
94+
LocalizedReason = "This app wants to use biometry for ...",
95+
LocalizedFallbackTitle = "Fallback Title",
96+
LocalizedCancelTitle = "Cancel Title"
97+
};
98+
```
99+
- Please note that the subtitle passed via `useOperationPrompt` is only displayed on devices using TouchID.
46100

47-
Please also note that the title and subtitle are used for `Fingerprint` and `Face` biometry.
48-
49-
Here is an example of instantiation of the service for Android.
50-
51-
``` cs
52-
var promptBuilder = () => new BiometricPrompt.PromptInfo.Builder()
53-
.SetTitle("Title")
54-
.SetSubtitle("Subtitle")
55-
.SetNegativeButtonText("Cancel")
56-
.SetAllowedAuthenticators(AndroidX.Biometric.BiometricManager.Authenticators.BiometricStrong)
57-
.Build();
58-
59-
var biometryService = new BiometryService(
60-
fragmentActivity: MainActivity.Instance,
61-
promptInfoBuilder: promptBuilder,
62-
loggerFactory: null
63-
);
64-
```
101+
## Features
65102

66-
#### iOS
103+
### Platform Compatibilities
67104

68-
Please note that you must set `NSFaceIDUsageDescription` (key/value) in the `Info.plist` file otherwise the service will throw an exception.
105+
The `IBiometryService` has severals methods.
69106

70-
Please also note that the prompt builder subtitle is used for `Fingerprint` biometry only.
107+
As of now, this is the list of features available per platform.
71108

72-
Here is an example of instantiation of the service for iOS.
109+
| Methods | iOS | Android | WinUI | UWP |
110+
| ---------------- | :-----: | :-----: | :-----: | :-----: |
111+
| `GetCapability` | ✔ | ✔ | ✔ | ✔ |
112+
| `ScanBiometry` | ✔ | ✔ | ✔ | ✔ |
113+
| `Encrypt` | ✔ | ✔ | ✔ | ✔ |
114+
| `Decrypt` | ✔ | ✔ | ❌ | ❌ |
115+
| `Remove` | ✔ | ✔ | ✔ | ✔ |
73116

74-
``` cs
75-
_biometryService = new BiometryService(
76-
useOperationPrompt: "Subtitle",
77-
laContext: null,
78-
localAuthenticationPolicy: LAPolicy.DeviceOwnerAuthenticationWithBiometrics,
79-
loggerFactory: null
80-
);
81-
```
82117

83-
## Methods
118+
### Error Handling
84119

85-
Please note that in case of error, `BiometryException` is thrown.
120+
Please note that in case of error, a `BiometryException` is thrown.
86121

87122
Biometry Exception Types:
88123
- `Failed`: Any other failures while trying to use the device biometrics.
@@ -101,66 +136,58 @@ If it's a cancellation error, `OperationCanceledException` is thrown.
101136

102137
### GetGapabilites
103138

104-
Gets the device's current biometric capabilities.
139+
This method gets the device's current biometric capabilities.
105140

106-
It will return a struct `BiometryCapabilities` with the detailled device configuration.
141+
It returns a struct `BiometryCapabilities` with the detailed device configuration.
107142

108143
### ScanBiometry
109144

110-
Attemps to scan the user's biometry.
145+
This method attemps to scan the user's biometry.
111146

112147
``` cs
113-
await biometryService.ScanBiometry(cancellationToken);
148+
await biometryService.ScanBiometry(CancellationToken.None);
114149
```
115150

116151
### Encrypt
117152

118-
Encrypts the value and stores it into the platform secure storage with the given key name.
153+
This method encrypts a value and stores it into the platform secure storage with the given key name.
119154

120155
``` cs
121-
await biometryService.Encrypt(cancellationToken, "KeyName", "KeyValue");
156+
await biometryService.Encrypt(CancellationToken.None, "KeyName", "KeyValue");
122157
```
123158

124-
#### Android
159+
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.
160+
The final step encodes the data in base64 and stores it in the shared preferences.
125161

126-
A new `CryptoObject` from `AndroidX.Biometric` is created with a key as a parameter. Then the data will be encrypted and presented to the `BiometricPrompt` manager.
127-
The final step will encode the data in base64 and store it in App with the shared preferences.
128-
129-
#### iOS
130-
131-
The `SecKeyChain` will be used to store a string linked to a key. The OS is in charge of securing the data with biometric authentication during the process.
162+
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.
132163

133164
### Decrypt
134165

135-
Decrypts and gets the data associated to the given key name.
166+
This method decrypts and gets the data associated to the given key.
136167

137168
``` cs
138-
await biometryService.Decrypt(cancellationToken, "KeyName");
169+
await biometryService.Decrypt(CancellationToken.None, "KeyName");
139170
```
140171

141-
#### Android
142-
143-
Retrieve the shared preference encrypted data, then decrypt it with the secret as a parameter by presenting it to the `BiometricPrompt` manager.
144-
145-
#### iOS
172+
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.
146173

147-
Retrieve 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.
174+
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.
148175

149176
### Remove
150177

151-
Removes the ecrypted value in the platform secure storage.
178+
This method removes the ecrypted value from the platform secure storage.
152179

153180
``` cs
154181
biometryService.Remove("KeyName");
155182
```
156183

157-
#### Android
184+
On Android, the method removes the encrypted data from the shared preferences.
158185

159-
Remove the encrypted data from the shared preferences.
186+
On iOS, the method removes the encrypted data from the `SecKeyChain`.
160187

161-
#### iOS
188+
## Breaking Changes
162189

163-
Remove the encrypted data from the `SecKeyChain`.
190+
Please consult the [BREAKING CHANGES](BREAKING_CHANGES.md) for more information about breaking changes history.
164191

165192
## Changelog
166193

@@ -177,10 +204,4 @@ This project is licensed under the Apache 2.0 license - see the
177204
Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on the process for
178205
contributing to this project.
179206

180-
Be mindful of our [Code of Conduct](CODE_OF_CONDUCT.md).
181-
182-
## Contributors
183-
184-
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
185-
186-
<!-- ALL-CONTRIBUTORS-LIST:END -->
207+
Be mindful of our [Code of Conduct](CODE_OF_CONDUCT.md).

‎src/BiometryService.Abstractions/BiometryService.Abstractions.csproj‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,10 @@
88
<AssemblyName>BiometryService.Abstractions</AssemblyName>
99
<PackageId>BiometryService.Abstractions</PackageId>
1010
<Description>BiometryService.Abstractions</Description>
11+
<GenerateDocumentationFile>true</GenerateDocumentationFile>
1112
<PackageLicenseExpression>Apache-2.0</PackageLicenseExpression>
1213
<PackageProjectUrl>https://github.com/nventive/BiometryService</PackageProjectUrl>
13-
<GenerateDocumentationFile>true</GenerateDocumentationFile>
14+
<PackageReadmeFile>README.md</PackageReadmeFile>
1415
<PackageTags>biometry;mvvm;maui;winui;ios;android;xamarin;uwp</PackageTags>
1516
</PropertyGroup>
1617

@@ -26,4 +27,11 @@
2627
<ItemGroup>
2728
<PackageReference Include="Microsoft.SourceLink.GitHub" Version="1.1.1" PrivateAssets="All" />
2829
</ItemGroup>
30+
31+
<ItemGroup>
32+
<None Include="..\..\README.md">
33+
<Pack>True</Pack>
34+
<PackagePath>\</PackagePath>
35+
</None>
36+
</ItemGroup>
2937
</Project>

‎src/BiometryService/BiometryService.csproj‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
<PackageTags>biometry;mvvm;maui;winui;ios;android;xamarin;uwp</PackageTags>
1313
<PackageLicenseExpression>Apache-2.0</PackageLicenseExpression>
1414
<PackageProjectUrl>https://github.com/nventive/BiometryService</PackageProjectUrl>
15+
<PackageReadmeFile>README.md</PackageReadmeFile>
1516
<DefineConstants Condition="'$(TargetFramework)'=='net6.0-windows10.0.19041'">$(DefineConstants);__WINDOWS__</DefineConstants>
1617
</PropertyGroup>
1718

@@ -45,6 +46,13 @@
4546
<PackageReference Include="Xamarin.AndroidX.RecyclerView" Version="1.2.1.7" />
4647
</ItemGroup>
4748

49+
<ItemGroup>
50+
<None Include="..\..\README.md">
51+
<Pack>True</Pack>
52+
<PackagePath>\</PackagePath>
53+
</None>
54+
</ItemGroup>
55+
4856
<ItemGroup>
4957
<ProjectReference Include="..\BiometryService.Abstractions\BiometryService.Abstractions.csproj" />
5058
</ItemGroup>

0 commit comments

Comments
 (0)