Developer Pages

# App attestation

Page contents

# About app attestation

Our app attestation feature gives applications additional security, as it prevents third-party use of our APIs. Using this feature guarantees that our Encap server communicates with the correct app.

Without app attestation, any mobile client with a valid application ID and end-to-end (E2E) public key can call and use our Encap mobile client APIs. This could allow a third party to create a malicious app, which can pose security and privacy risks.

# Understanding malicious API usage

# Normal use case

In a normal use case, the customer's app interacts with the customer server and the Encap server through the Encap mobile SDK.

Normal API usage click-to-zoom

# Malicious use case

In a malicious use case, an attacker figures out how the Encap server and the customer backend API work, and uses them to create a malicious app.

The Encap mobile client APIs are open, therefore any client with a valid application ID and E2E public key can call and use these APIs. Depending on the obfuscation and shielding of the apps, a skilled attacker with enough resources could pick out the necessary attributes to use the Encap APIs.

All open APIs are vulnerable to some extent. Hiding all attributes to prevent this kind of abuse is not possible.

Malicious API usage click-to-zoom

Users of a malicious app activate the app against the customer's API; either willingly by filling out the activation details in the app, or unwillingly as a result of phishing.

The activated user of the malicious app can then authenticate towards the customer's API and access customer data just as easily as if they were using the legitimate app.

Note

This is not a case of hacking the credentials, but social manipulation of the end-user and abuse of the customer's onboarding process.

Most of the processes that are abused in a malicious use case are outside the scope of the Encap solution because:

  • Proofing of end-users is handled entirely by the service provider.
  • The binding of an end-user's identity to an Encap credential is handled by the service provider.
  • The Encap solution only knows about registered devices, not the identity of the end-user.

# What risks can app attestation mitigate?

App attestation can mitigate risks in situations of both malicious and non-malicious apps.

# Malicious apps

In the case of malicious apps as described above, app attestation protects against risks such as:

  • Financial loss for the end-user.
  • Loss of privacy for the end-user.

# Non-malicious apps

A non-malicious app is an app that attempts to misuse the Encap solution, but without malicious intent. App attestation protects against the risks that this can create, such as:

  • Unmanaged security and privacy risks.
  • Loss of control of customer communication for the service provider.

Example of a non-malicious app

For example, a consumer banking app wants to display customer bank statement data from another bank account by activating its own app against the Encap server, but without consent from the owning bank. This would be considered misuse of the Encap solution, which app attestation would protect against.

# Mitigating malicious API usage with app attestation

To prevent third-party use of our APIs and to enforce the use of legitimate apps with our own SDK, we have introduced two features for app attestation; Play Integrity for Android and App Attest for iOS.

# How does Play Integrity work?

For Android devices, we make use of Play Integrity's Attestation API. This API is provided by Google as part of the Android platform, and gives your app additional security against threats such as device tampering and potentially harmful apps.

Based on the results of the attestation, it is possible to deny access on rooted device and emulators.

Play Integrity ensures:

  • The integrity of the device.
  • That the application is genuine.
  • That the application has been installed using Google Play.

Encap SDK compatibility

For Encap SDKs of version 3.17 or later, only Play Integrity is supported.

# Basic flow for an attestation

  1. The Encap server sends a nonce to the client.
  2. The Android client calls the Google Play Integrity Attestation API and passes on the nonce.
  3. The Google server verifies that it is a known device and returns the Google-signed attestation.
  4. The app sends the attestation data back to the Encap server.
  5. The server verifies:
    1. That the attestation signature has not been tampered with.
    2. The timestamp, to make sure that not too much time has passed.
    3. That the nonce is the same as for the initial request.
    4. That the attestation is from the right app.
    5. The application hash.
    6. That the attestation is from a real device.
    7. The integrity of the device.
  6. If all checks pass on the server, the activation/authentication can continue. If not, then the resulting status is sent to the service provider.

Learn more about Play Integrity

You can find a full description of Play Integrity in the Android developer portal:

# Risks

  • It is possible that some phones (such as models by Chinese brands) could fail the integrity test.
  • There is a risk that rooted devices will not pass the integrity test. This means that if someone has configured Shield to not crash but just warn, they will still fail the authentication.
  • There is a quota limit of 10,000 requests a day per API key. This limit can be increased by Google on request (opens new window).
  • The Google service could be down.

