Configuration of App Shielding for iOS apps

To configure App Shielding for your applications, select the options on the Configuration Page of the OneSpan Customer Portal as needed.

Configuration options for iOS

Configuration options for iOS

Option	Description
Settings
Exit on debugger URL [Deprecated]	There is no guarantee that this URL is triggered even though a debugger is attached. It is recommended to not use this option. This option is deprecated and will be removed in the future.
Check developer mode	Checks if Developer Mode is enabled on the device. Developer Mode was introduced in iOS 16 and enables development capabilities on an iOS device. When enabled, it will reduce the security of the device since it opens up to some attack vectors abusing developer-only functionality.
Exit on developer mode	Determines whether to exit the application when Developer Mode is detected on the device.
Exit on developer mode URL
Check hooking frameworks	Checks if hooking frameworks were detected in the application’s process.
Exit on hooking frameworks	Determines whether to exit the application when hooking frameworks are detected in the application’s process. Depends on: Check hooking frameworks
Exit on hooking frameworks URL	If Exit on hooking frameworks is used, a browser can be launched with a preconfigured URL which may explain the problem to the user. If no URL is configured, then the browser is not invoked. Depends on: Exit on hooking frameworks
Check jailbreak	Checks if the device on which the application runs is jailbroken.
Exit on jailbreak	Determines whether to exit the application if the device is jailbroken. Depends on: Check jailbreak
Exit on jailbreak URL	Depends on: Exit on jailbreak
User screenshot monitor	Checks if the user takes a screenshot of the application.
Exit on user screenshot	Determines whether to exit the application when the user takes a screenshot. Due to constraints related to the operating system, App Shielding cannot prevent the user from taking a screenshot. The screenshot will be taken even if the application has been exited.
Exit on user screenshot URL	Depends on: Exit on user screenshot
Block external screens	Blocks external screens (connected through an adapter or through Airplay) and prevent them from mirroring the application window. This feature is unavailable to apps using UISceneDelegate in iOS 13 and later.
Application signer certificate	The certificate used to sign the application.
Prevent system screenshot	Prevents iOS from taking screenshots of the application. This screenshot is available on the list of open applications when the application is in the background.
Prevent system screenshot only in background	Only block an application once it completely enters the background. Depends on: Prevent system screenshot.
Prevent system screenshot bg color	The background color to use for the screenshot replacement graphics. The value describes the color as a 6-character hexadecimal string, providing the red, green, and blue values (e.g. ffffff for white, ff0000 for red, 00ff00 for green, and 0000ff for blue). Depends on: Prevent system screenshot
Prevent system screenshot image path	The path to an image to use for screenshot replacement. If this resolves to a UIImagecompatible image file or a XIB file containing a single view, the resulting view will be presented in the event a screenshot is attempted. The background color defined with the Prevent system screenshot bg color option will fill in any areas not covered by the view (see Prevent system screenshot bg color). The path to the image is relative to the application bundle, the XIB is just the name of the XIB within the main bundle. If the image is in a subdirectory, use a slash (/) as a directory separator (e.g. subdir/image.png). The image will be centered and scaled to the screen size, keeping the aspect ratio. If the image aspect ratio does not match the screen, the parts of the screen which are not covered by the image will show the specified fill color. If the image could not be loaded for any reason, the screenshot replacement will fall back to use a specified solid background color instead. Depends on: Prevent system screenshot
Prevent system screenshot blur strength	Determines whether the screenshot replacepment graphics show a blurred representation of the window. A positive value enables this feature. Higher values result in stronger blurring. If blurring fails for any reason, the screenshot replacement will fall back to use a solid background color instead, as defined with the Prevenst system screenshot bg color option (see Prevent system screenshot bg color). This does not necessarily prevent an attacker from recovering the blurred information. Depending on the nature of the data and the strength of the blur filter, this may not even be particularly difficult. However, if a proper strength is chosen, this may be sufficient to hide the information from accidental revelation. Depends on: Prevent system screenshot
Check screen recording	Checks if a screen is being recorded.
Exit on screen recording	Determines whether to exit the application when the screen is being recorded. Depends on: Check screen recording
Exit on screen recording URL	If Exit on screen recording is used and an URL is set, a web browser can be started with a preconfigured URL to explain the problem to the user. If no URL is configured, then the browser is not invoked. Depends on: Exit on screen recording
Prevent runtime library injection	Prevents injection of libraries into the application during runtime.
Runtime library injection prevention mode [Deprecated]	Defines a policy for how the decision on blocking an injected library is made. This option will be ignored on iOS/iPadOS 12 or newer, the "non-strict" method will always be used. Since iOS/iPadOS (and earlier) is no longer supported by App Shielding, this option is deprecated and will be removed. For more information, see Runtime library injection prevention mode.
Check load-time library injection	Check if libraries were injected into the application’s process at load-time. App Shielding protects against injection of libraries during runtime. However, it cannot protect against injection of libraries during load-time. Because of that, and also as a second layer of protection against injection during load-time, App Shielding can detect when there are libraries inside the process that should not be there, i.e. have been injected.
Exit on load-time library injection	Determines whether to exit the application when libraries were injected into the application’s process at load-time. OneSpan highly recommends having this setting enabled for release versions, ideally in combination with the browser reporting feature. In case of libraries being injected into the app's process, the application cannot be trusted anymore, meaning that code that reacts to callbacks can easily be patched out. Also note that code injection is usually happening on jailbroken devices that have the hooking framework MobileSubstrate installed, which injects libraries into all processes. Because of that, users of apps that are protected by App Shielding should be advised to uninstall MobileSubstrate. Depends on: Check load-time library injection
Exit on load-time library injection URL	If Exit on load-time library injection is used, a browser can be launched with a preconfigured URL which may explain the problem to the user. If no URL is configured, then the browser is not invoked. Depends on: Exit on load-time library injection
Updatable configuration
Updatable configuration	Specify whether the app will use the Automatic Configuration feature.

