Tutorial — Knox Attestation (v3)

Get a Vendor-Unique Attestation Key

In the header of every REST API call to the Attestation server, identify yourself by encoding your own unique Vendor-Unique Attestation Key.

To get this key:

1. Go to: Get a License.
2. Enter a unique alias to describe this Vendor-Unique Attestation Key. This is mandatory.
3. Click Get License Key.
4. Under License Number, copy the key to use in your REST API calls.

Set up a server

In the following examples, we use an Apache server on a Linux operating system with PHP as the scripting language. You can set up such a web server from scratch quite simply. If you don’t have a web server, you can enroll in a free or trial cloud service to get quick access to one.

If you are new to web server setup, here are some basic Linux commands to set up the server:

install Ubuntu 14.0
sudo apt-get update
sudo apt-get install apache2
sudo apt-get install php5 libapache2-mod-php5 php5-mcrypt php5-curl
sudo /etc/init.d/apache2 restart

Alternatively, you can use a pre-built environment, such as that provided by Apache Friends.

Once you have a web server with PHP support, copy your scripts into the folder /var/www/html. In the sample Attestation app, there are two PHP scripts, called nonces.php and measurements.php, which you can copy into this folder.

Get a nonce

A nonce is a random value that uniquely identifies each attestation request. To protect from replay attacks, each nonce is valid only for a short period of time. This ensures that the Attestation server can fail requests made using an invalid nonce once it expires, which prevents malicious attackers from accessing a past attestation result. A nonce also serves as a unique identifier for each attestation request.

• Get a nonce from the attestation server
• Get a nonce from web script

$curl = curl_init();curl_setopt($curl, CURLOPT_URL, " https://attest.samsungknox.com/v3/nonces";curl_setopt($curl, CURLOPT_POST, 1);curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);curl_setopt($curl, CURLOPT_RETURNTRANSFER, false);  $headers = array(   'Accept: application/json',   'Content-Type: application/json'',   'Authorization: Bearer '.$api_key,   'Ats-Request-Id: '.$ats_request_id  );  curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);  if(!curl_exec($curl)){    die('Error: "'. curl_error($curl). '" - Code: '. curl_errno($curl));  }

// identify the URL of your web serverprivate static final String URL_MDM_SERVER_NONCE = "http://attestation.example.com/nonces";// through HTTP, send a nonce request to your web serverString response = HttpClient.getInstance().getNonce(URL_MDM_SERVER_NONCE, ”ATTESTATION_KEY”, “REQUEST_ID”));

For details about the syntax of the REST API calls to the Attestation Server, see the Attestation REST API reference.

Start attestation

Start attestation using EnhancedAttestationPolicy.

// import EnterpriseKnoxManager
// import EnhancedAttestationPolicy
// import EnhancedAttestationPolicyCallback

import com.samsung.android.knox.EnterpriseKnoxManager;
import com.samsung.android.knox.integrity.EnhancedAttestationPolicy;
import com.samsung.android.knox.integrity.EnhancedAttestationPolicyCallback;

// declare EnhancedAttestationPolicy to call api
private EnhancedAttestationPolicy mPolicy;
EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);
mPolicy = ekm.getEnhancedAttestationPolicy();

//make callback to receive attestation result
EnhancedAttestationPolicyCallback cb = new EnhancedAttestationPolicyCallback() {
 @Override
 public void onAttestationFinished(final EnhancedAttestationResult result) {}
};

// call startAttestation (AUK is vendor Unique Key)
mPolicy.startAttestation(AUK, nonce, cb);

Handle attestation result

Your app handles the attestation result by passing it to the Callback method. This method handles the result sent by the EnhancedAttestationPolicy.

/// import package that defines constants for values returned by EnhancedAttestationResult
import com.samsung.android.knox.integrity.EnhancedAttestationResult

EnhancedAttestationPolicyCallback cb = new EnhancedAttestationPolicyCallback() {
 @Override
 public void onAttestationFinished(final EnhancedAttestationResult result) {
  if (result.getError() == EnhancedAttestationResult.ERROR_NONE) {
   Log.i(TAG, "attest: onSuccess");
   //should compare nonce to unique Id.
   if (nonce.equals(result.getUniqueId())) {
    //nonce verification success
   }
  ...
  } else {
   Log.i(TAG, "attest: onFailure");
   if (nonce.equals(result.getUniqueId())) {
    //nonce verification success
   }
  ...
  }
 }
};

Get verdict

• Get a verdict from web script
• Get a verdict from attestation server

// identify the URL of your web serverprivate static final String URL_MDM_SERVER_MEASUREMENTS = "http://attestation.example.com/attestations/";String response = HttpClient.getInstance().getAttestationStatus(URL_MDM_SERVER_MEASUREMENTS + nonce, “ATTESTATION_KEY”, “REQUEST_ID”);

$curl = curl_init();curl_setopt($curl, CURLOPT_URL, "https://attest.samsungknox.com/v3/attestations/".$nonce);curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);curl_setopt($curl, CURLOPT_RETURNTRANSFER, false);$headers = array(    'Accept: application/json',    'Content-Type: application/json',    'Authorization: Bearer '.$api_key,    'Ats-Request-Id: '.$ats_request_id);curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);if(!curl_exec($curl)){    die('Error: "'. curl_error($curl). '" - Code: '. curl_errno($curl));}               }                

Display the verdict

You can process the verdict in either the web script or Android app.

Here, we use the Android app to convert the attestation response into a JSONObject to extract the results of the attestation, including the attestation verdict:

//Parsing result of attestation
JsonObject = new JSONObject(mAttestationStatus);
Gson gson = new GsonBuilder().disableHtmlEscaping().create();
EAResultInfo eAResultInfo = gson.fromJson(mAttestationStatus.responseData, EAResultInfo.class);
eAResultInfo.toString();

public static class EAResultInfo {
 int version;
 String nonce;
 String verdict;
 int warrantyFuseState;
 int trustBootState;
 int deviceIdState;

 App app;
 long timestamp;

 public String toString() {
  return "Version: " + version +
   "\nNonce: " + nonce +
   "\n\nVerdict: " + verdict +
   "\nWarranty bit: " + warrantyFuseState +
   "\nTrust boot: " + trustBootState +
   "\nDevice id Attestation: " + deviceIdState +
   "\n\nTimeStamp: " + timestamp +
   "\n\nApp package: " + app.pkg +
   "\n\nApp signature: " + app.signature;
 }

 static class App {
  String pkg;
  String signature;
 }
}

For details about the fields returned in the result, see the Attestation REST API reference.

A verdict of:

• Yes — indicates that the device passed the integrity checks
• No — indicates that the device might have failed the integrity checks

The Warranty Bit indicates device has been rooted.

• 0 — never rooted.
• 1 — rooted.

The Trust boot indicates cross binary (or OEM unlock).

• 0 — official binary.
• 1 — Cross binary or OEM unlock.

Device ID Attestation

• 0 — device ID passed integrity checks.
• 1 — IMEI and S/N has been modified.
• -1 — not supported