# How does App Attest work?

For iOS devices, we make use of App Attest. This API is provided by Apple as part of the iOS platform, and gives your app a way to assert its validity by enforcing the use of trusted apps with genuine Encap SDKs. This means that the Encap server can more confidently provide access to sensitive resources.

App Attest gives your app an equal or higher level of integrity assurance to the previously available Intermediate Push feature, without the need to rely on complex push infrastructure.

You can find an overview of the service backing this feature in the Apple developer documentation (opens new window).

Available iOS versions

Apple app attestation is only available for Apple devices running iOS 14 and later.

# Basic flow for an attestation

  1. The Encap server sends a nonce to the client.
  2. The client generates a key in the Secure Enclave, and stores the key identifier (keyID).
  3. The client attests the key by passing the keyID and the nonce to Device Check API. This results in a call to an Apple server, where an attestation object is returned.
  4. The client sends the attestation object along with the keyID to the Encap server.
  5. The Encap server parses and validates the attestation object.
  6. If all checks pass on the server, then the activation/authentication can continue. If the checks do not pass, then the resulting status is sent to the service provider.

Learn more about App Attest

You can find a full description of App Attest in the Apple developer portal:

# Risks

  • On a compromised system such as a jailbroken device with signing protection disabled, it is possible to get valid assertion objects from modified versions of the app.
  • The attestKey call on the client communicates with Apple servers, where the requests per second are rate limited. Therefore, it might not be possible to onboard all customers for a large user base directly.
  • App extensions (opens new window) are not supported. This means that attestation will fail in an app extension.
  • The Apple App Attest service could be down.

# How to configure app attestation

To use our app attestation feature, you need to:

# Configure the mobile SDK

Learn how to configure the mobile SDK for app attestation.

Configure the Android SDK
Learn how to configure the Android SDK for app attestation
Configure the iOS SDK
Learn how to configure the iOS SDK for app attestation

# Configure the application configuration

Learn how to configure the application configuration for app attestation.

# Attestation modes

The app attestation feature can be used in multiple modes:

OFF

The OFF mode means that attestation is not performed.

By default, attestation is turned OFF.

OPTIONAL

The OPTIONAL mode means that attestation is performed.

If attestation fails, then the transaction will not fail, and a new attestation is performed on the next transaction.

REQUIRED

The REQUIRED mode means that attestation is performed.

If attestation fails, then the transaction will fail and the device is locked.

The device must perform a successful attestation before it can be used for future transactions. Attestation is triggered on new registrations, or the first authentication if the registration already exists.

Note: Devices running versions of iOS older than iOS 14 will always fail if the mode is REQUIRED, due to requirements by the Apple App Attest API.

Our recommendation

For an existing installation with devices already activated on previous versions of Encap, we recommend that you start out using the OPTIONAL mode.

You can read more about the reasons for this in the How to roll out app attestation section.

# Play Integrity (Android)

# Setting the properties

To enable Play Integrity, you need to set the following properties in the application configuration:

Property name Description Allowed values
ATTESTATION_ANDROID_PLAY_INTEGRITY_MODE Determines whether Play Integrity attestation is performed, and how the request is handled. OFF,
OPTIONAL,
REQUIRED
ATTESTATION_ANDROID_PLAY_INTEGRITY_TIMEOUT The timeout (given in milliseconds) for a request made to Play Integrity google service. From 1 to MAXINT.
ATTESTATION_ANDROID_PLAY_INTEGRITY_DECRYPTION_KEY Play Integrity attestation decryption key (base-64 string), used to decrypt the integrity token. Base64 string from Google Play Console.
ATTESTATION_ANDROID_PLAY_INTEGRITY_VERIFICATION_KEY Play Integrity attestation verification key (base-64 string), used to validate the integrity token. Base64 string from Google Play Console.
ATTESTATION_ANDROID_PACKAGE_NAME The APK package name. String

Mandatory configurations

If ATTESTATION_ANDROID_PLAY_INTEGRITY_MODE is set to REQUIRED or OPTIONAL, then all Play Integrity configurations defined in the table above are required.