Since App Shielding v4.0, it is no longer possible to disable the checkRepackaging and exitOnRepackaging configuration options. If App Shielding detects that the application was repackaged, it will crash and shutdown the application during startup. Ensure that you always specify the correct signer certificate, configured with the applicationSignerCertificate option. For more information, see Application signer certificate.

Also, as of App Shielding version 4.0, anti-debugging has been improved to ensure that the blockDebugger, checkDebugger, and exitOnDebugger options cannot be disabled.

Since App Shielding v4.0, it is no longer possible to disable the checkRepackaging and exitOnRepackaging configuration options. If App Shielding detects that the application was repackaged, it will terminate unexpectedly and shut down the application during startup. Ensure that you always specify the correct signer certificate, configured with the applicationSignerCertificate option. For more information, see Application signer certificate.

Also, as of App Shielding version 4.0, anti-debugging has been improved to ensure that the blockDebugger, checkDebugger, and exitOnDebugger options cannot be disabled.

Application signer certificate

The repackaging feature of App Shielding will validate the signer of the application and check if one of the certificates given through this option matches the signer.

iOS apps can be signed in different ways:

• For development, apps are signed with a development certificate. In this case, the app can only be installed on a limited set of registered development devices.

• For in-house deployment (e.g. if an enterprise developer program membership is available), apps are signed with an in-house deployment certificate. Apps that are signed like this can be installed on all supported iOS devices.

• For delivery to iTunes Connect and subsequently TestFlight and the App Store, apps are signed using an App Store deployment certificate. However, when the app is deployed through TestFlight or the App Store, Apple re-signs the app with its own TestFlight or App Store certificate. This can lead to confusion since the deployed app is not signed by the same signer that was used to sign the app when it was uploaded to Apple. Because of that, App Shielding implicitly trusts the TestFlight and App Store certificates.

When App Shielding validates the application signer, it first checks if the application was signed by Apple for App Store or Test Flight deployment. If this validation fails, App Shielding will check if the app was signed by one of the configured applicationSignerCertificate fields using the development or enterprise deployment.In cases of App Store or TestFlight deployment, the applicationSignerCertificate field can be empty.

This public certificate can be safely extracted from the keychain you use to sign the app. Upload the certificate in .pem, .der, or .cer format.

To export the certificate from the keychain

1. Launch Keychain Access.
2. Right click on the certificate to use.
3. Select Export….
4. Select the Certificate file format (.cer)

Runtime library injection prevention mode

Determines how an injected library is blocked.

This option is ignored on iOS/iPadOS 12 or newer, and the "non-strict" method will always be used. Since iOS/iPadOS (and earlier) is no longer supported by App Shielding, this option is deprecated and will be removed.

Possible values:

• strict. Performs a strict check of libraries. This might block certain system libraries that are also loaded as extensions.

• non-strict. Performs a non-strict check of libraries. This will not block system libraries that are loaded as extensions, but reduces security.

• policy. Performs a strict check on jailbroken devices and a non-strict check on devices that are not jailbroken.

For strict checks, App Shielding considers the library as non-malicious if one of the following conditions apply:

• The library is signed by Apple, or the configured signer of the app. This is the normal case for libraries shipped with the app.
• The library comes from the shared library cache, and is not found in the file system if the dynamic loader dyld overrides the library cache. This is the normal case for system libraries.

For non-strict checks, the following condition is added:

• The library is ad-hoc signed in exactly the same way Apple ad-hoc signs some of its libraries. This is the case for system libraries that are not in the shared library cache.

This option is deprecated and will be removed in the future.

Updatable configuration

With this option, you can specify whether the app will use the Automatic Configuration feature.

When you enable this option, the portal displays additional configuration fields:

• Request timeout (seconds): Specify the duration in seconds before the client device stops connecting to the server and sends a request timeout error.

• Config Identifier: Identify for which application the configuration update is intended. A configuration update file must contain the identical config identifier as the original configuration for the app, and must be created with the exact same version of App Shielding.

  If not specified or set to an empty string, the config identifier is set to the package ID of the app, which means that any configuration update for the app must be created with the same input app. However, using the config identifier option allows for multiple apps to use a common source for the updatable configuration file.

• Certificate type: Use this field to upload your server certificate in the .pem file format.

• URL: Specify the URL of the web page where the configuration can be downloaded. The server must be running with a config.dat file accessible in the destination path.

  It is possible to use substitution variables encoded in the URL, consistent with the substitution variables launching Exit URL. For more information, see URL variable substitution for the updatable configuration.

• Client Certificate: Upload a TLS client certificate. This must be exported as a base64 string from a pkcs12 file.

  The base64 string can be extracted from the pkcs12 file using this command:

  base64 client_cert.p12 > client_cert.b64

• Password: Password used to generate the pkcs12 client certificate file.