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
Section titled “1. The Verification Handshake Sequence”The validation process involves three main actors:
- The Prover (User/Holder): Presenting their credential (wallet card QR code).
- The Verifier (Scanning Entity): Challenging and scanning the credential.
- 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
Section titled “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
Section titled “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.kidformat) 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 thevalstring.sha: SHA-256 hash computed over thevalstring.
B. The Response (res) Block Fields
Section titled “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 originalreq.valstring, 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 extendedres.valstring.sha: SHA-256 hash computed over the extendedres.valstring.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
Section titled “3. Real-Time Verification Mechanism”When the scanning entity receives the completed T-Doc, their browser-native SubtleCrypto client performs the following verification checks:
- User Signature Check: Decodes
req.valand verifies that the user’s signature (req.sig) is valid against the public key declared inreq.key. This proves the holder indeed owns the credential. - DDX Countersignature Check: Decodes
res.valand 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. - 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
Section titled “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
Section titled “The Clock-Drift Window”- To prevent replay attacks, the API ledger enforces a strict
+/- 10-secondwindow 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
Section titled “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 instancesdue 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
itsto fall out of range ofnce, 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 = 1to keep the container continuously warm and responsive.