# Play Integrity verdicts

The table below illustrates Play Integrity verdicts:

Verdict Value
deviceRecognitionVerdict MEETS_DEVICE_INTEGRITY
appRecognitionVerdict PLAY_RECOGNIZED
appLicensingVerdict LICENSED

The result of the verdicts will dictate how the operation is handled, depending on what you have set the attestation mode to:

  • If the ATTESTATION_ANDROID_PLAY_INTEGRITY_MODE is set to REQUIRED, then the server will only authorise an operation if the mobile device passes all of the verdicts.
  • If the ATTESTATION_ANDROID_PLAY_INTEGRITY_MODE is set to OPTIONAL, then the same verdicts are performed. However, if the device fails any of the verdicts, the operation is still authorised.
  • If the ATTESTATION_ANDROID_PLAY_INTEGRITY_MODE is set to OFF, then Play Integrity attestation is disabled.

You can read more about integrity verdicts in the Google developer documentation (opens new window).

# Obtaining the decryption and verification keys

Warning

You must set the following application configuration properties in order for the server to decrypt the token response from the Play Integrity API:

  • ATTESTATION_ANDROID_PLAY_INTEGRITY_DECRYPTION_KEY
  • ATTESTATION_ANDROID_PLAY_INTEGRITY_VERIFICATION_KEY

Without these values, the server will return an error.

In order to perform the decryption and validation of the token sent from the application to the server, you need to set up the decryption key and validation key provided from the Google Play Console in the application configuration file. To do this:

  1. Access your application in the Google Play Console.
  2. In the left-side menu, select App integrity.
  3. On the Play Integrity API header, click Settings on the right-hand side.
  4. Under Project configuration, click Link a Cloud project. You can link an existing project that you already use, or you can create a new one.
  5. Under Class requests, click Edit on the Response encryption field, then select Manage and download my response encryption keys.
  6. Follow the instructions listed under Show instructions and upload the public key .pem file. Then click Save changes.
  7. Go back to the previous view and press Download keys.
  8. Download the keys, then use the private key generated in the previous step to obtain the values for DECRYPTION_KEY and VERIFICATION_KEY.
  9. Update your application configuration with the keys obtained.

# App Attest (iOS)

# Setting the properties

To enable App attest, you need to set the following properties in the application configuration:

Property name Description Allowed values
ATTESTATION_IOS_APP_ATTEST_MODE Determines whether App Attest attestation is performed, and how the request is handled. OFF,
OPTIONAL,
REQUIRED
ATTESTATION_IOS_APP_ATTEST_ENVIRONMENT Determines the environment where an iOS app that uses app attestation validates itself. PRODUCTION,
DEVELOPMENT
ATTESTATION_IOS_APP_ATTEST_TIMEOUT The timeout (given in milliseconds) for a request made to App Attest service. From 1 to MAXINT.
ATTESTATION_IOS_APP_ATTEST_APP_ID The iOS app ID which is a concatenation of a 10-digit team identifier, a period, and the app's CFBundleIdentifier value

Example: 0123456789.com.company.myApp		 String

Note

If ATTESTATION_IOS_APP_ATTEST_MODE is set to REQUIRED or OPTIONAL, all other App Attest configurations defined in the table above are required.

# App attest environments

You can set either of the following environments for the ATTESTATION_IOS_APP_ATTEST_ENVIRONMENT added to your application configuration:

  • PRODUCTION is the App Attest production environment. Keys that you create in the production environment do not work in the sandbox environment.
  • DEVELOPMENT is the App Attest sandbox environment that you use to test a device without affecting its risk metrics. Keys that you create in the sandbox environment do not work in the production environment.

# Attestation result

The attestation result is provided in the REST response as the attestation_object.

The attestation object (opens new window) is:

# Response fields

Attestation object (REST) Description
play_integrity_status The Play Integrity attestation status for the device.

See the Play Integrity statuses table under 3.1.5 The attestation object for possible values.
play_integrity_date The date of when the Play Integrity attestation was performed.
app_attest_status The App Attest attestation status for the device.

See the App Attest statuses table under 3.1.5 The attestation object for possible values.
app_attest_date The date of when the App Attest attestation was performed.

