Root Detection SDK. Integration Guide 4.17

Transcription

1 Root Detection 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 Root Detection SDK Functions Overview Exposed APIs Constants Starting the Analysis (s Method) Description Parameters Return Values Error Codes Examples Android ios Obtaining the Signature File Version (g Method) Description Parameters Return Values Error Codes Example Android ios Integrating the Root Detection SDK Integrating the Root Detection SDK with Android Integrating the Root Detection SDK with ios Technical Support

4 Table of Contents Index of Tables Table 1 Return Codes... 8 Table 2: Method Signature (Starting the Analysis)... 9 Table 3: Parameters (Starting the Analysis)... 9 Table 4: Error Codes (Starting the Analysis)... 9 Table 5: Method Signature (Obtaining the Signature File Version) Table 6: Parameters (Obtaining the Signature File Version) Table 7: Error Codes (Obtaining the Signature File Version)

5 Introduction 1 Introduction Welcome to the Root Detection SDK Integration Guide! The Root Detection SDK provides facilities to detect whether a device is rooted / jailbroken. This document provides information about: Functions of the Root Detection 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 Biometric Sensor SDK (refer to the Biometric Sensor SDK Integration 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 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) 1 As of version 4.3.2, the package name of the DIGIPASS SDK has been changed to DIGIPASS for APPS. 5

6 Introduction Instructions to integrate the White-Box Cryptography (WBC) SDK (refer to the White-Box Cryptography SDK Integration Guide) 6

7 Root Detection SDK Functions 2 Root Detection SDK Functions This chapter contains an overview of the Root Detection SDK and information about the SDK s functions. This chapter covers the following topics: Overview Starting the Analysis (s Method) Obtaining the Signature File Version (g Method) 7

8 Root Detection SDK Functions 2.1 Overview Exposed APIs Constants The Root Detection SDK is a JAR file named RootDetectionSDK.jar for Android, and a framework named RootDetectionSDK.framework for ios. It detects if an application is running on a rooted Android device or on a jailbroken ios device. To detect that a device is corrupted, the Root Detection SDK uses a signature file that is part of the DIGIPASS for Apps package. This signature file must be integrated into your project. Classes and methods which are exposed by the Root Detection SDK API have very simple names of a single letter to enhance security by complicating reverse-engineering. The Root Detection SDK supports the following platforms: ios 5.0 (and higher) Android 2.3 and higher The APIs comprise two main methods: s method: Start analysis process to detect if the phone is rooted / jailbroken. g method: Retrieve the file signature version. For Android, the APIs are exposed by the P class of the com.vasco package. For ios, the APIs are exposed by the P object. Table 1 Return Codes Name Value Error Message v Current version Version of the Root Detection SDK. t 14 Current version of the signature file. n 0 Return code indicating that the device is not rooted / jailbroken. z Return code indicating an unknown error. r Return code indicating that the device is rooted / jailbroken. e Return code indicating that the signature file is null. l Return code indicating that the signature file length is incorrect must be at least 256 characters. f Return code indicating that the signature file format is incorrect only hexadecimal characters allowed. i Return code indicating that the signature file is invalid: wrong signature or XML parsing error. a Return code indicating that the version of the signature file is too old to be used by the Root Detection SDK. The return codes can be retrieved from the O object. 8

9 Root Detection SDK Functions 2.2 Starting the Analysis (s Method) Description Parameters Table 2: Method Signature (Starting the Analysis) Platform Method Signature Android public static S s(string c, Context a) ios +(s) s: (NSData*) c This function starts the analysis process, which detects whether a device is rooted or jailbroken. With the Root Detection SDK 4.4, this method also checks the version of the signature file. The signature file version must be higher as or equal to the version defined in the Root Detection SDK (indicated by the constant t ). The aim is to prevent anyone from using signature files that may contain deprecated verification rules. NOTE For Android platforms, another signature for this method exists: public static S s(string c), which does not use the Android context. However, the Android context is necessary for improving the root detection process. As a result, the deprecated method must only be used for backward-compatibility to manage earlier client integrations (Root Detection SDK 4.3 or earlier versions) Return Values Error Codes Table 3: Parameters (Starting the Analysis) Type Name Use Description String/NSData* c I (mandatory) Signature file content. Context a I (mandatory) Android context (Android only). A response object named S is returned, which contains the following: a return code indicating the result of the analysis, and an exception if an unknown error occurs. Table 4: Error Codes (Starting the Analysis) Name Value Error Message n 0 Return code indicating that the device is not rooted / jailbroken. z Return code indicating an unknown error. 9

