Device Management Use Cases

The basic idea of attestation is that it is trustworthy evidence or proof about something. In the case of a cybersecurity system, for example, it means that a relying party like a bank or an Fintech can be confident about what it is that they are receiving from a device. Digging deeper into that, what we really mean by attestation is that we have a Secure Environment – a Root of Trust – that is providing cryptographically signed evidence about the state of the device. For example, is it securely booted, is debug enabled, is there any evidence of tampering? This enables the relying party, because it is cryptographically signed, to verify that it is a particular device from a particular manufacturer, and that it has not been tampered with before it is connected to. Now to achieve this eclipse has expose following APIs with help of google play integrity APIs.

Require config

package name.decryption.key=XXXXX
package name.verification.key=XXXXX

Example:

com.ukheshe.eclipse.payment.service.decryption.key=XXXXX
com.ukheshe.eclipse.payment.service.verification.key=XXXXX
Need to obtain these decryption and verification keys from google projects

Nonce Generation and Verification:

Below two APIs can be used for generating and verifying the nonce

Generate a Nonce

GET: /eclipse-conductor/rest/v1/global/attestations/{deviceId}

Example Response Body:

{
  "nonce": "MDk4MTI2MGE0MzRiMjE1MTVkOWI3MzJmNzZjNjEzYTgzZGNjMGFiM2NlNGZkOGI3MzgzOGNmZGJmZDNlYzA4ZA=="
}

Verify a Nonce

POST /eclipse-conductor/rest/v1/global/attestations/{deviceId}

Request Payload:

{
  "integrityVerdict": "MDk4MTI2MGE0MzRiMjE1MTVkOWI3MzJmNzZjNjEzYTgzZGNjMGFiM2NlNGZkOGI3MzgzOGNmZGJmZDNlYzA4ZA",
    "packageName": "com.ukheshe.eclipse.payment.service"
}

Response Value:

{
  "info": "Decrypted payload or errorDescription as JSON string",
  "isVerified": true
}

Examples

Example response if decryption is successful and decrypted nonce matches the actual nonce:

{
  "isVerified": true,
  "info": "{\"requestDetails\":{\"requestPackageName\":\"com.ukheshe.eclipse.payment.service\",\"timestampMillis\":\"1661841706123\",\"nonce\":\"asdlkfjaseroitueoritueoirtueros=\"},\"appIntegrity\":{\"appRecognitionVerdict\":\"UNRECOGNIZED_VERSION\",\"packageName\":\"com.ukheshe.eclipse.payment.service\",\"certificateSha256Digest\":[\"2ihgOPNFiCGvHLTIiw6A-JSoK-xAj4YJkP-EDIPcViI\"],\"versionCode\":\"1\"},\"deviceIntegrity\":{\"deviceRecognitionVerdict\":[\"MEETS_DEVICE_INTEGRITY\"]},\"accountDetails\":{\"appLicensingVerdict\":\"LICENSED\"}}"
}

Example response if decryption is successful and decrypted nonce does not match the actual nonce:

{
  "isVerified": false,
  "info": "{\"errorDescription\":\"There is error in decrypting verdict. Please provide valid play integrity verdict with valid package name.\"}"
}

Example error:

{
  "errorDescription": "There is error in decrypting verdict. Please provide valid play integrity verdict with valid package name."
}

📘

Note:

• If no nonce has been generated for the device id it will throw an exception with the description: "No nonce found for deviceID: XXXXX. Please create nonce first."
• The generated nonce can be used for only one successful/unsuccessful nonce verification request (POST API)