Example: Attestation result for device using Android Play Integrity

"attestation" : {
	"play_integrity_status" : "VERIFIED",
	"play_integrity_date" : "2019-09-20T13:14:01.984UTC",
}

Example: Attestation result for device using iOS App Attest

"attestation" : {
	"app_attest_status" : "VERIFIED",
	"app_attest_date" : "2019-09-20T13:14:01.984UTC"
}

# Failed operations due to attestation

If the attestation mode is set to OFF or OPTIONAL, then the operation will not fail if the attestation verification fails.

If the attestation mode is set to REQUIRED, then the operation will fail if the attestation verification fails. When this happens, the session will return a session status.

See the Session statuses table under 3.1.4 The session status object (opens new window) for possible values.

# Tracking

To track failed attestations in logs, add the following in logback.xml:

Example: Log for Android Play Integrity

<logger name="com.encapsecurity.encap.core.services.attestation.playintegrity" level="INFO"/>

Example: Log for Apple App Attest

<logger name="com.encapsecurity.encap.core.services.attestation.AppAttestAttestationVerificator" level="INFO"/>

# How to roll out app attestation

Availability

  • Apple App Attest is only available for devices running iOS 14 and later.
  • Google Play Integrity is available for all supported Android devices.

# New customers

For a clean Encap installation (with the server and the client SDK on version 3.15 or later), we recommend that the attestation mode is configured as REQUIRED for both Android and iOS devices from the start. This means that all devices that register successfully have been verified to be real Android or iOS devices, activated on a specific Encap app.

You can read more about ensuring that all registrations have a successful attestation in the Reach full security section.

# Existing customers

For existing Encap installations, we recommend carrying out the configuration in steps to minimise the end-user support needed.

  1. Upgrade the server and the client to version 3.15 or later.

  2. Configure the clients to support attestation.

  3. Set the attestation modes to OPTIONAL. Once this is enabled, all existing and new customers will trigger a Play Integrity or App Attest attestation on their next authentication or activation.

    • The transactions will work as normal, but you will now be able to see how many registrations are failing the attestation verification.

    • This can be tracked in the logs or in the REST response for the transaction, making it possible to see the reason for the failure.

    • You can then tweak the configuration, support end-users, and/or update your app to reach an acceptable level of successful attestations.

  4. Set the attestation modes to REQUIRED. If an attestation fails in this mode, the transaction will now fail.

You can read more about ensuring that all registrations have a successful attestation in the Reach full security section.

# Considerations

These considerations apply to both new and existing installations of Encap.

# Play Integrity

  • We recommend that you start with the attestation mode set to OPTIONAL, to avoid potential attestation failures.

  • The default Play Integrity quota is 10,000 requests per day. If the daily activation load is higher than the quota, then the activation will fail. Therefore, the quota limit must be increased by Google on request (opens new window), to be greater than the daily activation load.

  • If this feature is enabled on an existing installation, then the Play Integrity attestation will be triggered on both the next authentication for all existing registrations and new activations. This needs to be considered when setting the Play Integrity quota.

# App Attest

  • We recommend that you start with the attestation mode set to OPTIONAL, to avoid potential attestation failures.

  • If the user base is large, the app may send many requests to the Apple App Attest service. In order to manage resources and avoid being rate limited, this feature could be introduced gradually. You can do this by using App Store Version Phased Releases (opens new window) to release app updates gradually to end-users, over a 7-day period.

  • Apple App Attest is only available for devices running iOS 14 and later, and requires Encap Client API 3.15 and later.

# Reach full security

To ensure all registrations have a successful attestation when performing a transaction, you need to:

  • Set the attestation mode to REQUIRED (applies to Play Integrity and App Attest).

  • Set MINIMUM_REQUIRED_ENCAP_API_VERSION_ANDROID to 3.17 for Play Integrity in the application configuration. This will force older clients to upgrade the app before they can use it again.

  • Set MINIMUM_REQUIRED_ENCAP_API_VERSION_IOS to 3.15 for App Attest in the application configuration. This will force older clients to upgrade the app before they can use it again.

Last updated: 11/04/2024 07:47 UTC

← Geofencing →