đī¸Integration Guidelines
For successful integration into the DVR application workflow, each client stakeholder is advised to follow the guidelines specified in this documentation.
Last updated
zkPass
zkPass Developer's Guide
For successful integration into the DVR application workflow, each client stakeholder is advised to follow the guidelines specified in this documentation.
Last updated
The call flow involving all stakeholders within the DVR application is depicted in the accompanying diagram below.
The call sequence diagram for the interaction is provided here.
The comprehensive workflow for zkPass is elaborated in the following sections, where each step is explained in detail.
(Step 1) The Data Holder initiates the process by requesting the Data Verifier to generate a DVR token. This request requires authentication, allowing the Proof Verifier to securely verify the identity of the requesting user.
Note: The API signature and payload format are determined by the specific implementation of the Proof Verifier. zkPass does not enforce any specific standards or structure.
(Step 2) Upon receiving the request, the Verifier creates the DVR, tailoring the query to the requirements of the user's core data. For an example of a DVR query, refer to [this example].
To ensure uniqueness, the Verifier generates a distinct DVR ID each time a new DVR is created. Once the DVR is constructed, it is signed and encapsulated as a JSON Web Signature (JWS) token to ensure its integrity and authenticity.
(Step 3) The Data Holder then receives the DVR token from the Data Verifier.
(Step 4) With the DVR token, the Data Holder proceeds to collect user data based on the DVR's requirements. Like the previous call to the Verifier, this request also requires authentication.
Caching Consideration: If the required user data is already cached and valid (not expired), this API call can be skipped. In such cases, proceed directly to Step 3.
Note: The API signature and payload structure are specific to the Data Issuer's implementation. zkPass does not prescribe any particular format or details.
(Step 5) Upon validating the request, the Data Issuer retrieves the corresponding user data. It then signs and serializes this data into a JSON Web Signature (JWS) token to confirm its authenticity. Finally, the token is returned to the requesting Data Holder.
(Step 6) The Data Holder receives the user data token from the Data Issuer.
(Step 7) With both the DVR token and the user data token in hand, the Data Holder initiates the proof generation process. This step involves:
Encrypting both tokens into JSON Web Encryption (JWE) tokens.
Wrapping the tokens into a RESTful API call to the zkPass Service.
The primary goal of this step is to execute the query defined in the DVR against the user data, generating both a Zero-Knowledge Proof (ZKP) and the query output.
The zkPass Service processes the proof generation request by:
Validating the signatures on both tokens.
Decrypting the tokens.
Executing the query in a secure, isolated environmentâspecifically, the zkPass Query Host running within a Trusted Execution Environment (TEE).
(Step 8) Upon successful execution, the zkPass Service constructs a zkPass Proof object, which encapsulates the query output. This proof is signed as a JWS token to ensure its authenticity. The zkPass Proof token is then returned to the Data Holder.
zkPass Proof Components: The zkPass Proof object includes:
The cryptographic Zero-Knowledge Proof.
The query output.
Metadata about the proof.
(Step 9) The Data Holder receives the zkPass Proof token.
(Step 10) With the zkPass Proof token, the Data Holder requests the Data Verifier to verify the proof. The proof token is provided as the sole input parameter.
Note: The API signature and payload schema for the Verifier are implementation-specific. zkPass does not impose any standardized format or structure.
(Step 11) Upon receiving the request, the Verifier:
Validates the signature on the proof token.
Uses the verify_zkpass_proof function from the zkPass-client library to perform ZKP verification. This step involves validating the cryptographic seal generated by the ZKVM in the zkPass Query Host process and extracting the query output from the seal.
(Step 12) After successfully verifying the zkPass Proof and extracting the query output, the Verifier returns the query results to the Data Holder.
