Security Architecture

Introduction

The Halo Dot SDK provides a simple interface for integrators to start accepting contactlesss payments in their applications. However, processing card data brings with it a host of security concerns. This document will describe the sensitive assets that cross the boundary from the SDK to the application (and vice versa) to help explain what is required from an application perspective. Additionally, this document will describe the various security mechanisms that are used and how these interact with the integrating application. Finally, this document will list the permissions required by the SDK and provide explanations for why they are necessary.

Sensitive Assets

This section describes the sensitive assets that cross the boundary of the SDK. This refers to any pieces of information that are either directly or indirectly used in the processing of financial data. This includes authentication tokens, certificates and keys and card data. In the table below, the direction column refers to the direction that the assets flow. There are 3 entities mentioned:

• Application: This is the integrating application that is calling methods in the Halo Dot SDK.

• SDK: This is the Halo Dot SDK

• Backend: This is the Halo Dot transactional server

Asset	Direction	Explanation	Required Protection
JWT	Application → SDK	The JWT is required by all SDK functions, and must be provided by the integrating application	This is documented in the key management document
Phone keys	SDK → Backend	The SDK performs a key exchange with the Halo Dot servers to establish shared keys that can be used for encryption and signing of messages at application level	None; this is protected by Halo Dot
Server keys	Backend → SDK	The Halo Dot servers respond with server keys that are used for encrypting and signing messages. A cache of keys is stored on the device, protected by the Halo Dot SDK	None; this is protected by Halo Dot
Terminal config	Backend → SDK	The Halo Dot servers respond with the terminal config to intialise the terminal. This determines what card types are supported, what the CVM limits are, whether ot not PIN is supportedf and any other terminal configuration properties	None; this is protected by Halo Dot
IPEK	Backend → SDK	The Initial Pin Encryption Key is generated by an HSM and is used to initialise the DUKPT state on the device. This is required to process PIN transactions securely.	None; this is protected by Halo Dot
Entropy	Backend → SDK	Entropy is sourced from the Halo Dot servers to seed the DRNG on the phone	None; this is protected by Halo Dot
Transaction Data	SDK → Backend	This is the card data that is required to authorise the transaction.	None; this is protected by Halo Dot
Encrypted PIN Block	SDK → Backend	The client PIN that is captured if required. Encrypted using DUKPT and signed by the SDK, validated on the backend	None; this is protected by Halo Dot
Transaction Result	SDK → Application	The result of the transaction is returned to the integrating application. This includes the transaction disposition, masked PAN and transaction IDs.	The transaction result is returned with a signature - the signing key will be shared out of band. Please verify the signature to ensure that the result has not been tampered with.

Protection mechanisms

To protected the integrity of the application and ensure that financial data is securely read and transmitted, the Halo Dot SDK makes use of a number of protection mechanisms. These range from static protections (to protect against reverse engineering and code analysis) to run-time protection (to protect against instrumentation and malicious access). Any errors that occur as a result of these mechanisms are reported either the HaloStartTransactionResult, HaloTransactionResult andHaloInitializationResult objects.

• Static code protection (obfuscation) The SDK is minified using R8 and then obfuscated using Zimperium zShield. The Kotlin code is transpiled to C++ and then obfuscated to prevent static code analysis. There is no requirement from the integrating app to handle this, but be aware that debugging the Halo Dot source code will not produce usable source files for internal functions.

• Run time integrity protections The SDK performs various checks at run time to ensure the integrity of the platform. This includes checking if the device is rooted, if a debugger is attached or if an instrumentation framework is being used. If any of these are detected, the application immediately terminates.

  • Root checks Rooted devices have full access to the memory and services running on them, and so they cannot be trusted to perform financial transactions.

  • Instrumentation checks Instrumentation frameworks (such as Frida) are used to manipulate running applications by hooking into function calls and replcaing their implementations. This allows the user to potentially bypass security checks, exfiltrate card data or make the app think that a transaction has been approved when it has actually been declined, or vice versa.

  • Debugger checks Debuggers can be used to inspect memory and alter application flows, and so they can not be allowed on a running payment application. With Android, it is possible to debug a device remotely, and so we must terminate the application if we detect the presence of a debugger.

• Developer option checks If developer options are enabled, it is possible to attach adb to the device, which can be used to extract information or view the screen remotely (since adb can be attached over wi-fi). Thus, the SDK does not allow developer options to be enabled on the release build. The debug build allows developer options as normal.

• Accessibility service checks Accessibility services are capable of scraping screen elements and processing them to enable screen reading or other accessibility functions. Unfortunately, this presents a security vulnerability for the PIN screen, as a malicious accessibility service would be capable of capturing PIN numbers. Thus, the release Halo Dot SDK does not allow the PIN screen to be displayed if accessibility services are enabled. A warning will be returned during initialisation if accessibility services are detected, and an error will be returned during transaction processing if a PIN is required.

• Overlay detection The SDK does not allow overlays to be displayed over the PIN screen. This is to prevent a class of attack where transparent overlays can capture PIN numbers without the user's notice.

• Attestation Attestation is the process of verifying the claims that the device makes about itself. Halo Dot uses attestation to ensure that the device has not been compromised and that the application that is running the SDK has not altered. Any attestation failures will result in exceptions being raised and the SDK will fail to initialise and transact. In most cases, these will be returned through the HaloInitializationResult and HaloTransactionResult objects. However, due to attestations that occur in the background, attestation errors can also be reported using the onAttestationError callback.

  • Play Integrity Google services are used to determine if the application has been tampered with and if the device profile is known to Google.

  • Whitebox attestation A custom attestation process is used to verify the integrity of the Whitebox to ensure that PINs can be securely captured.

  • Key attestation Android key attestation is used to check if the bootloader has been unlocked and to verify the signature on the application.

• Certificate pinning The SDK uses certificate pinning to protect against man in the middle attacks and to prevent malicious CA's from being used to bypass legitimate Halo Dot servers. The certificate PIN is provided in the JWT that the SDK uses and contains the SHA256 hash of the public key of the server certificate. Since the JWT is provided by the integrating application, it is vitally important to protect the integrity of the JWT. Please see the key management section for guidance on protecting the JWT signing keys.

• Encryption and signing of messages to and from the server In addition to using TLS 1.2+, all messages between the SDK to the backend server are signed and encrypted at application level. During initial device registration, key exchanges are performed to allow secure communcation. If either the server or SDK fails to validate the signature of a message, an exception is raised and the operation is aborted.

Permissions required

The Halo Dot SDK requires a number of permissions to function. Some of these permissions require user intervention, so integrators are required to ask for these permissions before attempting to initialise the SDK. The permissions that require user intervention are:

• Bluetooth This permission is required to determine if any devices are connected to the mobile device. This is an attestation requirement to determine if any known malicious devices are connected.

• Microphone The microphone must be monitored to prevent side channel attacks and to prevent malicious applications from capturing sensitive card holder information. The SDK does not do anything with the microphone other than prevent other apps from using it.

• Location Each transaction that is submitted contains the GPS co-ordinates of the device. This is to help detect fraud.

• Camera The camera must be held to prevent malicious applications from capturing card details while it is being tapped on the phone. The SDK does not do anything with the camera other than prevent other applications from using it.