This document explains how to use the Samsung Knox Attestation REST APIs. Knox Attestation lets you verify that a Samsung Android device has not been rooted or running unofficial firmware that can compromise the data integrity.

http://attest-api.secb2b.com

Here is an overview of how you use these services:

1. Your web server requests a nonce from Samsung's Attestation Server.

2. Your web server passes the nonce to your Android app, which starts an attestation check on a device. This is to see if the device is running authorized firmware. Your Android app sends back a blob (Binary Large OBject) containing the attestation results.

3. Your web server requests an attestation verdict from Samsung's Attestation Server, based on the generated blob. The verdict indicates if the device passed or failed the attestation check.
   For details, see the Knox Attestation Developer Guide.

To communicate with the Attestation Server, you must use the following:

• HTTPS – This provide secure delivery of the nonces, blobs, and attestation verdicts. For coding examples showing how to use HTTPS, see the Attestation Developer Guide
• SSL certificate – You need this to encrypt data over the HTTPS connection. Make sure that the certificate is:
  • from a trusted provider. Do not use self-signed certificates, which cannot be trusted.
  • contains the complete certificate chain. For help, please consult with your web provider.

The Knox Attestation API uses the conventional HTTP response code to indicate the success or failure of a request. A 2XX response code indicates success, a 4XX response code indicates an error given the inputs of the request, and a 5XX response code indicates a failure with the Knox Attestation platform.

In addition, errors will contain a JSON response body with more information about the error:

HTTP/1.1 200 OK Content-Type: application/json

{
    "result" : "SUCCESS",
    "objectId" : "SDAKJ23DKCMSDAKENXSSAEQ",
    "requestedId": "111000291332456"
}

Async result : POST /api/v1/transaction

HTTP/1.1 200 OK Content-Type: application/json

{
    "count" : 3,
    "success": 2,
    "fail": 1,
    "resultList": [
        {
            "result": "FAIL",
            "requestedId": "123456789012347"
            "error" : {
                "code" : "4000000",
                "message" : "RESOURCE_INVALID_PARAM",
                "reason" : "RESOURCE_INVALID_PARAM"
            }
        }
    ]
}

HTTP/1.1 401 Unauthorized Content-Type: application/json

{
    "result" : "FAIL",
    "error" :
       {
          "code": 4010000,
          "message": "AUTHORIZATION_FAIL",
          "reason": "Invalid Api Key"
       }
}

The error response attributes are.

The error objects contain the following attributes.

The following table lists the most common HTTP error responses.