Server-Side Integration

This section explains how the encrypted security report sent from the Sentinel Attest client library is received, decrypted, and validated on the server side, step by step.

1. Nonce Generation Endpoint

Before initiating the attestation process on the client side, the client must request a short-lived cryptographically secure token (Nonce) from the server to prevent replay attacks.

GET /api/v1/attestation/nonce

• Purpose: Generates a single-use, unpredictable value and stores it temporarily on the backend.

2. Data Models

The raw data structure sent by the client to your server and the decrypted object models are defined below.

2.1. Encrypted Request Model (Incoming Server Payload)

The client encrypts the prepared package using hybrid encryption - both asymmetric (RSA) and symmetric (AES) - and sends it to your server's /api/v1/attestation/verify endpoint via a POST request.

@Serializable
data class EncryptedAttestation(
    val encryptedKey: String,  // Base64-encoded one-time AES key, encrypted with the server's RSA Public Key
    val encryptedData: String, // Base64-encoded core payload data, encrypted with the AES key
    val iv: String             // Base64-encoded Initialization Vector (IV) used in the AES encryption
)

2.2. Decrypted Data Model (Payload)

Once the EncryptedAttestation is successfully decrypted, this is the main object model you will obtain to execute your core validation logic:

@Serializable
data class AttestationPayload(
    val nonce: String,                      // A unique, single-use token generated by the server
    val attestationToken: String,           // The attestation token from Play Integrity (Android) or App Attest (iOS)
    val securityReport: SecurityReportDto   // Sentinel device security analysis report
    val platform: String,                   // operating system indicator: "android" or "iOS"
    val timestamp: Long                     // The epoch timestamp (ms) when the request was created on the client side
)

2.3. Sentinel Security Report Details (SecurityReport)

This report contains the real-time security status of the device, root/jailbreak detection flags, and specific threats detected:

@Serializable
data class SecurityReport(
    val severity: Int,              // Total risk weight score (e.g., 90, 120, 330)
    val riskLevel: String,          // Categorized risk level (e.g., "SAFE", "LOW", "MEDIUM", "HIGH")
    val isCompromised: Boolean,     // Indicates if the device is rooted/jailbroken or if system integrity is breached
    val isTampered: Boolean,        // Indicates if the application package or its signature has been modified
    val isHooked: Boolean,          // Indicates active runtime manipulation (e.g., Frida, Xposed)
    val isVirtualDevice: Boolean,   // Indicates if the app is running on an emulator or simulator
    val isDebugged: Boolean,        // Indicates if a debugger is attached to the application
    val isMockLocation: Boolean,    // Indicates if mock or spoofed location providers are active
    val threats: List<String>,      // A list of class names representing the specific violations detected
    val timestamp: Long             // The generation timestamp of the report
)

3. Server-Side Processing Pipeline

When the server receives an attestation request (e.g., POST /api/v1/attestation/verify), it must execute the following operations in sequence:

Step 1: Hybrid Decryption

1. Decrypt the AES Key (RSA): Decrypt the incoming EncryptedAttestation.encryptedKey using your server's securely stored RSA Private Key to retrieve the raw symmetric AES key.

2. Decrypt the Payload (AES): Decrypt the EncryptedAttestation.encryptedData using the extracted AES key along with the provided EncryptedAttestation.iv.

3. Deserialization: Convert the resulting decrypted plaintext string (which is in JSON format) into the AttestationPayload object.

Tip for Testing & Debugging: While implementing and testing your server-side validation, you can use the following trusted online tools to manually decode, decrypt, and inspect your payloads:

• RSA Key Generator

• RSA Encryption

• RSA Decryption

• AES Encryption

• AES Decryption

• CBOR Playground

Step 2: Nonce and Expiration Validation (Replay Attack Protection)

1. Nonce Verification: Look up the payload.nonce in your database or cache layer (e.g., Redis).

   • If the nonce does not exist or has already been marked as used, reject the request immediately.

   • If the nonce is valid, delete it from your system immediately to prevent any subsequent reuse.

2. Timestamp Expiration Check: Compare the server's current time with payload.timestamp. Reject any requests that exceed your configured threshold (e.g., older than 5 minutes) to protect against time-lagged replay attacks.

Step 3: Attest Provider Platform Verification

Execute secondary platform-specific validation based on the payload.platform flag:

• android: Forward the payload.attestationToken to the official Google Play Integrity API servers for remote validation. Verify that the packageName returned by Google matches your application's unique identifier.

• iOS: Validate the payload.attestationToken on your backend according to Apple's native App Attest Validation guidelines.

Step 4: Sentinel Security Policy Evaluation

Enforce your specific business rules based on the telemetry inside payload.securityReport. You can implement flexible mitigation policies:

• Strict Policy (Full Block): If isCompromised, isTampered, or isHooked is true, or if the riskLevel is evaluated as "HIGH", return an error response to the client and block the user from proceeding with critical transactions (e.g., money transfers, login attempts).

• Monitoring / Restricted Mode: If lighter flags like isVirtualDevice or isDebugged are triggered, you may choose to log the event or flag the user profile for review rather than terminating the session entirely.

Once all layers of validation (Decryption, Nonce lifecycle, Apple/Google ecosystem verification, and the Sentinel report) pass successfully, return a successful response (HTTP 200 OK) to the client.

Backend Developer Note: The threats list contains specific technical categories of the violations caught on the client side (e.g., Root, Tamper, Hook). We highly recommend passing this array directly into your logging or SIEM infrastructure to analyze real-time attack trends from your backend dashboard.