10 Root Detection SDK Functions Examples Android Name Value Error Message r Return code indicating that the device is rooted / jailbroken. e Return code indicating that the signature file is null. l Return code indicating that the signature file length is incorrect it must be at least 256 characters. f Return code indicating that the signature file format is incorrect only hexadecimal characters are allowed. i Return code indicating that the signature file is invalid: wrong signature or XML parsing error. a Return code indicating that the version of the signature file is too old to be used by the Root Detection SDK. This section illustrates how to integrate and use the s method. For more information, refer to the Root Detection SDK sample project in the DIGIPASS for APPS package. // Retrieve the signature file InputStream ins = assetmanager.open(path); // Start analysis process S response = P.s(convertInsToString(ins), this.getapplicationcontext()); int returncode = response.getreturncode(); // Check the result from the analysis process if (returncode == O.n) { System.out.println("Device is not rooted."); } else if (returncode == O.r) { System.out.println("Device is rooted."); } else { System.out.println(getMsgFromReturnCode(returnCode)); System.out.println("Error code: " +returncode); } ios //Get file signature path NSString * filepath = [[NSBundlemainBundle] pathforresource:@"signature" oftype:nil]; 10

11 Root Detection SDK Functions //Load signature file NSData * d = [NSData datawithcontentsoffile:filepath]; // Call s method: check if phone is rooted s response = [P s:d]; NSString * resulttext //Parse result switch(response.r){ case P_r: resulttext Device is rooted **" ; break; case P_n: resulttext Device is not rooted **" ; break;

12 Root Detection SDK Functions 2.3 Obtaining the Signature File Version (g Method) Table 5: Method Signature (Obtaining the Signature File Version) Platform Method Signature Android public static G g(string c) ios +(g*) g: (NSData*) c Description Parameters This method returns the version of the signature file. Table 6: Parameters (Obtaining the Signature File Version) Type Name Use Description String/NSData* c I (mandatory) Signature file content Return Values A response object named G is returned, which contains the following: a return code indicating the result of the analysis, the version of the signature file in case of success, an exception if an unknown error occurs Error Codes Table 7: Error Codes (Obtaining the Signature File Version) Name Value Error Message n 0 Return code indicating that the version has been successfully retrieved. z Return code indicating an unknown error. e Return code indicating that the signature file is null. l Return code indicating that the signature file length is incorrect it must be at least 256 characters. f Return code indicating that the signature file format is incorrect only hexadecimal characters allowed. i Return code indicating that the signature file is invalid: wrong signature or XML parsing error. 12

13 Root Detection SDK Functions Example Android ios This section illustrates how to retrieve the signature file version. For more information, refer to the Root Detection SDK sample project in the DIGIPASS for APPS package. Once deployed, the application will be installed under the name Root Detection SDK Sample. // Retrieve the signature file InputStream ins = assetmanager.open(path); // Get signature file version G response = P.g(convertInsToString(ins)); int returncode = response.getreturncode(); // Check if the version has been successfully retrieved if (returncode == O.n) { System.out.println("Signature File version " + response.v()); } else { System.out.println(getMsgFromReturnCode(returnCode)); System.out.println("Error code: " +returncode); } //Load signature file NSString * filepath = [[NSBundlemainBundle] pathforresource:@"signature" oftype:nil]; //Get NSData from file NSData * d = [NSData datawithcontentsoffile:filepath]; // Call the g method: check the signature file version G response = [P g:d]; NSString * resulttext //Parse result switch(response.r){ casep_n: resulttext = [NSStringstringWithFormat:@"** Version ** \r ** %s ** ", response.v];... 13

14 Integrating the Root Detection SDK 3 Integrating the Root Detection SDK This chapter contains instructions how to integrate the Root Detection SDK with the supported platforms. This chapter covers the following topics: Integrating the Root Detection SDK with Android Integrating the Root Detection SDK with ios 14

15 Integrating the Root Detection SDK 3.1 Integrating the Root Detection SDK with Android Using the Root Detection SDK in your Android project 1. Copy RootDetectionSDK.jar from the DIGIPASS for APPS package to the libs folder. 2. Copy UtilitiesSDK.jar from the DIGIPASS for APPS package to the libs folder. 3. Copy the signature file from the DIGIPASS for APPS package to the assets/signature folder. You are now ready to use the Root Detection SDK. For more information about integrating the methods, refer to Chapter 2 Root Detection SDK Functions. 15

16 Integrating the Root Detection SDK 3.2 Integrating the Root Detection SDK with ios Using the Root Detection SDK in your ios project 1. Link the RootDetectionSDK.framework file from the DIGIPASS for APPS package to your Xcode project. 2. Link the libc++ library from the ios SDK to your Xcode project using the Link Binary With Libraries build phase (only required if the project is compiled in Objective-C and not in Objective-C++). 3. Link the libutilitiessdk.a library from the DIGIPASS for APPS package to your Xcode project. 4. Copy the signature file from the DIGIPASS for APPS package to the res folder. CAUTION Your project must be compiled using the libc++ standard library. You are now ready to use the Root Detection SDK. For more information about integrating the methods, refer to Chapter 2 Root Detection SDK Functions. 16

17 Technical Support 4 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