Biometric Sensor SDK. Integration Guide 4.17

Transcription

1 Biometric Sensor SDK Integration Guide 4.17

2 Disclaimer Disclaimer of Warranties and Limitations of Liabilities Legal Notices Copyright VASCO Data Security, Inc., VASCO Data Security International GmbH. All rights reserved. Trademarks VASCO, VACMAN, IDENTIKEY, axsguard, DIGIPASS, CertiID, CRONTO, MYDIGIPASS.COM, the MYDIGIPASS.COM MD Lock logo, the DP+ logo, the VASCO V logo and the CRONTO logo are registered or unregistered trademarks of VASCO Data Security, Inc. and/or VASCO Data Security International GmbH in the U.S. and other countries. VASCO reserves all rights to the trademarks, service marks and logos of VASCO and its subsidiaries. Intellectual Property VASCO Software, documents and related materials ( Materials ) made available on the Site contain proprietary and confidential information. All title, rights and interest in VASCO Software and Materials, updates and upgrades thereof, including software rights, copyrights, patent rights, trade secret rights, sui generis database rights, and all other intellectual and industrial property rights, vest exclusively in VASCO or its licensors. No VASCO Software or Materials published in this Site may be downloaded, copied, transferred, disclosed, reproduced, redistributed, or transmitted in any form or by any means, electronic, mechanical or otherwise, for any commercial or production purpose, except as otherwise marked or when expressly permitted by VASCO in writing. Disclaimer VASCO accepts no liability for the accuracy, completeness, or timeliness of Site content, or for the reliability of links to and content of external or third party websites. VASCO shall have no liability under any circumstances for any loss, damage, or expense incurred by you, your company, or any third party arising from the use or inability to use VASCO Software or Materials, or any third party material available or downloadable from the Site. VASCO will not be liable in relation to any loss/damage caused by modification of these Legal Notices or Site content. Reservation VASCO reserves the right to modify these Notices and the content at any time. VASCO likewise reserves the right to withdraw or revoke consent or otherwise prohibit use of the VASCO Software or Materials if such use does not conform to the terms of any written agreement between VASCO and you, or other applicable terms that VASCO publishes from time to time. Date:

3 Table of Contents Table of Contents 1 Introduction Introducing the Biometric Sensor SDK Overview Available methods Check biometric authentication support by the platform Check biometric authentication applicability Start biometric authentication of user Stop biometric authentication of user Integrating the Biometric Sensor SDK Integrating the Biometric Sensor SDK with ios Integrating the Biometric Sensor SDK with Android Known Issues Technical Support

4 Table of Contents Index of Tables Table 1: Method Signature (Checking Biometric Authentication Support by the Platform)... 8 Table 2: Method Signature (Checking Biometric Authentication Applicability)... 8 Table 3: Methods Signature (Verifying the User s Fingerprint on Android with built-in Dialog)... 9 Table 4: Methods Signature (Verifying the User s Fingerprint on Android without built-in Dialog)... 9 Table 5: Methods Signature (Callbacks for User s Fingerprint Verification) Table 6: Dialog Popup Customization Attributes Table 7: Method Signature (Start Biometric Authentication on ios) Table 8: Method Signature (Stop Biometric Authentication)

5 Introduction 1 Introduction Welcome to the Biometric Sensor SDK Integration Guide! This document provides information about: Functions of the Biometric Sensor SDK, with parameter and method descriptions Integration steps This document does not provide: An overview of DIGIPASS for APPS 1 and its components (refer to the DIGIPASS for APPS Product Guide) Instructions to integrate the Client Device Data Collector (CDDC) SDK (refer to the CDDC SDK Integration Guide) Instructions to integrate the Client Score SDK (refer to the Client Score SDK Integration Guide) Instructions to integrate the Device Binding SDK (refer to the Device Binding SDK Integration Guide) Instructions to integrate the DIGIPASS Bluetooth Token SDK (refer to the DIGIPASS Bluetooth Token SDK Integration Guide) Instructions to integrate the DIGIPASS SDK (refer to the DIGIPASS SDK Integration Guide) Instructions to integrate the DIGIPASS Software Advanced Provisioning Protocol (DSAPP) SDK (refer to the DSAPP SDK Integration Guide) Instructions to integrate the Face Recognition SDK (refer to the Face Recognition SDK Integration Guide) Instructions to integrate the Geolocation SDK (refer to the Geolocation SDK Integration Guide) Instructions to integrate the Image Generator SDK (refer to the Image Generator SDK Integration Guide) Instructions to integrate the Image Scanner SDK (refer to the Image Scanner SDK Integration Guide) Instructions to integrate the Notification SDK (refer to the Notification SDK Integration Guide) Instructions to integrate the Root Detection SDK (refer to the Root Detection SDK Integration Guide) Instructions to integrate the Runtime Application Security Protection (RASP) SDK (refer to the RASP SDK Integration Guide) Instructions to integrate the Secure Messaging SDK Client (refer to the Secure Messaging SDK Client Integration Guide) Instructions to integrate the Secure Messaging SDK Server (refer to the Secure Messaging SDK Server Integration Guide) Instructions to integrate the Secure Storage SDK (refer to the Secure Storage SDK Integration Guide) Instructions to integrate the White-Box Cryptography (WBC) SDK (refer to the White-Box Cryptography SDK Integration Guide) 1 As of version 4.3.2, the package name of the DIGIPASS SDK has been changed to DIGIPASS for APPS. 5

