General overview

The Client Device Data Collector SDK (CDDC SDK) provides facilities to aggregate information from various mobile sources for risk evaluation of mobile transactions by OneSpan Risk Analytics. To mitigate the risks associated with mobile transactions, the CDDC SDK retrieves contextual information, such as the device model and the current position from the client device, and uses it to create user behavior profiles.

Secure Channel

The OneSpan Mobile Security Suite Secure Channel feature can be used to securely transfer the collected data from the client to the server to ensure the confidentiality, integrity, and non-repudiation of the data. For more information about the Secure Channel feature, refer to the OneSpan Mobile Security Suite Product Guide and the Digipass SDK Integration Guide.

Supported platforms, included libraries and directories

The CDDC SDK can be used on a variety of devices and supports the following platforms:

Android devices:

• Minimum Android 6 (API level 23)
• Target Android 14 (API level 34)

iOS devices:

• iOS 13 or higher
• Swift 5.0 or higher
• Xcode 15 or higher

The Client Device Data Collector SDK package includes the following:

• CDDCSDK.aar for Java platforms (e.g. Android)
• MSSCDDC.xcframework for iOS
• BehavioSecIOSSDK.xcframework for iOS (required to capture behavioral data).

The BehavioSecIOSSDK.xcframework is included for customers using only the BehavioSec solution. If you plan to utilize the CDDC SDK, you do not need to include the BehavioSecIOSSDK.xcframework since it is automatically included in the MSSCDDC.xcframework.

For instructions on how to integrate the SDK, see Integrate the CDDC SDK with Android.

Data collection and transfer

The CDDC SDK provides an API to aggregate the relevant client device information in RA-readable messages. Risk Analytics uses these CDDC messages to evaluate the risk of mobile transactions.

For a list of device and event properties that can be collected, see Retrievable device and event properties lists device and event properties that can be retrieved from the client device..

Data collection and transfer process

The data collection and transfer process consists of the following steps:

1. The mobile application must call the collectCDDCData method of the CDDC SDK to start the data collection.

2. Via dedicated setters which the CDDC SDK exposes, you can configure the following data collection parameters:

   • Collection duration; default value: 400 milliseconds
   • Bluetooth data collection; default value: false
   • Wi-Fi data collection (Android only); default value: false

3. A listener object which implements the CDDCDataCollectListener interface notifies the mobile application about the status of the collected data (success, interrupted, warning, or error).

4. The mobile application must call the getCollectedCDDCData method of the CDDC SDK. This method uses an event identifier (from the CDDCEventName class) and the unique identifier of the mobile device as parameters.
   

   For more information, see Overview of the Device Binding SDK.

5. The call to the getCollectedCDDCData method is not blocked (if data has been collected successfully at least once), and can be called without having to refresh the data.

6. The getCollectedCDDCData method returns a CDDCData object.

   Some data cannot be collected automatically by the CDDC SDK. The mobile application must populate these with dedicated CDDCData object setters. See the Retrievable device and event properties lists device and event properties that can be retrieved from the client device. for a list of data elements which must be populated by the mobile application.

   If you encrypt the collected data, i.e. the CDDCData object, it must be converted to hexadecimal strings. After the conversion, the Digipass SDK encrypts it with the toHexStringList method of the CDDC SDK. For more information, refer to the Overview of the Digipass SDK.

   If the CDDC data length is greater than 1024 hexadecimal characters, the toHexStringList() method returns several hexadecimal strings with a maximal length of 1024 characters each. These strings must be encrypted in succession with the OneSpan Mobile Security Suite Secure Channel feature.

7. The mobile application must call the generateMessageWithEncryptedData method of the CDDC SDK to get the CDDC message that must be transmitted to Risk Analytics.
8. The CDDC message is a JSON string with encrypted CDDC data.

   The CDDC data can be sent in clear text with the generateMessageWithClearData method.

Use case 1: Authentication

You can use the CDDC SDK to mitigate the risk during an authentication and collect behavioral data.

Prerequisites

1. Customer mobile application is available.
2. Risk Analytics is used for risk analysis.
3. OneSpan Authentication Server is used for identity management. we recommend installing OneSpan Authentication Server to encrypt / decrypt data the CDDC SDK collects.

   This requires the Digipass SDK to activate a license first.

4. A BehavioSec license is available to analyze behavior data.
5. A customer server is available to manage the communication between the mobile application, Risk Analytics, OneSpan Authentication Server, and the BehavioSec service.

Sequence of an authentication via PIN with behavior analysis

Sequence of an authentication request:

1. The user initiates an authentication with PIN on the mobile application.
2. The mobile application confirms the authentication request and requests the PIN.
3. The CDDC SDK collects the PIN behavior data via the Behavior GUI component and life cycle methods.
4. The CDDC SDK sends a request response to the user.
5. The user enters their PIN in the mobile application.
6. The mobile application requests the CDDC data from the SDK. This data includes the event and the device ID.
7. The CDDC SDK sends the CDDC data to the mobile application.
8. The mobile application requests the timing data from the SDK.
9. The SDK returns the raw timing data to the mobile application.
10. The mobile application creates a JSON file with the CDDC data and the behavior data.
11. The mobile application adds this behavioral data to the CDDCData object.
12. The CDDC SDK sends a status success response to the mobile application(OK/NOK).
13. The mobile application generates a CDDC Secure Channel message that contains the CDDC and behavbiorial data.
14. (Optional) The data is encrypted with the Digipass SDK.
15. The mobile application generates the message with the encrypted or clear data to the CDDC SDK.
16. The CDDC SDK returns the message to the mobile application.
17. The mobile application sends an authentication request including the CDDC message to the customer server application.
18. The customer server application extracts the behavioral data from the message.
19. The customer server application sends the extracted BehavioSec data to the BehavioSec service for analysis.
20. The BehavioSec service provides the data from the behavioral analysis as a confidence score to the customer server application.
21. If the CDDC message has been encrypted, the customer server application sends it for decryption to OneSpan Authentication Server.
22. OneSpan Authentication Server returns the decrypted CDDC message.
23. The customer server application generates an XML file with the clear data and the behavior result and sends these data to OneSpan Risk Analytics via a REST API.
    For more information, refer to the Risk Analytics Digital Banking Integration Guide.
24. Risk Analytics assesses the risk and informs the customer server application to make a decision on the authentication request.
25. The customer server application sends the authentication result to the mobile application.
26. The mobile application processes the authentication according to the retrieved result.