Giter Club home page Giter Club logo

nativescript-keystore-access's Introduction

Nativescript Keystore Access Build Status License: MIT

Also works with Face ID on iPhone X Requires Xcode 9+, iOS 11 SDK

Icon made by surang from www.flaticon.com is licensed by CC 3.0 BY

Installation

From the command prompt go to your app's root folder and execute:

tns plugin add nativescript-keystore-access

WARNING

You must always make sure you call cleanup() when you leave/finish the context where you are using the plugin. This is because of the way the Android FingerprintManager works. If you have the Android FingerprintManager listening for fingerprint and you leave the context or even closes the app or crash the app, you may have a defunct FingerprintManager still listening for fingerprint, and then if you start the app again or any other app that uses fingerprint, this will fail because of the still listening defunct FingerprintManager. It is therefore important to hook into ngOnDestroy() on any component using this plugin an call cleanup() here.

API

available

Call this method to check if biometrics is available on your device. Always call this method and check the result before calling any other method.

TypeScript

import { KeystoreAccess, BiometricIDAvailableResult } from "nativescript-keystore-access";

class MyClass {
  private keystoreAccess: KeystoreAccess;

  constructor() {
    this.keystoreAccess = new KeystoreAccess();
  }

  this.keystoreAccess.available().then((result: BiometricIDAvailableResult) => {
    console.log(`Biometric ID available? ${result.any}`);
    console.log(`Touch? ${result.touch}`);
    console.log(`Face? ${result.face}`);
    if (result.customUI) {
        // You must show a custom biometrics UI, basicly this means you are on Android and the OS does not show a UI for you.
        // You can at any time call `useCustomUI` to check if you should show a custom biometrics UI.
    }
  }).catch(err => {
    console.log("doCheckAvailable error: " + err.code + ", " + err.message);
  });
}

useCustomUI

Call this method to check if you must show a custom biometrics UI to inform the user that the device is witing for a fingerprint.

TypeScript

import { KeystoreAccess } from "nativescript-keystore-access";

class MyClass {
  private keystoreAccess: KeystoreAccess;

  constructor() {
    this.keystoreAccess = new KeystoreAccess();
  }

  if (this.keystoreAccess.useCustomUI()) {
    // You must show a custom biometrics UI, basicly this means you are on Android and the OS does not show a UI for you.
    // You can at any time call `useCustomUI` to check if you should show a custom biometrics UI.
  }
}

storeDataWithFingerprint

Call this method to have some string data encrypted with the device keystore in a way so that it can only be decrypted with biometrics authentication.

TypeScript

import { KeystoreAccess } from "nativescript-keystore-access";

class MyClass {
  private keystoreAccess: KeystoreAccess;

  constructor() {
    this.keystoreAccess = new KeystoreAccess();
  }

  // Remember to call "useCustomUI()" and show some UI that is indicating to the user that the device is awaiting a fingerprint.
  this.keystoreAccess.storeDataWithFingerprint(
      keystoreKeyAlias: "ALIAS", // A unique id for your data, use the same key for encryption and decryption of the same data, and another key for different data.
      data: "This is a secret", // The string you want to encrypt and store.
      biometricMessage: "Biometric Message" // A short description that will show up on the iOS biometrics dialog.
    ).then((result: void) => {
    console.log("Your secret is safe with me");
    // You can now remove your custom biometrics UI
  }).catch(err => {
    console.log("storeDataWithFingerprint error: " + err.code + ", " + err.message);
    // Inform the user of the error, that may or may not be recoverable, on your custom biometrics UI
  });
}

retrieveDataWithFingerprint

Call this method to retrieve previously encrypted and stored data as a decrypted string.

TypeScript

import { KeystoreAccess } from "nativescript-keystore-access";

class MyClass {
  private keystoreAccess: KeystoreAccess;

  constructor() {
    this.keystoreAccess = new KeystoreAccess();
  }