6 Introducing the Biometric Sensor SDK 2 Introducing the Biometric Sensor SDK This chapter contains an overview of the Biometric Sensor SDK and information about the SDK s functions. This chapter covers the following topics: Overview Available methodsoverview 6

7 Introducing the Biometric Sensor SDK 2.1 Overview The Biometric Sensor SDK provides facilities to use biometric authentication to increase user convenience during the identification process while retaining a secure solution. It also provides methods to test whether biometric authentication is supported by the platform and has been enabled by the user before actually performing biometric authentication. The following biometric authentication methods are supported: Fingerprint recognition, Android and ios (with Touch ID) Face recognition, ios only (with Face ID) The Biometric Sensor SDK can be used on devices with a biometric sensor for the following platforms: Android devices: 6.0 and later Samsung Android devices: 4.2 and later ios devices: 7.0 and later The Biometric Sensor SDK includes the following: A framework named BiometricSensorSDK.framework for ios A JAR file named BiometricSensorSDK.jar for Android 7

8 Introducing the Biometric Sensor SDK 2.2 Available methods Check biometric authentication support by the platform This function checks whether the biometric authentication feature is supported by the platform. Both hardware and software need to support them. Table 1: Method Signature (Checking Biometric Authentication Support by the Platform) Platform ios Android Method Signature +(BOOL) isbiometricauthenticationsupportedbyplatform: (BiometricAuthenticationMethod) biometricauthenticationmethod; public static boolean isuserfingerprintsupportedbyplatform; Check biometric authentication applicability This function checks whether the biometric authentication feature is currently usable on the device, i.e. supported by the platform and enabled by the user with at least one user biometric data registered (e.g. fingerprint). Table 2: Method Signature (Checking Biometric Authentication Applicability) Platform ios Android Method Signature +(BOOL) isbiometricauthenticationmethodusable: (BiometricAuthenticationMethod) biometricauthenticationmethod; public static boolean isuserfingerprintusable(); 8

9 Introducing the Biometric Sensor SDK Start biometric authentication of user Android This function uses the biometric authentication features of the device to validate the user s biometric data (e.g. fingerprint). On Android, a dialog must be implemented and displayed by the application during the identification process. The Biometric Sensor SDK provides two methods to verify the user s fingerprint: A method which displays a dialog handled by the Biometric Sensor SDK. The look of the dialog is customizable, e.g. text, color, icon, etc. (see (b) Dialog customization). Table 3: Methods Signature (Verifying the User s Fingerprint on Android with built-in Dialog) Method Signature public static void verifyuserfingerprint(biometricsensorsdklistener listener, Activity activity, BiometricSensorSDKDialogParams params); A method which doesn t display any dialog. It s up to the application integrating the Biometric Sensor SDK to build and display a respective dialog. Table 4: Methods Signature (Verifying the User s Fingerprint on Android without built-in Dialog) Method Signature public static void verifyuserfingerprint(biometricsensorsdklistener listener, Activity activity); 9

10 Introducing the Biometric Sensor SDK (a) Verification callback functions A listener must be implemented and provided as an input parameter of the verification method in order to receive the callbacks related to the user s fingerprint verification: Table 5: Methods Signature (Callbacks for User s Fingerprint Verification) Method Signature Description void onfingerprintscansucceeded() Called if verification was successful void onfingerprintscanfailed(int Called if verification failed (e.g. wrong user s fingerprint failcode, String failstring) or quality issue) void onfingerprintscancancelled() Called if the user cancels the verification void onfingerprintscanerror(int Called if an error occurred during user s fingerprint errorcode, String errorstring) verification (e.g. locked or time-out) The string returned by the callback methods are generated by the OS and are localized according to the device language, they can be displayed as it to the user. 10

11 Introducing the Biometric Sensor SDK (b) Dialog customization The dialog built by Biometric Sensor SDK contains texts describing the purpose of the operation and is cancelable. It can contain an icon and a fallback button. The color of the text and background can be customized (ARGB). Table 6: Dialog Popup Customization Attributes Attribute Description Default value Text color Color of the description text and dialog buttons 0xFF (black) Background color Background color of the dialog 0xFFFFFFFF (white) Fail text color Color of the text in case of authentication failure 0xFFFF0000 (red) Description Description message displayed in the dialog to explain the purpose of the dialog Please, use your fingerprint scanner to authenticate. Default authentication failed text Message displayed in case of authentication failure Authenticatio n failed. Cancel text Text of the cancel button Cancel Fallback mechanism used Indicates whether a fallback mechanism false button must be displayed Fallback mechanism text Text of the fallback mechanism button Use fallback Icon used Indicates whether an icon must be displayed false Icon name Name of the icon from the resource folder null ios Table 7: Method Signature (Start Biometric Authentication on ios) Method Signature +(void) startuserauthenticationwithparams: (BiometricSensorSDKParams*) biometricsensorsdkparams; A BiometricSensorSDKParams object must be provided to set the following parameters: biometricauthenticationmethod to set the authentication method which must be used to authenticate the user (Touch ID, Face ID or any). This parameter is optional, the default value is BiometricAuthenticationMethodAny. usefallbackmechanism to display a fallback mechanism button after an authentication failure. This parameter is optional, the default value is No. If this button is pressed, the onbiometricauthenticationfallbackcalled callback will be called. It is up to the integrator to implement this fallback mechanism. 11

