App Onboarding

In order to ensure security and MPoC compliance, we require the following information to form our attestation:

App Package name - Package name of the integrating application.
Key Store Hash - This is a SHA-256 hash value from the keystore certificate.
Play Integrity Keys - These are response encryption keys used to secure the communication between your Android application and the Google Play services.

The following sections will guide you through the process of onboarding your app and obtaining these values.

Please contact NMI at [email protected], to share this information.

Pre-requisites

To manage your app's security, keys, and certificates, you will need to use the Google Play Console. This is the tool used to manage, release, and track your apps on the Google Play Store. Additionally, you will need to create a Google Play Project, which integrates your app with backend services and APIs like the Google Play Developer API, and other Google services.

If you are not set up with a Google Play Console, you will need to register for a Console Developer account, see Android's documentation to do this.

To create a Google Play Project through your Google Play Console:

Navigate to Menu > IAM & Admin > Create a Project.
Follow the on-screen instructions. More information about these steps can be found in creating-managing-projects in the Google Cloud documentation.

Play Integrity Keys

To obtain your Play Integrity keys from the Google Play Console, you must link your Google Cloud Project to the app.

Ensure that you are the owner of the app for the next steps, as the app owner must match the owner of the Google Cloud Project.

Before starting the following steps, please ensure that you have requested a PEM file (certificate) from us, this is required to obtain your Play Integrity keys.

To link your Google Play Project you need to enable Play Integrity API via your Google Play Console.

Navigate to Release > App integrity.

Under Play Integrity API select Link a Cloud project.

Select a Cloud Project to link to your app and enable Play Integrity API for the project. For more details on this see Set up in Google Play Console in Android's documentation.
Once this is successfully enabled you should see the button Link Cloud Project changes to Integrate Integrity API.

Once you have your PEM file, you can make a classic request to obtain your integrity keys. To do this your app must be on Google Play.

Go to Google Play Console and select your app.
Navigate to Release > App integrity.

Select Settings next to Play Integrity API.

Navigate to Classic requests where you can request and download your play integrity keys.

Select Edit next to Response encryption, and a window should open.

Select Manage and download my response encryption keys.
Follow the instructions to upload the PEM file we provided you with.
Once uploaded successfully click Save to download the encrypted keys.

For more information on requesting integrity keys see Android's documentation.

When enabling play integrity for a new application, this will require a release that is prompted to at least Internal Testing.

Keystore Hash

Ensure that the Base64 encoded SHA256 digest of the keystore certificate used for app signing is shared with NMI.

The keystore hash must come from the same signing key you use for your app - whether for production or testing. If you sign your debug APK with a different key than your release build, you'll need to supply two separate onboarding configurations (one for test, one for production). We use your onboarding data, including the keystore hash, to perform integrity checks. A mismatch will cause calls to connectAndConfigure to fail.

There are two methods of managing app signing that will mean obtaining the keystore hash is different depending on the method you are implementing. The following sections will step through how this may be done for each method.

Google Play Signed Apps

If you're using Google app signing the release key required can be found in the Google Play Console. The key found on Google Play Console is in hex format and so you will need to convert it to Base64 format before sharing it with us.

Self Managed Signing

If you are managing your own keys and don't make use of Google Play Signing, you can use the following command to export the keystore certificate.

keytool -export -alias <ALIAS_NAME> -keystore <KEYSTORE_PATH> -rfc -file <CERTIFICATE_NAME>

The SHA-256 fingerprint can be fetched from keystore certificate using the following command:

openssl x509 -noout -fingerprint -sha256 -inform pem -in <CERTIFICATE_NAME>

This will provide the SHA-256 fingerprint in hex so will need to be converted to Base64.

To generate it in digest the following sample code can also be used:

public static String getSHA256Fingerprint(X509Certificate cert) throws Exception {
    java.security.MessageDigest md = java.security.MessageDigest.getInstance("SHA-256");
    byte[] der = cert.getEncoded();
    md.update(der);
    byte[] shaFingerprint = md.digest();
    return java.util.Base64.getEncoder().encodeToString(shaFingerprint);
}

You will need to add this key to your Google Play Console if you are managing this yourself so please see their documentation to do so.

For more information on how to sign your app, refer to the Android documentation on app signing.