The update process

If the app is configured to allow updating the configuration, App Shielding will download the updated configuration from a pre-configured URL at specific events.

App Shielding will attempt to update the configuration every time it determines that the application should be terminated as a result of a security policy violation.

App Shielding will update the configuration using an HTTP GET request to the configured URL, and the process will succeed only if:

• The server responded with an HTTP status code 200 with a non-zero data payload.
• The data payload can be validated via cryptographic signature and decrypted.
• The configuration data contains a time stamp that is newer than the existing configuration.
• The configuration data contains an identifier that is equal to the existing configuration. The configIdentifier option is set to the bundle identifier of the app by default, but can manually be set to anything in the configuration.

App Shielding will ignore any configuration that it fails to download or verify without any visible warnings.

App Shielding will use the If-Modified-Since header and thereby allow the server to respond with a 304 response code if the configuration file has not been changed.

Configuration selection

By default, any App Shielding-protected app will use the preloaded initial configuration until it is superseded by an updated configuration. The initial configuration is bundled inside the application AAB, APK, or IPA and technically cannot be replaced. Instead, a downloaded configuration can be used.

When App Shielding downloads a new configuration, the new configuration is stored in the file system after verification.

When the application is launched, App Shielding decodes both the initial and the downloaded configurations. The downloaded configuration will be preferred if it is both newer than the initial configuration and correctly verified. Otherwise the downloaded configuration will be ignored as invalid or obsolete.

When a downloaded configuration is used, it completely replaces the initial configuration. This means that the downloaded configuration must be correct and cover all aspects of the App Shielding configuration.

Configuration versioning

Each configuration file contains an internal time stamp value, which is used for implicit versioning. The time stamp specifies the time of the configuration creation and App Shielding will always prefer the newest configuration.

Due to this implicit configuration versioning it is important that any configuration update is created after the process to protect the app with App Shielding has been completed. If the configuration is updated before the App Shielding protection for the app is in place, the initial configuration will be timestamped and considered newer, which would render any update obsolete.

This design choice is deliberate as it facilitates tracking and the explicit versioning of the configuration deployment for the app owner.

Client configuration

For more information about Automatic Configuration Update settings, see OneSpan Customer Portal and OneSpan Customer Portal.

Server configuration

App Shielding should be configured to update from HTTPS connections such as https://config-update.example.com/config/config.dat

To generate a new configuration, you must use the same version of App Shielding that was initially used to protect the application.

To create a new configuration file

1. Connect to the OneSpan Customer Portal or OneSpan Mobile Portal.
2. Create your new App Shielding configuration.
3. Verify that all settings are correct.
4. Upload the updatable configuration.
5. Shield your application.
6. Download the .zip file. This archive contains your new config.dat file.
7. Publish the new config.dat file on your server.

The App Shielding package contains a sample server that can be used to demonstrate how client-server communication works.