12 Introducing the Biometric Sensor SDK fallbackmechanismtext the text displayed on the fallback button. This parameter is mandatory if usefallbackmechanism is Yes. operationdescription the text displayed in the biometric view giving the reason for the biometric authentication. This parameter is optional, not text is displayed by default. onbiometricauthenticationsucceeded the block that will be called in case of success during biometric authentication. This parameter is mandatory. onbiometricauthenticationfailed the block that will be called in case of failure during biometric authentication. This parameter is mandatory. onbiometricauthenticationcancelled the block that will be called if the biometric authentication is cancelled by the user. This parameter is mandatory. onbiometricauthenticationfallbackcalled the block that will be called if the fallback mechanism button is pressed by the user. This parameter is mandatory if usefallbackmechanism is Yes. onbiometricauthenticationerror the block that will be called in case of exception catched during biometric authentication. This parameter is mandatory Stop biometric authentication of user This function stops a biometric authentication process. If no authentication is in progress, nothing happens. Table 8: Method Signature (Stop Biometric Authentication) Platform Method Signature ios +(void) stopuserauthentication; Android public static void stopuserfingerprintverification; 12

13 Integrating the Biometric Sensor SDK 3 Integrating the Biometric Sensor SDK This chapter provides descriptions of how to integrate the Biometric Sensor SDK. This chapter covers the following topic: Integrating the Biometric Sensor SDK with ios Integrating the Biometric Sensor SDK with Android 13

14 Integrating the Biometric Sensor SDK 3.1 Integrating the Biometric Sensor SDK with ios Using the Biometric Sensor SDK in your ios project 1. Link BiometricSensorSDK.framework from the DIGIPASS for APPS package to your Xcode project. 2. In the Build Settings > Other Linker flags section of your Xcode project, add the line -weak_framework LocalAuthentication NOTE If the integration is done with a version of Xcode lower than 9, the following framework must be added as dependencies and the related lines must be added in the Build Settings > Other Linker flags section of your Xcode project: -weak_framework IOSurface -weak_framework FileProvider CAUTION The NSFaceIDUsageDescription key must be defined in the Info.plist file when using Xcode 9 or later. You are now ready to use the Biometric Sensor SDK. For more information about integrating the functions, see 2 Introducing the Biometric Sensor SDK. 14

15 Integrating the Biometric Sensor SDK 3.2 Integrating the Biometric Sensor SDK with Android Using the Biometric Sensor SDK in your Android project 1. Link BiometricSensorSDK.jar from the DIGIPASS for APPS in your project. 2. Link UtilitiesSDK.jar from the DIGIPASS for APPS in your project. 3. Link the android-support-v4 library from Google in version and later. 4. The Biometric Sensor SDK also manages fingerprints authentication on Samsung Android devices since Android 4.2. To manage fingerprint on those devices you must link the Pass SDK in your project. If you don t link the Pass SDK library the Biometric Sensor SDK will only be able to manages fingerprint for Android devices running Android 6.0 and later. The Pass SDK can be downloaded from Samsung s developer website: Once these libraries are linked in your project you will be able to verify fingerprints on: Samsung devices with fingerprint scanner running Android from version 4.2 (Jelly Bean API 17). All other devices with fingerprint scanner running Android from 6.0 (Marshmallow API 23). CAUTION To be able to access the fingerprint service, you need to set appropriate permissions in your application configuration. For Android 6.0 devices and later, you need to add the USE_FINGERPRINT permission to the AndroidManifest.xml file. For Android Samsung devices, you need to add the com.samsung.android.providers.context.permission.write_use_app_feature_survey permission to the AndroidManifest.xml file. You are now ready to use the Biometric Sensor SDK. For more information about integrating the functions, see 2 Introducing the Biometric Sensor SDK. 15

16 Known Issues 4 Known Issues This chapter lists issues that have not yet been resolved for the current Biometric Sensor SDK version. In addition, this chapter provides information about possible workarounds, if available. Incorrect error code in case of cancel on some Samsung devices When cancelling the fingerprint authentication on some Samsung devices, a timeout error code can be randomly returned instead of a cancel error code. The impacted devices are: Samsung Galaxy Alpha (4.4.4) Samsung Galaxy Note 4 Edge (6.0.1) 16

17 Technical Support 5 Technical Support If you encounter problems with a VASCO product please do the following: 1. Check whether your problem has already been solved and reported in the Knowledge Base at the following URL: 2. If there is no solution in the Knowledge Base, please contact the company which supplied you with the VASCO product. If your supplier is unable to solve your problem, they will automatically contact the appropriate VASCO expert. 17