VERIFY (User Verification)

The VERIFY operation is designed to authenticate an already-registered user by comparing a live biometric sample against the reference homomorphically encrypted token stored during registration. This process is entirely privacy-preserving; raw biometric data is processed on-device and purged immediately after generating a cryptographic token.

Operation Overview

In the VERIFY operation, the following steps are performed:

1. Live Biometric Capture & Preprocessing:
   • The client device captures a current facial biometric image.
   • Local algorithms (e.g., face detection, alignment, normalization) extract and preprocess the facial region.
2. Homomorphic Token Generation:

   • The preprocessed biometric data is transformed into a homomorphically encrypted token using advanced schemes (such as BFV or CKKS).

   • This token is designed for secure arithmetic operations on ciphertexts, enabling similarity measurements without decryption.

3. Reference Token Retrieval & Comparison:

   • The reference token is retrieved based on the user’s UUID, either from secure local storage or through a server lookup if necessary.

   • A cryptographic comparison is executed locally to measure similarity. In cases where the token is not available locally, the encrypted reference token is securely fetched from the server.

4. Data Purging & Optional Selfie Capture:

   • As with other operations, raw biometric data is immediately purged post-token generation.

   • Optionally, an accompanying selfie or audit image may be sent via webhook for anti-fraud or forensic purposes.

5. Enhanced Session Metadata:
   • Additional metadata such as sessionExpiry, deviceInfo, and a cryptographic nonce (challenge) are incorporated to bind the verification session to specific context and to mitigate replay attacks.

Endpoint

  POST /v2/verification-session

Expanded Request Body

The VERIFY request includes not only the core parameters but also additional fields for session control, detailed device metadata, and cryptographic nonce validation:

{
  "type": "VERIFY",
  "uuid": "123e4567-e89b-12d3-a456-426614174000", // Registered user's UUID.
  "redirectURL": "https://your-app.com/callback",
  "callback": {
    "url": "https://your-api.com/webhook",
    "headers": {
      "authorization": "Bearer YOUR_TOKEN"
    }
  },
  "locale": "en-US",
  "enableDesktop": false, // Desktop verification disabled for enhanced security.
  "sendImages": false, // Do not include images in webhook by default.
  "verifyDeleteUser": false, // Optionally delete user data post-verification.
  "sessionExpiry": 1800, // Verification session expiry in seconds.
  "transactionID": "txn-verify-112233", // Unique identifier for tracking the transaction.
  "deviceInfo": {
    // Optional metadata about the client device.
    "os": "iOS 16",
    "model": "iPhone 14",
    "resolution": "2778x1284"
  },
  "challenge": "unique-nonce-string", // Cryptographic nonce for preventing replay attacks.
  "additionalAuditData": {
    // Supplementary audit data.
    "ambientLight": "350 lux",
    "captureTime": "2025-03-19T12:34:56Z"
  },
  "debugMode": false, // Disable verbose logging in production.
  "requirements": [
    // Enables usage of different scenarios. With Face or Face and Passkey
    "face",
    "passkey"
  ]
}

Parameter Details

Success Response

A successful sign-in returns a JSON payload including a unique session identifier and a launch URL for the biometric process:

{
  "launchUrl": "https://verify.privateid.com/start?sessionId=2fbbb4a3-1392-43c4-8d12-f61ff44e4efb",
  "sessionId": "2fbbb4a3-1392-43c4-8d12-f61ff44e4efb"
}

Webhook Response

The asynchronous webhook provides the outcome of the SIGN-IN operation.

{
  "message": "Success!",
  "status": "success",
  "sessionId": "dac57c75-0ed8-40fa-b40e-f0620dbb9444",
  "identificationResult": {
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "guid": "ljkn23ln-23rl-n23r-l23rl23rl23rln2bk",
    "confidence": 0.97,
    "status": "success",
    "challengeResponse": "signed-challenge-response"
  }
}

Failure Response

{
  "status": "error",
  "message": "Verification failed due to token mismatch or replay attack.",
  "errorCodes": [-12],
  "retryAfter": 10
}

Cryptographic Considerations for VERIFY

• Homomorphic Encryption Integrity:
  

  The verification process leverages the same homomorphic encryption scheme as registration, ensuring that biometric tokens are compared securely without exposing the underlying data

• Challenge-Response Validation:
  

  The inclusion of a cryptographic nonce (challenge) in the token generation process ensures that each verification session is unique. The signed challenge response binds the session to the current verification attempt, preventing replay attacks.

• Data Purging:
  

  Immediate purging of raw biometric data following token generation minimizes the risk of data leakage. This is critical in preserving the integrity of the verification process.

• Audit and Forensics:
  

  The additionalAuditData field provides contextual information (e.g., ambient light conditions, capture timestamp) to support forensic analysis and ensure compliance with regulatory standards.

• Token Comparison Protocol:
  

  The system performs a secure, on-device comparison of the newly generated token with the reference token. In cases where the reference token is not available locally, a secure server retrieval mechanism is invoked. The comparison is performed using cryptographic similarity measures that operate directly on the ciphertexts.