Link Search Menu Expand Document
tsrct documentation

DDX Request-Response Verification Flow

This document details the real-time, three-party cryptographic handshake used to verify that a Domain Delegated Extension (DDX) credential is still active and valid.

Unlike static credentials, a DDX card represents a dynamic, revocable relationship (e.g., Active Employee, Active Student, Active Member). To prove validity in real-time, the credential must undergo a Challenge-Response Handshake countersigned by the issuing organization’s live DDX server.

1. The Verification Handshake Sequence

The validation process involves three main actors:

  1. The Prover (User/Holder): Presenting their credential (wallet card QR code).
  2. The Verifier (Scanning Entity): Challenging and scanning the credential.
  3. The DDX Server (Issuer): The organization’s live server verifying the relationship.
+------------+               +--------------+               +---------------+
|   Prover   |               |   Verifier   |               |  DDX Server   |
|   (User)   |               |  (Scanner)   |               |   (Issuer)    |
+-----+------+               +------+-------+               +-------+-------+
      |                             |                               |
      |  1. Scan Wallet Card QR     |                               |
      +---------------------------->+                               |
      |                             |                               |
      |  2. Dispatch Cryptographic  |                               |
      |     Challenge               |                               |
      +<----------------------------+                               |
      |                                                             |
      |  3. Local sign challenge                                    |
      |     (Create req object)                                     |
      |                                                             |
      |  4. POST challenge payload to DDX URL                       |
      +------------------------------------------------------------>+
      |                                                             |
      |                               5. Verify signature & state   |
      |                                  (Create res object)        |
      |                                                             |
      |  6. Return countersigned response (res)                     |
      +<------------------------------------------------------------+
      |                                                             |
      |  7. Embed req & res into T-Doc header                       |
      |  8. Deliver completed verified T-Doc envelope               |
      +---------------------------->+                               |
                                    |                               |
                                    |  9. Locally verify both       |
                                    |     signatures in browser!    |
                                    v                               |

2. Cryptographic Schema of the ddx Header Block

Upon successful completion of the handshake, the completed req (Request) and res (Response) blocks are serialized and embedded as objects inside the T-Doc’s header ddx metadata array:

"ddx": [
  {
    "uid": "2222222222222222222222222.9000990009900099000990009.20240201204933-ddx-name-saurabh-gupta",
    "req": {
      "sig": "CVySUnrjFOPT35QVzSrsj...",
      "sha": "GfmVpx7ZTU8ALI43O_UfC7LfeuqREad_FghgbItxCAA",
      "src": "9000990009900099000990009",
      "key": "9000990009900099000990009.20240228180712",
      "nce": 1716237996,
      "val": "sig=C_9b394n_FwDJq7iYfFBbyxpEEud...&sha=1Tx5B86Kwm533at61...&src=9000990009900099000990009&nce=1716237996"
    },
    "res": {
      "val": "sig=C_9b394n_FwDJq7iYfFBbyxpEEud...&sha=1Tx5B86Kwm533at61...&src=9000990009900099000990009&nce=1716237996&its=2024-05-20T20:46:37Z",
      "sig": "RD6IL-Rjcnv4Mc231qvzr-zONvhMa...",
      "sha": "FEtg2rZ6JvODcC1vqAGFLUNfw5_2QYMuPriOT0n5UAM",
      "its": "2024-05-20T20:46:37Z",
      "bld": "1.0.0"
    }
  }
]

A. The Request (req) Block Fields

The req block represents the user proving their possession of their private key by signing the current document state and nonce:

  • src: The Prover’s (User’s) 25-digit UID.
  • key: The public key ID (uid.kid format) used by the Prover to sign.
  • nce: Nonce epoch timestamp (seconds), ensuring challenge freshness.
  • val: The query-string-formatted parameter payload submitted to the DDX server: 
    sig={body_sig}&sha={body_sha}&src={user_uid}&nce={nonce}
  • sig: The Prover’s RS256 signature generated over the exact UTF-8 bytes of the val string.
  • sha: SHA-256 hash computed over the val string.

B. The Response (res) Block Fields

The res block represents the organization’s DDX server verifying and countersigning the user’s challenge:

  • val: The extended query-string parameter payload returned by the DDX server. It mathematically appends the server’s issue timestamp (its) to the original req.val string, locking them together: 
    sig={body_sig}&sha={body_sha}&src={user_uid}&nce={nonce}&its={its_timestamp}
  • sig: The DDX Server’s RS256 signature generated over the exact UTF-8 bytes of the extended res.val string.
  • sha: SHA-256 hash computed over the extended res.val string.
  • its: The DDX Server’s issue timestamp in ISO-8601 UTC format.
  • bld: The DDX Server’s active software build version (e.g. "1.0.0").

3. Real-Time Verification Mechanism

When the scanning entity receives the completed T-Doc, their browser-native SubtleCrypto client performs the following verification checks:

  1. User Signature Check: Decodes req.val and verifies that the user’s signature (req.sig) is valid against the public key declared in req.key. This proves the holder indeed owns the credential.
  2. DDX Countersignature Check: Decodes res.val and verifies that the DDX Server’s signature (res.sig) is valid against the organization’s registered DDX public key. This proves the issuing authority endorsed this validation.
  3. Active Status Check: If the organization revokes the credential, the DDX server will refuse to sign any incoming challenges for that target UID, causing the handshake to fail instantly.

4. Critical Performance & Timing Constraints

Because the verification depends on comparing epoch offsets between nce (nonce generation) and its (countersignature issue time), timing synchronization is critical.

The Clock-Drift Window

  • To prevent replay attacks, the API ledger enforces a strict +/- 10-second window on the timestamps.
  • Any significant clock drift on either the user’s mobile device or the organization’s DDX server instance will trigger a validation failure.

Serverless Cold-Starts Warning

Many organizations deploy their DDX Server on serverless infrastructure such as GCP Cloud Run or AWS Lambda:

  • If the DDX Server has scaled down to 0 instances due to inactivity, the first incoming validation request will trigger a Cold-Start.
  • A Cloud Run container initialization sequence can take anywhere from 2 to 8 seconds.
  • If the validation response delay exceeds the timeout thresholds or causes its to fall out of range of nce, the transaction will be rejected as expired.
  • Production Remedy: It is highly recommended to configure the DDX Service on Cloud Run with a minimum instance count of min-instances = 1 to keep the container continuously warm and responsive.