🏗️Integration Guidelines

For successful integration into the DVR application workflow, each client stakeholder is advised to follow the guidelines specified in this documentation.

DVR Block Diagram

The call flow involving all stakeholders within the DVR application is depicted in the accompanying diagram below.

Call Sequence Diagram

The call sequence diagram for the interaction is provided here.

zkPass Call Sequence Diagram

Detailed Explanations

The comprehensive workflow for zkPass is elaborated in the following sections, where each step is explained in detail.

1. Step 1:

   • Call get_dvr_token (Part A) To initiate the process, the Data Holder invokes the get_dvr_token API method provided by the Verifier. This call necessitates authentication to enable the Proof Verifier to securely ascertain the identity of the requesting user.

     Note: The API signature and payload format for get_dvr_token are determined by the specific implementation of the Proof Verifier. zkPass does not impose any particular specifications or structure.

   • Return the DVR token (Part B) Upon receiving the request, the Verifier constructs the DVR, tailoring the query according to requirements specific to the user's core data. For a concrete example of a DVR query, please refer to this example.

     The Verifier ensures the uniqueness of the DVR by generating a distinct DVR ID each time a new DVR is created. After the DVR is assembled, the Verifier signs and encapsulates it in a JSON Web Signature (JWS) token to affirm its integrity and authenticity.

2. Step 2:

   • Call get_user_data_token (Part A) Once the DVR token is obtained, the Data Holder moves on to gather the user data specified by the DVR requirements. This is achieved by invoking the get_user_data_token API method offered by the Data Issuer. Like the earlier call to the Verifier, this request also mandates authentication.

     Caching Consideration: If the requisite user data is already cached by the Data Holder and is still valid (not expired), this API call can be skipped. In such cases, proceed directly to Step 3.

     Note: The API signature and payload structure for get_user_data_token are specific to the Data Issuer's implementation. zkPass does not prescribe any particular format or details.

   • Return the User Data token (Part B) Upon validating the request, the Data Issuer locates the corresponding user data. It then signs and serializes this data into a JSON Web Signature (JWS) token to confirm its authenticity. Finally, the JWS token encapsulating the user data is returned to the requesting Data Holder.

3. Step 3:

   1. Call generate_zkpass_proof (Part A) Upon securing both the DVR token and the user data token, the Data Holder invokes the generate_zkpass_proof method from the zkclient-lib. This method takes both tokens as input parameters, encryptes both tokens into JWE tokens, and serves as a wrapper for a RESTful API call to the zkPass Service. The core objective of this invocation is to execute the query defined in the DVR against the supplied user data, subsequently generating both the Zero-Knowledge Proof and the query output.

   2. Return the ZkPass Proof token (Part B) The zkPass Service handles the generate_zkpass_proof request by validating the signatures on both input tokens and decrypting them. The query is then executed within a secure, isolated environment—specifically, the zkPass Query Host process running inside a Trusted Execution Environment (TEE).

      Upon successful execution, the zkPass Service constructs a zkPass Proof object. This object encapsulates the query output and is signed into a JWS token for authenticity. The zkPass Proof token is then returned to the calling Data Holder.

      zkPass Proof Components: The zkPass Proof object comprises the cryptographic Zero-Knowledge Proof, the output of the executed query, and associated metadata about the proof itself.

4. Step 4:

   1. Call verify_zkpass_proof (Part A) At this point, the Data Holder possesses the zkPass Proof token. It then proceeds to call the Verifier's verify_zkpass_proof method, supplying the proof token as the sole input parameter.

      Note: The API signature and payload schema for the Verifier's verify_zkpass_proof method are implementation-specific. zkPass does not impose any standardized format or details.

   2. Verify the ZkPass Proof (Part B) Upon receipt of the request, the Verifier scrutinizes the signature attached to the proof token. Subsequently, it invokes the verify_zkpass_proof function available in the zkpass-client library. This function performs the ZKP verification on the cryptographic seal produced by the ZKVM running in the zkPass Query Host process. It also extracts the query output from the seal.

   3. Return the query result (Part C) After successfully validating the zkPass Proof and extracting the query output, the Verifier relays the query result back to the Data Holder. This final step completes the zkPass workflow.