Since: Knox API Level 7
public class

AttestationPolicy

extends Object
java.lang.Object
   ↳ com.samsung.android.knox.integrity.AttestationPolicy

Class Overview

The Attestation agent service provides a front end to retrieve attestation data from the TrustZone. The service interacts with the TrustZone to obtain the Attestation measurements which can be verified by an attestation server.

It will interact with the MDM client to start the attestation process as well as providing back the Attestation results in the form of a blob.

Below is the format of the blob containing the attestation results.

1. Exitcode(1 byte)|Error_str_len(1 byte)|Error String(Error_str_len bytes): for example (0|7|"Success")

2. Version_number (1byte)

3. Size_of_data(2 bytes)|Data(size_of_data bytes): the format of Data is described below.

4. Signature(256 bytes): the signature of the entire Data segment. We are using PKCS #1 RSA version 1.5, and SHA256.

5. Cert_len1(2bytes)|certificate1(cert_len1 bytes)

6. Cert_len2(2bytes)|certificate2(cert_len2 bytes)

Data segment consists of multiple subsections. Each subsection is in the format of:

Type(1 byte)|length(2 bytes)|data(length bytes)

The types are defined as the following:

1. 0x01: measurement (seven 32-byte SHA256 hashes)

2. 0x02: verdict (a string which could be: "Yes", "No", "Unknown")

3. 0x03: nonce (must be 32 bytes)

4. 0x04: SEAndroid status (No longer used)

5. 0x05: Serial number (4 bytes)

6. 0x06: Warranty violation fuse (tamper fuse) value (1 byte)

7. 0x07: TIMA Dashboard (variable length)

8. 0x08: Device IMEI Hash (SHA256)

9. 0x0A: Wifi MAC Address Hash (SHA256)

10. 0x0B: Aboot version (No longer used)

11. 0x0C: Kernel version (No longer used)

12. 0x0E: Reason that verdict is "No" (since KNOX 2.8)

13. 0x40: The Package Digest count (since KNOX 2.6)

14. 0x41: Package Digests using SHA256 (since KNOX 2.6)

15. 0x42: Package Names (up to 50 characters, delimited by '|') (since KNOX 2.6)

16. 0x43: Package Versions (since KNOX 2.6)

17. 0x44: Certificate Digest count (since KNOX 2.6)

18. 0x45: Certificate Digests using SHA256 (since KNOX 2.6)

19. 0x46: UCM ODE Vendor ID (since KNOX 2.8)

20. 0x47: UCM ODE plug in signature (since KNOX 2.8)

Since
API level 7
KNOX 1.0.1

Summary

Constants
String ACTION_KNOX_ATTESTATION_RESULT Action: Sent to the MDM agent to inform the result of the attestation process.
int ERROR_DEVICE_NOT_SUPPORTED Device is not compatible for attestation.
int ERROR_INVALID_NONCE Invalid nonce provided.
int ERROR_MDM_PERMISSION Only MDM partner client with appropriate permission can invoke this API.
int ERROR_NONE The communication with the TrustZone and the Attestation server was successful.
int ERROR_TIMA_INTERNAL Error communicating with the trust zone.
int ERROR_UNKNOWN Unknown error during attestation process.
String EXTRA_ATTESTATION_DATA This is a byte array, containing the blob data upon completion of the Attestation process.
String EXTRA_ERROR_MSG This is a String extra.
String EXTRA_NETWORK_ERROR This is an int extra.
String EXTRA_RESULT This is an int extra to obtain possible error messages.
Public Constructors
AttestationPolicy(Context context)
Public Methods
void startAttestation(String nonce)

API to start attestation.

