Android - App Fingerprint - Monitor (Pro)

The certificate fingerprint, also known as a signature, can be used to detect whether the Android app was built and signed by the original developer or someone else. The fingerprint is digitally applied to an app by using a private key (stored in a key store); this ensures the authenticity and integrity of the app. A fingerprint is created by a developer or an organization and is unique to their app.

Validating the fingerprint is easier to set up than checking the app hash, as it can be done locally without having to use an external remote resource for validation.

Monitor

The 'AndroidPackageFingerprintMonitor' (class AndroidPackageFingerprintMonitor, namespace GUPS.AntiCheat.Monitor.Android) reads the signing fingerprint of the app. Because the fingerprint is stored as binary, the monitor hashes it with a configurable algorithm to make it more human readable. When the fingerprint has been read, it emits an AndroidFingerprintStatus to its observers.

Status

The monitor emits an AndroidFingerprintStatus, which implements IAndroidStatus (and therefore IWatchedSubject):

public struct AndroidFingerprintStatus : IAndroidStatus
{
    // True if the fingerprint could not be retrieved (e.g. a JNI failure).
    public bool FailedToRetrieveData { get; }

    // The algorithm used to compute the fingerprint.
    public string Algorithm { get; }

    // The hex-encoded signing certificate fingerprint of the running app.
    public string Fingerprint { get; }
}

• FailedToRetrieveData: True when the fingerprint could not be retrieved or an exception occurred; the other values are then not valid.
• Algorithm: The hash algorithm used to make the binary fingerprint readable (see the table below).
• Fingerprint: The hex-encoded certificate fingerprint the app was signed with.

Lifecycle and timing

The monitor reads the fingerprint once, in its OnStart callback, and then notifies observers a single time with the resulting AndroidFingerprintStatus. If the fingerprint could not be read, it still notifies with FailedToRetrieveData set to true.

Configuration

The algorithm and the expected fingerprint are configured in the AntiCheat project settings rather than on the component. See 'Hash Algorithm' below.

Development builds

The paired detector honors the global 'Verify development builds' switch. By default it validates the app only in release builds, so the check is skipped in development builds and inside the Unity editor. Enable this option in 'Project Settings -> GuardingPearSoftware -> AntiCheat' while testing.

Enable 'Verify development builds' to also validate the app in development builds and the editor.

Supported Platforms

The monitor is only available on Android platforms.

Requirements

Requires an Android build with at least Android 4.4 (API level 19) (December 2013).

How To Use

Attach the 'AndroidPackageFingerprintMonitor' to a child GameObject of the 'AntiCheat-Monitor', assign the used hash algorithm in the 'AntiCheat-Project Settings', and pair it with the 'AndroidPackageTamperingDetector'.

Add Monitor Component

Add the 'AndroidPackageFingerprintMonitor' MonoBehavior from the 'GUPS.AntiCheat.Monitor.Android' namespace to your 'AntiCheat-Monitor' GameObject, or better, to a child GameObject.

Add the 'AndroidPackageFingerprintMonitor' as a Component.

Hash Algorithm

To calculate the hash of the binary fingerprint, an algorithm is needed. AntiCheat supports the following algorithms:

Hash-Algorithm	Description
None	No hash algorithm is used.
MD5	MD5 hash algorithm. Not recommended for security purposes.
SHA1	SHA1 hash algorithm. Not recommended for security purposes.
SHA256	SHA256 hash algorithm.
SHA384	SHA384 hash algorithm.
SHA512	SHA512 hash algorithm.

To assign the algorithm used for the fingerprint hash calculation, go to 'Project Settings -> GuardingPearSoftware -> AntiCheat'. Go to the section 'Android - App Fingerprint - Settings'. Activate the 'Verify app fingerprint' checkbox and assign the algorithm you would like to use. SHA256 is the recommended algorithm.

In the AntiCheat Project Settings, assign the algorithm used for hashing.

Consume the status in code

Besides pairing the monitor with a detector, you can subscribe your own observer to receive the AndroidFingerprintStatus directly. Every monitor derives from AMonitor and exposes Subscribe(IObserver<IWatchedSubject>), which returns an IDisposable you can dispose to unsubscribe.

using System;
using GUPS.AntiCheat.Core.Watch;
using GUPS.AntiCheat.Monitor.Android;
using UnityEngine;

public class AndroidFingerprintStatusLogger : MonoBehaviour, IObserver<IWatchedSubject>
{
    private void Start()
    {
        var monitor = GetComponentInChildren<AndroidPackageFingerprintMonitor>();
        monitor.Subscribe(this);
    }

    public void OnNext(IWatchedSubject subject)
    {
        if (subject is AndroidFingerprintStatus status)
        {
            if (status.FailedToRetrieveData)
            {
                Debug.LogWarning("Could not read the app fingerprint.");
                return;
            }

            Debug.Log($"Fingerprint ({status.Algorithm}): {status.Fingerprint}");
        }
    }

    public void OnError(Exception error) { }
    public void OnCompleted() { }
}

Detect Invalid Fingerprint

To react to the sent status and thus validate the calculated fingerprint, you need a detector. To do this, use the 'AndroidPackageTamperingDetector', an aggregated detector that can react to various attempts to tamper with the Android app itself.