Menu

Enhanced Attestation (v3)

On this page

Samsung Knox Enhanced Attestation is a feature that verifies a Samsung device's data integrity by checking that the device isn't rooted or running unofficial firmware.

Knox 3.4 introduces the latest version of Attestation (v3) running on flagship devices from the Note 10 onwards. Enhanced Attestation uses the EnhancedAttestationPolicy class and v3 REST API. For information about the previous version of Attestation, see Attestation (v2).

About Enhanced Attestation

Samsung Attestation Key

Enhanced Attestation uses the Samsung Attestation Key (SAK) to prove:

  • The key is protected by a secure hardware.
  • The device is manufactured by Samsung.
  • The device ID isn't comprised.

When verifying devices as Samsung devices, it's important to note that certificate change alone isn't enough to prove that a device is a Samsung device since malicious attackers can send a certificate chain generated by other devices.

With SAK, it's injected during the manufacturing process of a Samsung device to ensure it's protected by secure hardware. When verifying devices as Samsung devices, the attestation certificate chain is validated, which contains a hash value that includes the device IMEI and serial number. This hash value is embedded as the unique identifier (UID) in the subject field, which is then used to prove the device ID hasn't been changed after the SAK certificate has been generated.

Enhanced Attestation

With Knox Enhanced Attestation, device integrity can be validated on-demand by a remote Samsung Attestation server.

When an attestation request is made:

  1. The device side Knox Enhanced Attestation agent uses the Keystore attest API to receive an attestation certificate chain paired with an application private key.
  2. The attestation certificate chain is used by apps for validation, which consists of:
    • The attested key certificate — A certificate of the application key stored and managed in the Keystore.
    • The attestation certificate — The certificate of SAK. The attestation key is used to sign the attested key certificate.
    • The root certificate — The certificate of the root key issuing the SAK certificate, which is the last component of the attestation certificate chain.
    NOTE — When validating the chain, the root certificate must be obtained through another route since the root certificate is public data. It's recommended that the root certificate is used as a Trust root or to be compared with the root certificate of the attestation certificate chain.
  3. The Knox Warranty Bit value is checked to determine if a device has been rooted.
  4. The Knox Enhanced Attestation agent combines proprietary data to produce an attestation verdict, which indicates if tampering is suspected.

The attestation verdict is sent to the requesting web server on the TLS connection between the Samsung Attestation Server and the partner's web server. This process ensures the attestation verdict is secured during transfer to protect it from being modified.

If device tampering is suspected, security measures may include: uninstalling apps from the device, erasing sensitive data, checking the device location, or simply logging the event for later action.

Signature

For a remote MDM server to verify the integrity and authenticity of an attestation result, the result must be signed by the attestation app inside the device's TrustZone.

On each device that supports TrustZone-based Integrity Measurement Architecture (TIMA) Attestation, a unique RSA private/public key pair is generated when a device is manufactured. This key pair is the SAK. Note that the public key of SAK is also signed by a special Samsung Root Key to generate a X.509 certificate. SAK and its certificate are secured in the device's TrustZone.

When the device is booted up for the first time, another RSA private/public key pair is generated specially for the purpose of attestation. This is the Attestation Key. To generate a X.509 certificate, the Attestation Key's public key is signed by SAK. The Attestation Key and its certificate are secured in the device's TrustZone.

The chain of trust is formed by the Attestation Key, SAK, and the Samsung Root Key, which is is used to sign the SAK certificate.

After attestation result is generated, it will be signed by Attestation Key and the signature will be appended to the result. To verify the signature, the Attestation Key certificate and SAK certificate are also appended to the result.

Certificate and Verification

When the attestation result is verified by the server, it must have the Samsung Root Key and certificate installed and trusted. Once installed, it's used to verify the SAK certificate, Attestation certificate, and the signature. This ensures the integrity of the attestation result.

To protect from a replay attack, which replays the attestation result collected on a different device or the same device before it was compromised, TIMA Attestation requires the caller to send a nonce in the request.

The nonce is returned as part of the Attestation result, and the returned nonce is validated by the caller before accepting the result: Below illustrates how a MDM server can request TIMA attestation.

