Skip to content

Commit 0b92dd2

Browse files
OmbuwebOmbuweb
authored
docs(biometrics): update (#438)
1 parent 7d6ac9e commit 0b92dd2

File tree

1 file changed

+85
-61
lines changed

1 file changed

+85
-61
lines changed

‎packages/biometrics/README.md

+85-61
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,28 @@
11
# @nativescript/biometrics
22

3+
## Contents
4+
* [Intro](#intro)
5+
* [Installation](#installation)
6+
* [Use @nativescript/biometrics](#use-nativescriptbiometrics)
7+
* [Check if the device supports biometrics authentification](#check-if-the-device-supports-biometrics-authentification)
8+
* [Biometrics authentification support on Android](#biometrics-authentification-support-on-android)
9+
* [Face ID authentification support on iOS](#face-id-authentification-support-on-ios)
10+
* [Verify user biometrics](#verify-user-biometrics)
11+
* [API](#api)
12+
* [BiometricAuth class](#biometricauth-class)
13+
* [BiometricIDAvailableResult interface](#biometricidavailableresult-interface)
14+
* [IOSOptions interface](#iosoptions-interface)
15+
* [Android interface](#androidoptions-interface)
16+
* [BiometricResult interface](#biometricresult-interface)
17+
* [ERROR_CODES Enum](#error_codes-enum)
18+
* [License](#license)
19+
20+
## Intro
21+
A plugin that allows you to authenticate users with biometrics, such as fingerprints, facial recognition, etc.
22+
23+
> **Note**
24+
This plugin replaces [@nativescript/fingerprint-auth](../fingerprint-auth).
25+
326
## Installation
427

528
```cli
@@ -8,54 +31,50 @@ npm install @nativescript/biometrics
831
> **Note**
932
This plugin replaces [@nativescript/fingerprint-auth](../fingerprint-auth).
1033

34+
## Use the @nativescript/biometrics plugin
35+
36+
### Check if the device supports biometrics authentification
1137

12-
## Usage
38+
To check if the device supports biometrics authentication, call the `available()` method on a `BiometricAuth` instance.
1339

14-
### Importing
15-
To use the plugin, you should first import it.
1640
```ts
1741
import { BiometricAuth, BiometricIDAvailableResult } from "@nativescript/biometrics";
1842

19-
```
20-
### Checking for support
21-
22-
To check if the device supports biometrics authentication, call the `available()` method.
23-
24-
```js
2543
var biometricAuth = new BiometricAuth();
2644

27-
biometricAuth.available().then(function (avail) {
28-
console.log('Available? ' + avail);
45+
biometricAuth.available().then((result: BiometricIDAvailableResult) => {
46+
console.log(`Biometric ID available? ${result.any}`);
47+
console.log(`Touch? ${result.touch}`);
48+
console.log(`Face? ${result.face}`);
49+
console.log(`Biometrics? ${result.biometrics}`);
50+
2951
});
52+
3053
```
31-
```typescript
32-
class MyClass {
33-
private biometricAuth: BiometricAuth;
34-
35-
constructor() {
36-
this.biometricAuth = new BiometricAuth();
37-
38-
this.biometricAuth.available().then((result: BiometricIDAvailableResult) => {
39-
console.log(`Biometric ID available? ${result.any}`);
40-
console.log(`Touch? ${result.touch}`);
41-
console.log(`Face? ${result.face}`);
42-
console.log(`Biometrics? ${result.biometrics}`);
43-
});
44-
}
45-
46-
47-
}
54+
55+
#### Biometrics authentification support on Android
56+
57+
- It's only supported on `API 23+`.
58+
- In some devices, the OS does not consider face recognition secure enough and as a result, your app cannot use it for biometric authentication.
59+
This is the case with many Samsung devices. For example, Samsung Galaxy S10 ha Consequently, if the device has Face Recognition enabled and face scan saved, `available()` returns `{ any: true, biometrics: false }`.
60+
61+
#### Face ID authentification support on iOS
62+
63+
- It is only supported in iOS 11+.
64+
65+
- To allow Face ID support in your app, provide the reason of supporting it as the value of the `NSFaceIDUsageDescription` key in the `app/App_Resources/ios/Info.plist` file:
66+
67+
```xml
68+
<key>NSFaceIDUsageDescription</key>
69+
<string>For easy authentication with our app.</string>
4870
```
49-
> **Note: Android**
50-
It's only supported on `API 23+`. <br> <br>In some devices, face recognition isn't considered secure enough by the system to be used as biometric authentication,therefore it cannot be used for biometric authentication. This is decided by the device itself.
51-
This is the case in many Samsung devices. For example, Samsung Galaxy S10 has both fingerprint scanner and face recognition but only fingerprints are accepted as biometric authentication. <br> <br>So what happens is: <br>- If the device has Face Recognition enabled and face scan saved,calling `available()` returns `{ any: true, biometrics: false }`. You might expect the device to show Face Recognition when you call `verifyBiometric()` but Samsung does not consider Face Recognition secure on this device so you'll never be prompted. <br>- If you enroll a fingerprint in the Touch Recognition and call the `verifyBiometric()` method, the user will be prompted for the fingerprint scan.
71+
- On a simulator, to enroll a face and test Face ID authentification, use the `Features->Face ID` menu items.
5272

53-
### Verifying a user's biometric
73+
### Verify user biometrics
5474

55-
To verify a user's biometric, call the `verifyBiometric()` method.
75+
To verify user biometrics, call the `verifyBiometric()` method and pass it a [VerifyBiometricOptions](#verifybiometricoptions) object.
5676

5777
> **Note: iOS**
58-
Use `Features->Face ID` menu items to enroll a face and signal a successs/failure to recognize a face.
5978
`verifyBiometric()` will fail on IOS simulator unless the `pinfallBack` option is used.
6079

6180
```typescript
@@ -74,22 +93,14 @@ biometricAuth
7493
.catch((err) => console.log(`Biometric ID NOT OK: ${JSON.stringify(err)}`));
7594
```
7695

77-
### Requirements for Face ID Auth (iOS)
7896

79-
Support for Face ID was added in iOS 11+. To allow Face ID support in your app, you need to state the reason for it by adding the value for the `NSFaceIDUsageDescription` key to the `app/App_Resources/ios/Info.plist` file:
97+
### Detect change in enrolled fingerprints (iOS)
8098

81-
```xml
82-
<key>NSFaceIDUsageDescription</key>
83-
<string>For easy authentication with our app.</string>
84-
```
85-
86-
### Detecting change in enrolled fingerprints (iOS)
99+
For iOS 9+ you can check if enrolled fingerprints have changed since
100+
the last time you checked it. It's recommended you add this check to counter hacker attacks
101+
on your app. For more details, see [this article](https://www.linkedin.com/pulse/fingerprint-trojan-per-thorsheim/).
87102

88-
Since iOS 9 you can check if there is a change in enrolled fingerprints since
89-
the last time you checked it. It's recommended you add this check so you can counter hacker attacks
90-
to your app. See [this article](https://www.linkedin.com/pulse/fingerprint-trojan-per-thorsheim/) for more details.
91-
92-
To check if there is a change in enrolled fingerprints, call the `didBiometricDatabaseChange()` method. If it returns `true`, you probably want to re-authenticate your user
103+
To check if enrolled fingerprints have changed, call the `didBiometricDatabaseChange()` method. If it returns `true`, you probably want to re-authenticate your user
93104
before accepting valid fingerprints again.
94105

95106
```typescript
@@ -109,19 +120,24 @@ biometricAuth.available().then((avail) => {
109120

110121
## Biometrics and cryptography
111122

112-
### Normal operation
123+
To combine biometrics authentification with cryptography, for more secure data protection, set the `secret` and `keyName` options when you call `verifyBiometric()`.
124+
125+
If you do not pass the `pinFallback` or `keyName` options to the `verifyBiometric()` method, the plugin will automatically:
126+
1. create a secure key
127+
2. prompts the user to authenticate for a face/fingerprint
128+
3. attempts to use the key to encrypt some text.
113129

114-
If you do not pass the `pinFallback` or `keyName` options to the `verifyBiometric()` method, then the plugin will create a secure key, call the authorization methods to trigger face/fingerprint and then attempt to use the key to encrypt some text. The idea being that the key will not be accessible unless the user has successfully authenticated.
130+
That automatic key generation, however, is not foolproof.
115131

116-
This ,however, is not foolproof and the most secure method is to pass the `secret` and `keyName`options to encrypt/decrypt text.
117132

118-
### Encrypting/Decrypting with Authentication
133+
### Encrypting/Decrypting with biometrics authentication
119134

120135
The best practice is to use the options to encrypt some secret that is validated independently.
121136

122137
#### Encrypting your secret
123138

124-
To encrypt a secret key name, pass the `secret` and `keyName`options to the `verifyBiometric()` method.
139+
140+
To encrypt some sensitive string, pass the `secret` and `keyName`options to the `verifyBiometric()` method. Set the sensitive string as the `secret` property's value and the name of the key to access that secret as the value of the `keyName` property.
125141

126142
```typescript
127143
biometricAuth
@@ -141,7 +157,7 @@ biometricAuth
141157
.catch((err) => this.set('status', `Biometric ID NOT OK: " + ${JSON.stringify(err)}`));
142158
```
143159

144-
For Android the encrypted result and vector would then be stored in your app and used the next time when signing in the user by calling `verifyBiometric()` again:
160+
For Android, the encrypted and initialization vector is then stored in your app and used each time when signing in the user with `verifyBiometric()`:
145161

146162
#### Decrypting your secret
147163

@@ -165,9 +181,10 @@ biometricAuth
165181
.catch((err) => this.set('status', `Biometric ID NOT OK: " + ${JSON.stringify(err)}`));
166182
```
167183

168-
### Fallback to Pin
184+
#### Fallback to Pin
185+
186+
To allow biometrics authentification to fallback on lock screen credentials, set `pinFallback` to `true`. Note that thissetting also disables cryptography.
169187

170-
To allow the user to fallback on lock screen credentials, set `pinFallback` to `true`. This also disables cryptography.
171188

172189
```typescript
173190
biometricAuth
@@ -187,23 +204,26 @@ biometricAuth
187204
## API
188205

189206
### BiometricAuth Class
207+
190208
| Name | Return Type | Description|
191209
|-----|-------|-----------|
192210
|`available()`|`Promise<BiometricIDAvailableResult>`| Checks if biometric authentification is supported on the device. See [BiometricIDAvailableResult](#biometricidavailableresult) for more details.|
193211
| `didBiometricDatabaseChange(options?: VerifyBiometricOptions)`|`Promise<boolean>` | Checks if there is a change in a biometric of the user.|
194212
| `verifyBiometric(options: VerifyBiometricOptions)`|`Promise<BiometricResult>`| Verifies the biometrics auth using the specified [VerifyBiometricOptions](#verifybiometricoptions) object. |
195-
| `close()` | `void`| Closes Face/Fingerprint prompt. Will not do anything on Android if `pinFallBack` is `true`.|
213+
| `close()` | `void`| Closes Face/Fingerprint prompt. If `pinFallBack` is `true`, `close()` does not have effect on Android.|
196214
| `deleteKey(keyName?: string)`|`void`| Deletes the specified key. |
197215

198-
### BiometricIDAvailableResult
216+
### BiometricIDAvailableResult interface
217+
199218
| Name | Type| Description|
200219
|------|-----|------------|
201220
| `any`| `boolean`| `true` if no biometric authentification is available on android but device has pin/pattern/password set.|
202221
| `touch`| `boolean`| _Optional_: `iOS only`|
203222
| `face`| `boolean`| _Optional_: `iOS only`|
204223
| `biometrics` | `boolean` | _Optional_: (`Android only`) indicates if Face/Fingerprint is available.|
205224

206-
### VerifyBiometricOptions
225+
### VerifyBiometricOptions interface
226+
207227
| Name | Type| Description|
208228
|------|-----|------------|
209229
| `title`| `string`| _Optional_: (`Android only`)The title for the the fingerprint screen. Defaults to whatever the device default is.|
@@ -216,21 +236,25 @@ biometricAuth
216236
| `android` | [AndroidOptions](#androidoptions) | _Optional_: Android-specific options. |
217237
| `ios`| [IOSOptions](#iosoptions) | _Optional_: iOS-specific options. |
218238

219-
### IOSOptions
239+
### IOSOptions interface
240+
220241
| Name | Type| Description|
221242
|------|-----|------------|
222243
| `customFallback` | `boolean` | _Optional_: Indicates whether to allow a custom fallback from biometrics.|
223244
| `fetchSecret` | `boolean` | _Optional_: Indicates whether to attempt to fetch secret from the specified key.|
224245

225-
### AndroidOptions
246+
### AndroidOptions interface
247+
226248
| Name | Type| Description|
227249
|------|-----|------------|
228250
| `decryptText` | `string`| If set and `pinFallback` is `true`, and `keyName` is set then this string will be decrypted via the Biometric controlled Key. |
229251
If set and pinFallback is true, and keyName is set then this string will be decrypted via the Biometric controlled Key.|
230252
| `iv`| `string` | _Optional_: Retrieved from the result of an encryption. |
231253
| `validityDuration` | `number` | _Optional_: The period, in seconds, for which operations on the key are valid without triggering a biometric prompt.|
232254

233-
### BiometricResult
255+
256+
### BiometricResult interface
257+
234258
| Name | Type| Description|
235259
|------|-----|------------|
236260
|`code`| [ERROR_CODES](#error_codes-enum) |

0 commit comments

Comments
 (0)