Conceptual Overview

OneSpan API Protection uses a challenge-response mechanism where a server provides a challenge token that needs to be solved by the app. A response token is then calculated in the app and verified on the server side to determine if the app is legitimate and in a secure state.

From a high-level view, this process looks like the following image:

With a little more detail, the workflow can be broken down into the following steps:

1. Client initiates a handshake with the server.

2. Server generates and sends a challenge token to the client.

3. Client uses the challenge token to generate a response token and sends it to the server.

4. Server verifies the response token and authorizes or rejects the client’s request.

These transactions can take place over multiple REST requests, an open socket connection, or within any other communication setup you might have. Similarly, the challenge and response tokens can be exchanged as HTTP headers, payload elements, etc. The exact implementation is up to you.

Secret Hashing

The challenge-response mechanism uses keyed hashes for its internal response calculation. In its simplest form, you can think of it as a cryptographic algorithm like HMAC_SHA256(key=secret, data=challenge), where the key is a shared secret between the server and the app, and the data a "challenge" generated by the server.

The secret is not specific to a user or app installation. Instead, it is a common shared secret between the back end and all instances of the specific app version. The secret is protected by App Shielding and must be included in the App Shielding configuration file. It also needs to match the secret used on the server back end for successful verification.

Tokens

The challenge and response tokens are encoded with additional information that provides extra functionality. This information influences how the challenge is calculated and how the response token is validated on the back end.

The challenge token contains the following information:

• A timestamp

• Security flags (e.g., is the device rooted or jailbroken)

The response token contains the following information:

• A timestamp

• The original challenge

• The calculated response

The challenge token is exactly 32 bytes and encodes to Base64 in 43 bytes or hexadecimal in 64 bytes. The response token is exactly 80 bytes and encodes to Base64 in 107 bytes or hexadecimal in 160 bytes. After encoding, these tokens can, for instance, be sent as HTTP header values through existing HTTP traffic between the app and server.

Performance

The OneSpan API Protection APIs are stateless, meaning they do not read or write to memory or any form of storage. On the client side, OneSpan API Protection relies on existing App Shielding mechanisms, so no extra overhead is added to perform the needed security checks.

The act of hashing a token also has very little effect on performance. A single CPU core/thread can reasonably process tens of thousands of hashes per second.

Of course, performance ultimately depends on how OneSpan API Protection is integrated and how often requests are verified. Adding OneSpan API Protection to every API request would have a greater impact than only adding it to your authentication-related APIs, for example. There will always be an added network cost incurred by exchanging the tokens across your chosen protocol.