Client-Side Setup

The shared secret is added to the app by including an <appAttestationSecret> element in the main App Shielding configuration file and then running the Shielding Tool again. The secret is a sequence of bytes and should be encoded as a Base64 string for the config file. The following example uses the Base64 encoded version of the string "hello":

<?xml version="1.0" encoding="UTF-8"?>
<shield>
    <config>
        ...
        <appAttestationSecret v="aGVsbG8="/>
    </config>
</shield>

Next, import the OS-appropriate SDK into your mobile app project. For both Android and iOS, the SDK includes an AppAttestation class with a check() method. The check() method takes the challenge token from the server and produces a new response token for the server to later validate.

The challenge and response tokens are binary data, so the application code must decode and encode them (e.g., as Base64 or hex strings) when transporting to and from the server. See below for operation system-specific examples.

Android Integration

Add the ShieldSDK-app-attestation Maven dependency to your Android project. This is found in the App Shielding package’s SDK/maven/ directory. For more information on importing App Shielding libraries, refer to the App Shielding for Android Reference Documentation documentation.

The AppAttestation class is then used by calling the check() method on a class instance. For example:

import no.promon.shield.appattestation.AppAttestation;
...

new AppAttestation().check(token)

Remember, though, that the token is binary data that would have been encoded by the server. It will need to be decoded before check() is called and the returned response token encoded again before sending it back to the server. In a REST API, using HTTP headers to transport the tokens as Base64 strings, this process might look like the following example:

String challengeHeader = response.headers().get("X-Challenge");
byte[] challengeToken = Base64.getDecoder().decode(challengeHeader);

byte[] responseToken = new AppAttestation().check(challengeToken);
String responseHeader = Base64.getEncoder().encodeToString(responseToken);

request.addHeader("X-Response", responseHeader);

The above example is based on the OkHttpClient library. The exact methods to use will vary based on your own client setup.

If you do not run the Shielding Tool command line on the app,  the secret is not embedded in the app. This means the check() method will generate an invalid token that the back-end library will not be able to process.

iOS Integration

Add the ShieldSDK.xcframework bundle from the App Shielding package to your iOS project. For more information on importing App Shielding libraries, refer to the App Shielding for iOS Reference Documentation  documentation.

The AppAttestation class is then used by calling the check() method in the following manner:

import ShieldSDK
...

AppAttestation.check(token)

Remember, though, that the token is binary data that would have been encoded by the server. It will need to be decoded before check() is called and the returned response token encoded again before sending it back to the server. In a REST API, using HTTP headers to transport the tokens as Base64 strings, this process might look like the following example:

guard let challengeHeader = response.allHeaderFields["X-Challenge"] as? String else {
    print("X-Challenge header not found")
    return
}

guard let challengeToken = Data(base64Encoded: challengeHeader) else {
    print("Error decoding Base64 value")
    return
}

let responseToken = AppAttestation.check(challengeToken)
let responseHeader = responseToken?.base64EncodedString()

request.setValue(responseHeader, forHTTPHeaderField:"X-Response")

The above example is based on the URLSession class. The exact methods to use will vary based on your own client setup.

If you are using Objective-C instead of Swift, the process will look more like the following example:

#import <ShieldSDK/Shield.h>
...

NSString *challengeHeader = response.allHeaderFields[@"X-Challenge"];
NSData *challengeToken = [[NSData alloc] initWithBase64EncodedString:challengeHeader options:0];

NSData *responseToken = [AppAttestation check:challengeToken];
NSString *responseHeader = [responseToken base64EncodedStringWithOptions:0];

[request setValue:responseHeader forHTTPHeaderField:@"X-Response"];

If you do not run the Shielding Tool command line on the app, the secret is not embedded in the app. In this case, the check() method simply returns nil.