[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final String ACTION_KNOX_ATTESTATION_RESULT

Since: Knox API Level 7

Action: Sent to the MDM agent to inform the result of the attestation process. Receiver must hold "com.samsung.android.knox.permission.KNOX_REMOTE_ATTESTATION" to receive this intent The results of the attestation process are sent in this intent.

Since
API level 7
KNOX 1.0.1
Constant Value: "com.samsung.android.knox.intent.action.KNOX_ATTESTATION_RESULT"

public static final int ERROR_DEVICE_NOT_SUPPORTED

Since: Knox API Level 7

Device is not compatible for attestation. Possible value for EXTRA_RESULT. Use EXTRA_ERROR_MSG to get any error messages from the intent, might be null

Since
API level 7
KNOX 1.0.1
Constant Value: -3 (0xfffffffd)

public static final int ERROR_INVALID_NONCE

Since: Knox API Level 11

Invalid nonce provided. Possible value for EXTRA_RESULT. Nonce has to be exactly 32 bytes length HEX string.

Since
API level 11
KNOX 2.0
Constant Value: -5 (0xfffffffb)

public static final int ERROR_MDM_PERMISSION

Since: Knox API Level 7

Only MDM partner client with appropriate permission can invoke this API. Possible value for EXTRA_RESULT.

Since
API level 7
KNOX 1.0.1
Constant Value: -1 (0xffffffff)

public static final int ERROR_NONE

Since: Knox API Level 7

The communication with the TrustZone and the Attestation server was successful. The attestation results are available to be checked by the MDM server, either from the blob sent from the Attestation agent or by directly requesting the results from the Attestation server. Possible value for EXTRA_RESULT. Use EXTRA_ATTESTATION_DATA to get the blob provided by the TIMA service from the intent

Since
API level 7
KNOX 1.0.1
Constant Value: 0 (0x00000000)

public static final int ERROR_TIMA_INTERNAL

Since: Knox API Level 7

Error communicating with the trust zone. Possible value for EXTRA_RESULT. Caller needs to retry when issue is resolved.

Since
API level 7
KNOX 1.0.1
Constant Value: -2 (0xfffffffe)

public static final int ERROR_UNKNOWN

Since: Knox API Level 7

Unknown error during attestation process. Possible value for EXTRA_RESULT. Use EXTRA_ERROR_MSG to get any error messages from the intent, might be null

Since
API level 7
KNOX 1.0.1
Constant Value: -4 (0xfffffffc)

public static final String EXTRA_ATTESTATION_DATA

Since: Knox API Level 7

This is a byte array, containing the blob data upon completion of the Attestation process. Obtained via Intent.getByteArrayExtra()

Since
API level 7
KNOX 1.0.1
Constant Value: "com.samsung.android.knox.intent.extra.ATTESTATION_DATA"

public static final String EXTRA_ERROR_MSG

Since: Knox API Level 7

This is a String extra. Obtained via Intent.getStringExtra(). This can be obtained when EXTRA_RESULT is ERROR_UNKNOWN. Could be null

Since
API level 7
KNOX 1.0.1
Constant Value: "com.samsung.android.knox.intent.extra.ERROR_MSG"

public static final String EXTRA_NETWORK_ERROR

Since: Knox API Level 7

This is an int extra. Obtained via Intent.getIntExtra(). This can be obtained when EXTRA_RESULT is ERROR_NETWORK_FAILURE, to get the underlying network/protocol specific error code.

Since
API level 7
KNOX 1.0.1
Constant Value: "com.samsung.android.knox.intent.extra.NETWORK_ERROR"

public static final String EXTRA_RESULT

Since: Knox API Level 7

This is an int extra to obtain possible error messages. Obtained via Intent.getIntExtra().

Since
API level 7
KNOX 1.0.1
Constant Value: "com.samsung.android.knox.intent.extra.RESULT"

Public Constructors

public AttestationPolicy (Context context)

Since: Knox API Level 7

Since
API level 7
KNOX 1.0.1

Public Methods

public void startAttestation (String nonce)

Since: Knox API Level 7

API to start attestation.

Parameters
nonce
Nonce string provided by MDM client. Nonce has to be exactly 32 bytes length HEX string. Sample: 3859CBB9AAE91D8CFAF1FFAFED9B2AA04D860AACE9B1B4BAC5ED4FD6369C2C87
Throws
SecurityException If caller does not have required permissions
Usage
An administrator can use this API to start the attestation process. This API is used when there is a attestation server, This call starts the prcoess of requesting the nonce from the attestation server, which is then used for obtaining the blob from the TrustZone. The blob data obtained from the TrustZone is sent back to the MDM partner client. The blob data is sent via intents ACTION_KNOX_ATTESTATION_RESULT back to the MDM client and has to have "com.samsung.android.knox.permission.KNOX_REMOTE_ATTESTATION" permission to receive that intent.


 AttestationPolicy attestation = new AttestationPolicy(context);

 try

 {

     String nonce;

     attestation.startAttestation(nonce);

 }

 catch (SecurityException e)

 {

     Log.w(TAG, "SecurityException: " + e);

 }

 

Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_REMOTE_ATTESTATION" permission with a protection level of signature.
Since
API level 7
Knox 1.0.1