  // Remember to call "useCustomUI()" and show some UI that is indicating to the user that the device is awaiting a fingerprint.
  this.keystoreAccess.retrieveDataWithFingerprint(
      keystoreKeyAlias: "ALIAS", // A unique id for your data, use the same key for encryption and decryption of the same data, and another key for different data.
      biometricPromptMessage: "Biometric Prompt Message" // A short description that will show up on the iOS biometrics dialog.
    ).then((result: string) => {
    console.log("I just unlocked your secret: " + result);
    // You can now remove your custom biometrics UI
  }).catch(err => {
    console.log("retrieveDataWithFingerprint error: " + err.code + ", " + err.message);
    // Inform the user of the error, that may or may not be recoverable, on your custom biometrics UI
  });
}

fingerprintEncryptedDataExists

Call this method to check if you have encrypted data stored on this device.

TypeScript

import { KeystoreAccess } from "nativescript-keystore-access";

class MyClass {
  private keystoreAccess: KeystoreAccess;

  constructor() {
    this.keystoreAccess = new KeystoreAccess();
  }

  if (this.keystoreAccess.fingerprintEncryptedDataExists(
    keystoreKeyAlias: "ALIAS" // A unique id for your data, use the same key for encryption and decryption of the same data, and another key for different data.
  )) {
    console.log("You have encrypted data store on this device, go ahead and retrieve it if you like");
  )
}

deleteFingerprintEncryptedData

Call this method to delete any existing encrypted data stored on this device.

TypeScript

import { KeystoreAccess } from "nativescript-keystore-access";

class MyClass {
  private keystoreAccess: KeystoreAccess;

  constructor() {
    this.keystoreAccess = new KeystoreAccess();
  }

  this.keystoreAccess.deleteFingerprintEncryptedData(
    keystoreKeyAlias: "ALIAS" // A unique id for your data, use the same key for encryption and decryption of the same data, and another key for different data.
  );
}

Error Codes

The iOS and Android biometrics SDK are very different and reports errors very differently. To make the usage of this plugin predictable without knowing what platform you are on, all error types have been mapped to one common finite list of error codes. The error codes are the following:

enum ERROR_CODES {
  RECOVERABLE_ERROR_BIOMETRICS_NOT_RECOGNIZED = 102, // Biometrics are working and configured correctly, but the biometric input was not recognized
  RECOVERABLE_ERROR_FINGER_MOVED_TO_FAST = 102, // Finger moved to fast on the fingerprint sensor (only Android)
  RECOVERABLE_ERROR_FINGER_MUST_COVER_SENSOR = 101, // Finger must cover entire sensor (only Android)
  DEVELOPER_ERROR = 10, // Unexpected error, report to maintainer of plugin please
  NOT_AVAILABLE = 20, // Biometrics are not available on device
  TAMPERED_WITH = -5, // Biometrics was changed (added or removed) since last successful authentication, maybe a hacker was on your device
  AUTHENTICATION_FAILED = -1, // Biometrics are working and configured correctly, but the biometric input was not recognized
  CANCEL = -2 // Biometric authentication was canceled, probably by user
}

Face ID (iOS)

iOS 11 added support for Face ID and was first supported by the iPhone X. The developer needs to provide a value for NSFaceIDUsageDescription, otherwise your app may crash.

You can provide this value (the reason for using Face ID) by adding something like this to app/App_Resources/ios/Info.plist:

  <key>NSFaceIDUsageDescription</key>
  <string>For easy authentication with our app.</string>

License

This software is available under the MIT license.

nativescript-keystore-access's People

Contributors

langecode avatar

Stargazers

Philipp Huth avatar Rasmus Holm Andersen avatar

Watchers

Kim Dalsgaard avatar Anders Skarby avatar Anders Bloch avatar Alexis Thaveau avatar  avatar James Cloos avatar Henrik Stokbro avatar Peter Lindholm avatar David Dyrholm avatar  avatar Alexander Hafstad avatar Peter Bugge Jakobsen avatar Martin Vindahl Olsen avatar Peter Ring avatar Gagandeep Sharma avatar Lone Vestergaard avatar Philipp Huth avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.