Back-End Setup

The back-end library is downloaded from our file server as a Java JAR file. It can be directly embedded into a Java web application or, if you do not have an existing Java back end, proxied or forwarded to a separate service that uses the library. This can be accomplished with a framework like gRPC.

AppAttestation Class

The library is implemented in Java 11 and includes a single class, AppAttestation. Instances of this class are created in the following manner:

AppAttestation attestation = new AppAttestation(secret, timeout, flags);

The secret is the shared secret, as a byte array, that matches the secret in the App Shielding configuration. If the client used the Base64 encoded version of the string "hello", for example, the secret on the server side would be "hello".getBytes(StandardCharsets.UTF_8).

The timeout, in seconds, sets how long a challenge is valid. Lastly, flags are derived from the included CHALLENGE_FLAG enum to define which app security checks are required to solve the challenge token. The following example uses every possible flag:

EnumSet<CHALLENGE_FLAG> flags = EnumSet.of(
    CHALLENGE_FLAG.ROOT,
    CHALLENGE_FLAG.REPACKAGING,
    CHALLENGE_FLAG.RUNTIME_MANIPULATION,
    CHALLENGE_FLAG.HOOKING_FRAMEWORKS
);

You can omit flags as needed (e.g., remove CHALLENGE_FLAG.ROOT to allow rooted or jailbroken devices to solve the challenge), though at least one flag is required.

An app protected with App Shielding performs these security checks regardless if the corresponding challenge flags are set. In fact, some checks (like repackaging) are designed to crash the app when detected. However, adding the CHALLENGE_FLAG.REPACKAGING flag acts as an additional layer of security to your back end in the event that an attacker has prevented the repackaged app from crashing.

Instances of AppAttestation then have the following methods:

Implementation Example

The back-end library makes no assumptions about your server setup, so it can be integrated with any web framework or protocol. However, because the challenge is a byte array, it must be properly encoded for the chosen transport mechanism. In a REST API, for instance, you might want to send the token as a Base64 encoded string in an HTTP header. That process could look like the following example:

byte[] challengeToken = attestation.generateChallengeToken();
String challengeHeader = Base64.getEncoder().encodeToString(challengeToken);

response.addHeader("X-Challenge", challengeHeader);

When the server receives the response from the app, it similarly needs to decode the token to a byte array before calling the isResponseOk() method. If isResponseOk() returns false, then the server can assume the app or request is not secure and act accordingly. For example:

String responseHeader = request.getHeader("X-Response");
byte[] responseToken = Base64.getDecoder().decode(responseHeader);

if (!attestation.isResponseOk(responseToken)) {
    response.sendError(401, "Unauthorized");
    return;
}