Figure 1: Illustrates how an MDM server can request TIMA attestation

Secure communication

To ensure a secure communication with the Attestation server, use an HTTPS connection and a SSL certificate to encrypt data sent over the connection. Make sure to purchase an SSL certificate from a trusted provider. Self-signed certificates are not trusted by the Attestation server. Also, make sure your certificate contains the complete certificate chain. For help, please consult with your web provider.

How Attestation works

To perform attestation for a device, you must create both:

  • An Android app to initiate the attestation check on a device
  • A web script to communicate with Samsung's Attestation server

Here is the end-to-end process:

  1. Get a nonce: a random value that uniquely identifies each attestation request. Each nonce is valid for a short time period, after which the Attestation Server fails any request made using that nonce. This is to avoid a replay attack that could allow an attacker to reuse a past attestation result.
  2. Start attestation: To begin the attestation, your app can use startAttestation API in knoxsdk. The Knox Attestation Agent will pass attestation result over callback. Your app needs to handle attestation result(uniqueId).
  3. Get the attestation verdict: a verdict result is received from Attestation Server using a unique Id. The verdict result indicates if a device has passed or failed its integrity checks. Note that the requested nonce and unique Id should be same.

Obtain an Attestation REST API key

In the header of every REST API call to the Attestation server, ensure that you identify your app by encoding your own unique Attestation key.

If you haven't yet, you'll need to obtain an Attestation REST API key before you begin:

  1. Login to the Samsung Enterprise Alliance Program (SEAP) portal.
  2. Go to PARTNER RESOURCES > My license Keys.

  3. Click the GET A LICENSE button.
  4. Under the KNOX PLATFORM FOR ENTERPRISE (KPE) KEY tab, select a key type:
    • Development key — Provides access permissions for development purposes. Only one development key at a time is permitted.
    • Commercial key — Once your app is ready, deploy it commercially using commercial keys.
  5. Select Optional key.

  6. Select the REST API KEY tab.

  7. For Add a key alias, enter a license key name to help you identify this license key on the License Key Summary page.
  8. Click the GET LICENSE KEY button.

After obtaining your attestation REST API keys, activate your license key.

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

In your web script, build the request to get a nonce from the Attestation Server. Our sample app does this using PHP, which you can find in the file nonces.php:

$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));
  }

Get a nonce from your web script

In your Android app, request a nonce from your web server. On the web server, you need a script to take the request and forward it to Samsung’s Attestation server.

In the sample Attestation app, there is a script called nonces.php that does this:

// identify the URL of your web server
private static final String URL_MDM_SERVER_NONCE = "http://attestation.example.com/nonces";

// through HTTP, send a nonce request to your web server
String response = HttpClient.getInstance().getNonce(URL_MDM_SERVER_NONCE, ”ATTESTATION_KEY”, “REQUEST_ID”));

In this example, we use a string variable called response to store the resulting nonce. Later, you will parse the response into a JSON object and pass it to the Attestation agent on the device.

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

Send a blob to your web server

Send the result (unique Id) to your web server using the HTTP protocol. On the web server, you need a script to take the unique id which should be same as nonce and forward it to Samsung’s Attestation server. In the sample Attestation app, there is a script called measurements.php that does the following:

// identify the URL of your web server
private 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”);
				

In this example, we use a string variable called response to store the resulting verdict. Later, you will parse the response into a JSON object and display the verdict details.

Get a verdict from the Attestation server

In the web script, build a request to get the attestation verdict from the Attestation server. Our sample code does this using PHP, which you can find in the source code file measurements.php:

$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 {
 String nonce;
 String verdict;
 int warrantyFuseStatus;
 int verifiedBootState;
 int trustBootState;
 String idAttestationStatus;

 App app;
 long timestamp;

 public String toString() {
  return "Nonce: " + nonce +
   "\n\nVerdict: " + verdict +
   "\nWarranty bit: " + warrantyFuseStatus +
   "\nVerified boot: " + verifiedBootState +
   "\nTrust boot: " + trustBootState +
   "\nID Attestation: " + idAttestationStatus +
   "\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

  • OK — device ID passed integrity checks.
  • Not OK — IMEI and S/N has been modified.