Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Data Verification Request
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
The zkPass is a cloud-based infrastructure composed of three main components: zkPass Service, zkPass Modules, and zkPass Client Library.
The zkPass Service has 2 parts:
zkPass Web Service zkPass Web Service provides the REST API for the zkPass module clients. This endpoint accepts parameters that are defined by the zkPass module and forwards them to the ZkPass Host for the actual execution of the application. The web service operates in an untrusted environment. The clients of the zkPass module communicate with the web service via the zkPass Client Library.
zkPass Host zkPass Host operates within a Trusted Execution Environment (TEE), ensuring complete isolation and security from external threats. It interacts with the zkPass Web Service through a secure, specialized channel, receiving inputs for the zkPass module that are forwarded by the zkPass Web Service. The main function of the zkPass Host is to load the zkPass module executable module and execute it within the TEE. Additionally, the client of the zkPass module can perform end-to-end encryption with the zkPass Host to protect the privacy of user data being sent to the zkPass Service. This setup ensures that user data remains confidential and secure throughout the entire process.
The zkPass module is the heart of zkPass, creating higher-level abstractions and models that simplify integration and usage for third-party software. Its two main goals are:
Protecting the privacy of user data
Providing a verifiable computing environment
The zkPass module is implemented as a pluggable module, which is loaded by the zkPass Host and executed within a Trusted Execution Environment (TEE). While the data format for input and output is specific to each application, all input and output data must adhere to JWT encoding standards. This modular design ensures flexibility and security, allowing the zkPass module to operate seamlessly within the zkPass framework while maintaining the integrity and confidentiality of user data.
zkPass is designed to support multiple zkPass modules, with the current primary application being the Data Verification Request (DVR), detailed in the DVR section. DVR uses the powerful Zero Knowledge Virtual Machine as the underlying proof system. DVR ensures robust data protection and trust, making it indispensable for developers aiming to incorporate advanced privacy-preserving features into their software with an intuitive and easy-to-use interface and expressive JSON-based query language.
The zkPass-client is an SDK client library that provides interfaces, types, and functions for interacting with zkPass modules. Currently, the zkPass-client supports the DVR module.
The DVR client facilitates interaction with the DVR module and offers the following functionalities:
Issuing zkPass proofs
Verifying zkPass proofs
Generating tokens
Private Cloud Hosting, also known as the Virtual Private Cloud (VPC), for the zkPass service, is the go-to choice for organizations seeking a heightened level of control over their data and the execution of Zero-Knowledge Proofs (ZKPs). This hosting option offers a dedicated cloud environment, essentially providing a private digital space exclusively for your organization's use.
Enhanced Control You have the reins when it comes to managing your data. This control extends to how ZKPs are executed, giving you the ability to tailor processes to your specific requirements.
Customization Capabilities Every organization has unique needs, and private cloud hosting caters to this by offering the ability to customize your cloud environment to fit your specific operational parameters.
Data Control with Cloud Benefits While you enjoy comprehensive control over your data, you also benefit from the inherent advantages of cloud infrastructure, like scalability and operational efficiency. This means your hosting can grow and adapt to your organization.
In a private cloud setting, the zkPass service may operate differently compared to the public cloud. One key difference is that the zkPass service in a private cloud might not always run within a Trusted Execution Environment (TEE). This decision is often influenced by the specific security needs and infrastructure capabilities of your organization. Therefore, it's important to assess and implement additional security measures as needed to ensure that your data remains protected and your operations stay secure.
In conclusion, Private Cloud Hosting for zkPass is ideal for organizations that require a high degree of control and customization in their data management, alongside the flexibility and scalability of cloud infrastructure. This option is particularly suitable for those who have specific operational or security requirements that go beyond the scope of public cloud offerings.
For organizations with rigorous demands regarding data sovereignty and the security of their internal infrastructure, on-premise hosting of the zkPass Service is the ideal solution. This hosting model places the zkPass Service directly within your organization's data centers. By doing so, it ensures that your data remains entirely within your control and does not traverse external networks. This aspect is particularly crucial for organizations that handle highly sensitive information or are subject to stringent data protection regulations.
Unmatched Data Control With on-premise hosting, you have the highest level of control over your data. It stays within the confines of your organization, reducing external risks and exposures.
Enhanced Security Compliance This model is tailored for organizations that need to adhere to strict compliance and regulatory standards. Keeping the zkPass Service on-premise means you can align it more closely with your internal security protocols and compliance requirements.
Customized to Your Infrastructure On-premise hosting allows you to integrate the zkPass Service seamlessly with your existing IT infrastructure. This integration can be tailored to meet the specific needs and security standards of your organization.
Unlike cloud-based options, on-premise hosting of zkPass does not inherently require the service to run within a Trusted Execution Environment (TEE). This flexibility allows for a more customized security approach, where you can decide the best way to secure the service based on your infrastructure and security policies. However, it also means that ensuring the highest security standards rests largely on your organization’s ability to implement and maintain robust security measures within your own IT environment.
In summary, on-premise hosting of the zkPass Service is the premium choice for organizations that prioritize absolute control over their data and have the capability to manage high-level security requirements internally. This option provides a bespoke solution that aligns perfectly with stringent internal policies and regulatory needs, ensuring data remains secure and under your organization’s direct oversight.
Our Public Cloud Hosting option for the zkPass Service is like a communal digital space that's open and accessible to everyone. We take care of hosting the service, making it readily available for public use. This approach is perfect for those who want the benefits of cloud technology without the hassle of managing it themselves.
Choosing Public Cloud Hosting means you get the best of cloud computing, which includes:
Cost Efficiency Say goodbye to heavy investments in infrastructure. With public cloud hosting, you reduce your overhead costs as we handle the technical setup.
High Availability Our service is always up and running, ensuring you can access it whenever you need it.
Scalability As your organization grows or your needs change, scaling up or down is easy and flexible. This means the service adapts to your demand, not the other way around.
Effortless Management We keep the zkPass Service in top shape with regular updates and maintenance, all taken care of by our expert cloud service providers.
While the public cloud is all about accessibility, we haven't compromised on security. To ensure the highest level of protection, we run the zkPass Service within a Trusted Execution Environment (TEE). This means even in a shared cloud space, the zkPass operates in a secure, isolated environment, safeguarding all operations and data against external threats.
In summary, Public Cloud Hosting for zkPass is an ideal solution for those seeking a balance between accessibility, scalability, and cost-effectiveness, without compromising on the security and reliability of the service.
The zkPass SDK is the resource for integrating zkPass's robust privacy-protecting privacy applications into your client or service using Zero-Knowledge Proofs (ZKPs) functionalities provided by the zkPass Service. This SDK serves as an all-encompassing interface and library designed for third-party applications to use for accessing the zkPass Service framework.
The zkPass Software Development Kit is created with a set of core objectives in mind, ensuring that it not only meets but exceeds the expectations and needs of developers. Here's an overview of the key goals of the zkPass SDK:
Ease of Use The primary aim of the zkPass SDK is to provide an intuitive and user-friendly interface, ensuring minimal development coding and time for integration with the privacy-preserving apps running on the zkPass Service. This objective focuses on simplifying the process of incorporating privacy apps such as the DVR functionalities into applications, making it accessible even to those with limited experience in working with Zero-Knowledge Proofs.
High-Performance Performance is a critical aspect of the zkPass SDK. It is designed to handle complex proof computations efficiently, ensuring fast and reliable performance even under demanding conditions. This ensures that applications using zkPass can operate smoothly without performance bottlenecks.
Robust Security At its core, zkPass SDK is built with ZKP technologies. It prioritizes the protection of user data and the integrity of verification processes, implementing advanced cryptographic techniques to safeguard against potential vulnerabilities and threats.
Multi-Platform Support Understanding the diverse ecosystem of applications, the zkPass SDK is developed to be cross-platform compatible. Currently, it can be seamlessly integrated into three platform configurations: Node.js/Linux, ReactNative/Android, and Rust/Linux.
Innovation-Driven The zkPass SDK is at the forefront of technological innovation, especially in the realm of service-based proof systems. It continually evolves to include the latest advancements in the field of ZKP, providing developers with cutting-edge tools to build sophisticated and modern applications.
Comprehensive Documentation and Support To ensure developers can make the most of the SDK, comprehensive documentation and support for the privacy apps are provided. This includes detailed guides, API documentation, and responsive support channels to assist developers through any challenges they may encounter.
In summary, the zkPass SDK has been developed with a focus on usability, performance, security, and innovation, and it supports three different platforms. Currently, the primary application supported by the SDK is the DVR. The SDK's comprehensive approach to development objectives makes it a powerful tool for developers looking to integrate advanced data verification and privacy-preserving features into their applications.
You need an API key and a secret key to use the zkPass service. Register on the zkPass portal to obtain your API and secret keys.
Please keep your API Key and Secret Key safe—don't share them with anyone else
The DVR follows a robust trust model inspired by the W3C Decentralized Identifiers (DID) standards. Within the zkPass ecosystem, we define three client roles which participate in the zkPass ecosystem.
Depending on the application, the client of DVR can take one of these roles:
Data Issuer The entity responsible for issuing the original data that requires protection.
Data Holder (User) The individual whose confidential data is being protected.
Proof Verifier The service or application that sets the requirements or conditions on the user data. It verifies the zero-knowledge proof, which contains the result of the requirements.
This multi-faceted trust model allows the proper flow of data and communications among the DVR stakeholder clients and ensures that the user’s confidential information remains protected and secure.
This section demonstrates how to use the DVR module client SDK to:
Generate a DVR token.
Generate a User Data token.
Generate a zkPass proof.
Verify a zkPass proof.
This guide complements your understanding of our API endpoints by delving into key generation, signing, and encryption. These steps are crucial for securing your data tokens when using zkPass.
This pair consists of two keys: a public key and a private key. Think of them like a lock and key combination.
Public Key: This key is freely shared and used to verify the authenticity of your signed data tokens.
Private Key: Keep this key safe! It's used for signing and decrypting your data tokens.
Signing your data tokens adds a digital signature using your private key. This signature acts like a tamper-proof seal, ensuring anyone receiving the token can confirm it hasn't been altered.
Encryption takes your data tokens and scrambles them using your private key. This makes the data unreadable by anyone who doesn't possess the corresponding public key (which you wouldn't share).
This section provides a detailed reference for all zkPass API endpoints
Zero Knowledge Proof
ZKP, or Zero-Knowledge Proof, is a cryptographic method that allows one party to prove to another that a statement is true without revealing any specific information about the statement itself. In the context of verifiable computing, ZKP can be utilized to verify that computations were executed correctly on a binary app without actually having to re-execute or inspect the computation in detail. This means that even if a malevolent actor attempts to hack or tamper with the binary app's execution, they cannot falsify the ZKP. This is because the proof generated is mathematically bound to the correctness of the computation; any deviation from the correct execution would result in a proof that fails to verify. Therefore, using ZKP ensures that the computational results can be trusted without compromising privacy or revealing underlying data.
Imagine you have a magic box that can solve puzzles. You give a friend a puzzle to put inside the box. The box then spits out a "solved" ticket if it successfully solves the puzzle. Zero-Knowledge Proof (ZKP) is like this magic box. It can prove that a computer program did its job correctly without revealing what the job was or how it was done. So, even if someone tries to trick the magic box, they can't fake the "solved" ticket. In this way, you can trust the box's answer without knowing all its secrets.
This section explains how to use the zkPass service using any programming language that we don't currently support.
The following are the supported basic data types by the DVR Query language:
Integer A signed 64-bit integer data type. Example: 10, -12
String A sequence of characters. Example: "Hello, world!"
Boolean A binary value that can be either true or false
The list of supported operators:
Boolean Operators:
or
and
Relational Operators: >, >=, <, <=
Applies to integer
Equality Operators
Equality operator: == Applies to boolean, integer, and string. In the case of a string, this is a case-sensitive comparison.
Inequality operator: != Applies to boolean, integer, string
String-specific Relational Operations
~!= Case-insensitive inequality operation on a string
~== Case-insensitive equality operation on string
The zkPass Query language also defines the following concepts:
Variable The variable corresponds to the key name of the key/value json element in the query data. To reference nested elements in the json data, delimiter “.” is used as the path separator. The variable must appear on the left-hand side of a relational expression.
Literal (Constant) The constant value is compared to the variable's value. The literal must appear on the right-hand side of a relational expression. The data type of the literal must match that of the variable.
To address the limitations of the client-based proof system architecture, we introduce zkPass, a service-based proof system operating as a Proof-as-a-Service platform.
The defining characteristic of zkPass is the offloading of ZKP computations to a server operating within a Trusted Execution Environment (TEE). Users only need to initiate a service request through the zkpass-client SDK library, which then delegates the heavy computational tasks to the server side.
The zkPass is specifically designed to support privacy-preserving applications. It provides the client libraries and secure middle-layer infrastructure to implement applications that protect the privacy of user data and support a verifiable computation environment. zkPass uses ZKVM (Zero Knowledge Virtual Machine) as the underlying core proof system on which the applications run. In the future, zkPass may also support a new proof system other than Zero Knowledge Proof.
The high-level architecture view of the zkPass is illustrated here:
Currently, zkPass implements one such zkPass module, the Data Verification Request (DVR). Future releases of zkPass can support other forms of privacy-protecting applications. This guide will focus primarily on two things: the service infrastructure of zkPass and the DVR application.
The next section describes each component of the zkPass.
Data Verification Request (DVR) is the main zkPass module running within the framework of the zkPass Service.
The DVR application facilitates the verification of user data while maintaining its privacy. To use the DVR and participate in the DVR workflow, the DVR clients take one of the following client roles: Data Issuer, Data Holder (the user), and Proof Verifier.
The Proof Verifier sets the criteria for users to access certain services or resources. These criteria are encoded as a query script written by the Proof Verifier client, and the script represents business logic that verifies against the user's documents.
Although the user owns their data, it is typically issued and signed by a trusted entity known as the Data Issuer. The zkPass service processes the business logic specified in the DVR query script, generating a Zero Knowledge proof and the query output. The Proof Verifier then uses this proof and output to determine if the user meets the specified criteria. Throughout this process, the user’s data is never transmitted to the Proof Verifier, ensuring its privacy. The Verifier only receives the proof and the relevant output.
The high-level view of the DVR application and its clients is illustrated here.
It should be noted that with this server-centric approach, the user's sensitive input data is no longer confined to their device but is instead processed in a centralized server. This shift necessitates a degree of trust to ensure the confidentiality of the user's input. To alleviate this concern, zkPass Service runs the zkPass module, such as the DVR, within a Trusted Execution Environment (TEE). This secure and isolated environment aims to provide an additional layer of protection, safeguarding the privacy of user data while allowing for the efficient execution of DVR queries. In other words, zkPass can still protect data confidentiality through the trusted privacy model.
The diagram of the DVR for the holder-centric workflow is depicted below.
Beyond merely transferring the computational load of proof generation from the client device to the server, DVR incorporates a robust JSON-based query language (DVR Query) that empowers developers to articulate specific requirements or conditions to be applied to the user's data. This JSON query is executed within the Zero-Knowledge Virtual Machine (ZKVM), resulting in a cryptographic proof that verifies the execution has occurred exactly as intended, without any alterations.
The DVR inherits the two pivotal features from its client-side predecessor, enhancing them within its server-centric architecture:
Trusted Data Privacy By generating a cryptographic proof, DVR ensures that the underlying data remains confidential. The Proof Verifier can confirm the proof's validity without ever needing to access the original sensitive data. While the service-based approach does introduce a new set of concerns, which is the need to trust a centralized server with sensitive user data, DVR mitigates this issue by operating within a TEE. This adds an extra layer of security to maintain data integrity and confidentiality in an isolated and secure centralized computer.
Query Execution Transparency The cryptographic proof generated by ZKVM serves as an immutable record that the query has been executed faithfully, meeting all specified conditions or requirements. Unlike often rigid proof functions found in client-side implementations, DVR offers an easy-to-use JSON query language. This allows users to effortlessly adjust to varying logic to enforce data requirements or conditions.
This advanced feature set not only alleviates computational constraints but also offers a highly flexible, secure, and transparent way for developers to implement privacy-centric logic within their applications.
Transitioning from a client-centric to a service-oriented proof system, the DVR application and the zkPass Service strive to deliver a scalable, efficient framework that accommodates a wide range of devices with diverse computational resources. It does so without compromising its commitment to data privacy and transparent execution. Moreover, it incorporates a versatile JSON-based DVR query language that is adaptable to any user data schema, offering users even greater flexibility.
Understanding the DVR and its functionalities revolves around comprehending three fundamental concepts that form the backbone of the system. These concepts are integral to the operations of DVR running on zkPass Service and are crucial for anyone looking to effectively utilize or develop with this application.
The diagram below illustrates the relationship among the three:
At a fundamental level, the user data and the DVR Info, which contains the query, act as essential inputs to the DVR/zkPass. These two components are necessary for the generation of the zkPass proof.
For a more comprehensive understanding of the zkPass proof creation, examining the query processing pipeline provides insight into how this process unfolds.
Data Verification Request Info
DVR Info is information that contains data and parameters that define the behavior of the DVR application as defined by the Proof Verifier. Each DVR Info has two main parts:
Metadata (The Envelope of the DVR) Think of the metadata as the envelope that holds the DVR. It contains:
DVR ID This is like a tracking number for the request. It helps to know which question you're dealing with. This information is mainly used by the zkPass Service.
User Data Requests A mapping containing multiple UserDataRequest, which contains the User Data URL and the Public Key
User Data URL The URL to retrieve the user data referenced by the DVR Query variables. The Proof Verifier uses this information to tell the Data Holder where to download the user data content. A Data Issuer typically hosts the URL site. Note that this information is optional. The absence of this information means that the way to determine where to get the user data is embedded in the application business logic of the Data Holder.
Public Key This public key verifies that the user's data hasn't been tampered with.
Query (The Actual Question) The real heart of the DVR is the query. This is the actual question or condition you want to check against the user's data. In zkPass, you write this query using a unique format called zkPass JSON Query Language. The query uses the concept of variables to reference elements that exist in the user data and compare the variable values with specific constant literals.
In this example query, variable "personalInfo.firstName" references the JSON element "firstName" whose parent element is "personalInfo". This element exists in the user data.
Like user data, the Digital Verification Record (DVR) must transform into a secure, two-layered cryptographic token. Here's how it works:
This dual-layer token security model ensures that only the Proof Verifier, Data Holder, and zkPass Query Host can access the DVR's content while also allowing for verification of the token's authenticity. The design also guarantees that the DVR can be safely transmitted; unauthorized parties won't be able to modify or read the token as it moves through the network toward its final destination at the zkPass Service.
So, a DVR Info is a two-part package:
Metadata tells you which DVR you're dealing with and makes sure the user data is verifiable
Query specifies what you want to know about the user's data
By understanding these parts, you can use DVR Query language to ask all sorts of specific questions about user data in a secure and organized way.
Providing a REST API to retrieve the user data
The Data Issuer is required to expose a REST API that facilitates secure user data token retrieval. The API should be designed to authenticate the user robustly, ensuring that only the legitimate owner can access the data. The zkPass SDK does not dictate the precise authentication mechanisms, API semantics, or response formats, providing developers the flexibility to implement an approach best suited to their application's architecture.
The Data Issuer needs to make sure the user data is in JSON encoding. The DVR app architecture does not dictate the schema or structure of the user data, however, JSON encoding is required.
By conforming to these guidelines, Data Issuers contribute to the robustness and security of the DVR app infrastructure, ensuring an optimized and secure experience for all users involved.
Signing the User Data
As the authority provisioning sensitive user data, the Data Issuer plays a critical role in the DVR ecosystem. To ensure the authenticity of the user data, the Data Issuer must sign this sensitive information into a JWS (JSON Web Signature) token. The signing of the user data by the Data Issuer is illustrated by part of the DVR/zkPass call sequence, which is highlighted in red below:
The Dvr module client SDK library provides a specialized utility method for this purpose: callDvrGenerateUserDataToken
. How to digitally sign the user data using the Dvr module client SDK library is illustrated by the code snippet below.
Parameters passed to callDvrGenerateUserDataToken
:
signingKey This is the signing private key owned by the Data Issuer.
JSON.stringify(data) This is a stringified JSON user data.
verifyingKey This is a key to validate user data token.
User data encapsulates a spectrum of sensitive and confidential attributes, credentials, or claims, ranging from driver's licenses and passports to financial credentials such as bank account details.
The user data is modeled after the , which are structured pieces of information associated with a particular subject. Unlike the Verifiable Credentials, which adhere to rigorous and complex formatting standards, our user data model offers flexibility. It's engineered to accommodate any user data schemas, including the Verifiable Credentials.
In the app architecture, the individual or system who actually owns the data is referred to as the Data Holder or User. However, this data is initially provided by another party, known as the Data Issuer.
One of the standout features of zkPass is its adaptability to various data structures. The framework is designed to be "schema-agnostic," meaning it doesn't impose a specific schema on the data. This flexibility allows the Data Issuer to work with different types of data structures seamlessly.
For Data Issuers, the only requirement is that the data should be encoded in JSON format. This standardization enables easy integration into the zkPass workflow without necessitating specific data schematization.
At the end of the data flow, the consumer of this user data is the DVR app which is running inside the zkPass Host. This component operates in a secure and isolated environment, ensuring the integrity and confidentiality of the user data being queried.
In the context of secure data transmission, the user data content needs to be encapsulated within a multi-layered cryptographic token for confidentiality and integrity. Specifically, this token consists of two nested layers:
This double-layered security ensures that the user data remains confidential and accessible only by authorized components during transit.
By employing this nested-token architecture, the user data can be securely transmitted through the network. Only the Data Issuer, Data Holder, and zkPass Host are allowed to access the user data's content. This not only maintains the confidentiality and integrity of the user data but also prevents unauthorized parties from tampering with or viewing the token during its transit to the zkPass Service.
Sending the ZkpassProof object to the Proof Verifier for verification
From Data Holder perspective, no integration with the Dvr module client SDK library is needed for this step.
Once the Data Holder receives the Zkpass Proof from the zkPass Service, it will pass it along to the Proof Verifier for verification. The Proof Verifier provides a for this purpose.
The zkPass call sequence diagram, specifically steps 10–12, corresponds to the proof verification process.
The zkPass Service offers flexible hosting options to meet diverse organizational needs and data management preferences. Understanding these options is crucial for choosing the most suitable deployment strategy that aligns with your organizational requirements, control levels, and data privacy standards.
There are three main hosting options for the zkPass Service:
Each hosting option for the zkPass Service comes with its own set of advantages and considerations. Public cloud hosting offers ease and scalability, private cloud hosting provides additional control and customization, and on-premise hosting delivers the utmost in data sovereignty and security. Organizations should carefully assess their specific needs, regulatory requirements, and resource capabilities to select the most appropriate hosting solution for their implementation of the zkPass Service.
Calling zkPass Service's generate_zkpass_proof REST API to create the ZkPass Proof
To generate the ZkPass Proof, the Data Holder needs to use the zkpass-client SDK library. The following section illustrates how the coding is done.
The zkPass call sequence diagram, specifically steps 7–9, corresponds to the proof generation process.
The Data Holder generates the proof by using the Dvr module client SDK library, as shown here.
The zkPass Service employs different trust models with regard to data privacy, data integrity, and computation integrity.
zkPass primarily uses a Trusted Execution Environment (TEE) to protect the input's privacy and integrity. (Although TEE can also be used to protect the execution of proof computation, zkPass relies on the trustless ZKP technology for execution integrity, as explained in the next point.). The zkPass server has two main components that process the user’s data input:
Digital signature verification on the user’s data
ZK proof calculation, which takes the user’s data as the input.
Because the data must be unencrypted during processing, both components must be running under TEE to ensure that the user’s data privacy is always protected throughout the entire process. Homomorphic Encryption (HE) cannot be applied here as HE has minimal capabilities in terms of what computation it can perform, while both DSA and ZKVM involve very complex computations. Therefore, the data privacy protection in zkPass is based on a Trusted Model, in which the user basically must trust that the zkPass server is implemented correctly and holistically to protect the privacy of the user’s data.
The zkPass service takes two inputs: the signed credential and the signed DVR. Both inputs need to be DSA-verified by the zkPass service to make sure they are not tampered with. The DSA verification can occur either inside or outside the ZKP proof function. Therefore, there can be two different approaches to the data integrity model:
Trusted Data Integrity The digital signature verification on the credential and DVR is performed in TEE but outside of the ZKP proof function.
Trustless Data Integrity The digital signature verification on the credential and DVR is performed inside the ZKP proof function running in the TEE.
While the trustless data integrity model is the preferred one, the DSA verification computation is quite heavy to run inside the ZKVM engine. Currently, there are some limitations on how much processing you can perform on a ZKVM. Due to this constraint, the current proposal is to choose the Trusted Model for data integrity as it is practically feasible to implement and reasonably secure. However, it is very possible that we can use the trustless model in the near future if the underlying ZKVM engine has improved its processing capabilities.
zkPass uses a ZKVM engine (Zero Knowledge Virtual Machine) to ensure the proof function is executed in a verifiable computation environment. In this regard, the proof generation feature is based on the Trustless Model, in which the Verifier can confidently confirm if the generated proof and output are valid without the need to trust the zkPass server or any other third-party entity.
The following table summarizes the zkPass trust models:
The trusted model for data privacy, which is less desirable, is the result of the trade-off of moving the ZKP computation from the user’s private space into an external server managed by a third-party entity. Nevertheless, as described in the zkPass Service design, we believe that the proposed trust models are sufficiently secure enough and provide an effective and practical solution for the proof system needed for the didPass ecosystem.
Retrieving the Data Verification Request (DVR) from the Proof Verifier
From Data Holder perspective, no integration with the Dvr module client SDK library is needed for this step.
The Data Holder first gets the DVR by calling the provided by the Proof Verifier.
The zkPass call sequence diagram, specifically steps 1–3, corresponds to the DVR retrieval process.
Retrieving the User Data from the Data Issuer
From Data Holder perspective, no integration with the Dvr module client SDK library is needed for this step.
The User Data retrieves the user data that is needed by the DVR by calling the provided by the Data Issuer.
The zkPass call sequence diagram, specifically steps 4–6, corresponds to the User Data retrieval process.
The heart of the DVR application is the query engine, which implements the DVR app. The query engine is designed as a DVR Query language interpreter that runs on the ZKVM directly.
DVR Query Engine Codes The core component, the DVR Query Engine, is programmed in the Rust language. Rust is known for its safety and performance, making it an excellent choice for building reliable and secure systems.
Compilation to Assembly Code To integrate with the Zero-Knowledge Virtual Machine (ZKVM), the DVR Query Engine is compiled into assembly code. This compilation is done using a specialized set of tools known as the compiler toolchain, which is specifically designed for the ZKVM environment. This ensures that the Query Engine is compatible with the security and operational requirements of the ZKVM.
Build Outputs After the compilation process, two primary outputs are generated:
The Zero-Knowledge Proof Generator (ZK Proof Generator) This module is responsible for creating cryptographic proofs that confirm the validity of a query without revealing any underlying data. It is an integral part of the DVR Query Engine.
The Zero-Knowledge Proof Verifier (ZK Proof Verifier)
This is the counterpart to the Proof Generator. It is tasked with checking the validity of the proofs generated by the Proof Generator. The Proof Verifier is included in the zkpass-client
library, allowing client applications to verify proofs independently.
zkPass Service processes the DVR query contained in the DVR Info and the user data referenced by the query in a pipeline flow, as depicted below.
Initialization of the Data Verification Request(DVR) The proof verification begins by creating a Data Verification Request (DVR). This record is essential as it holds the specific request or "query" that needs to be verified.
Inputs for Verification There are two key pieces of information that the DVR Query Engine requires to perform verification:
The Query: This is the request for information or action that needs to be checked.
The User Data: This refers to any information related to the user that the query will use or check against.
Processing by the DVR Query Engine The DVR Query Engine is the powerhouse where the actual verification takes place. This engine operates within the Zero-Knowledge Virtual Machine (ZKVM), a secure environment designed for processing these queries.
Results of the Verification Once the query has been processed, there are two results produced:
The Zero-Knowledge Proof (ZK Proof) This is a verification result that proves the query was processed correctly without revealing any private details.
The Query Result This is the outcome of the query after it has been processed.
Packaging the Results Both the ZK proof and the query result are bundled into a single package known as the zkPass Proof object. This object can then be used to confirm the integrity and accuracy of the query process without exposing any sensitive information.
For successful integration into the DVR application workflow, each client stakeholder is advised to follow the guidelines specified in this documentation.
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.
The DVR app distinguishes itself with its adaptable workflows, specifically tailored to suit different business contexts. The platform supports two primary workflows: Holder-Centric, ideal for B2C (Business-to-Client) scenarios, and Verifier-Centric, suited for B2B (Business-to-Business) environments. Understanding how these workflows operate and their applicability can greatly enhance the effectiveness of DVR in various settings.
In a B2C setting, where businesses interact directly with individual clients or customers, the Holder-Centric workflow is particularly effective. Here, the Data Holder (the client or customer) initiates the data verification process by requesting a Data Verification Request (DVR) from the Proof Verifier. This approach empowers the individual, allowing them to control how and when their data is verified, aligning perfectly with customer-centric business models where individual agency and privacy are paramount.
Conversely, in a B2B context, the Verifier-Centric workflow becomes more relevant. In this model, the verification process starts with the Proof Verifier, usually a business, sending the DVR directly to the Data Issuer. This workflow is suitable for situations where businesses need to establish or verify partnerships, credentials, or compliance among other businesses. The verifier-centric approach offers a streamlined and efficient method for regular or systematic verifications, which is common in business-to-business interactions.
DVR's capability to support both holder-centric and verifier-centric workflows provides a significant advantage in catering to a wide range of customer needs. Whether it’s a business dealing with individual clients or other businesses, DVR offers a tailored approach to data verification. This flexibility ensures that the platform is not only versatile but also highly relevant and efficient in various real-world applications.
In summary, the dual workflow approach of DVR – holder-centric for B2C and verifier-centric for B2B – showcases the platform's versatility and adaptability to different business models. By understanding and utilizing these workflows appropriately, organizations can maximize the benefits of DVR, ensuring a seamless, secure, and user-friendly experience in their data verification processes.
To install the Dvr Module Client lib separately, please refer to this section
Ubuntu version 20 or higher, WSL (Windows Subsystem for Linux) is also supported.
or later.
Make sure the VPN is off
This command will enable the necessary features to run WSL and install the Ubuntu distribution of Linux.
If your underlying system, like Ubuntu, is already Linux-based, you can skip this step.
If your Windows version is below Windows 10 2004, please refer to instead.
Open PowerShell or Windows Command Prompt in administrator mode by right-clicking and selecting "Run as administrator"
Run the command below
Restart your machine
Once you have installed WSL, you will need to create a user account and password for your newly installed Linux distribution.
The above command only works if WSL is not installed at all, if you run wsl --install
and see the WSL help text, please try running wsl --list --online
to see a list of available distros and run wsl --install -d <DistroName>
to install a distro. To uninstall WSL, see or .
If you have installed WSL before, you can login using the command wsl
nvm
allows you to quickly install and use different versions of node via the command line.
Run the command below
Restart your terminal session
To check whether Node has been installed properly, run the commands below:
To check whether Node has been installed properly, run the commands below:
If you wish to explore our demo application, feel free to skip this installation step, as it has already been completed in the demo application.
If you want to use our zkpass-client-ts library on your own project / outside the demo application, you can follow this step
Set the npm registry configuration to gdp-labs registry.
Install the zkpass-client library for typescript
For NextJS projects with App Routing, several configurations have to be made in next.config.js
file:
To try our Typescript CLI demo, you can follow these steps
Clone demo repository
Go to Typescript CLI demo directory (Let's assume this is our root directory for steps below)
Install packages
Run Dewi demo
It will run the demo using predefined user data and DVR for Dewi. The expected query result is "false".
Expected result :
Run Ramana demo
It will run the demo using predefined user data and DVR for Ramana. The expected query result is "true".
Expected result :
Run Jane demo
It will run the demo using predefined user data and DVR for Jane. The expected query result is "true".
Expected result :
Run demo with custom data
You can run the demo using custom data. Examples for user data and DVR can be found in rust/test/data
.
Example running demo using custom data :
Expected result :
Run demo with multiple user data
You can also run the demo using multiple user data. Examples for multiple user data and DVR can be found in typescript/test/data/multiple
.
Example running demo using multiple data:
Here's the directory structure for Tyepscript SDK tutorial.
Components :
MyHoder, MyIssuer, and MyVerifier provide an overview of the process.
The Libs folder contains the detailed implementation of each actor.
The Utils folder includes miscellaneous functions.
Here's the directory structure for Rust SDK tutorial.
The privacy-apps components :
DVR types provide the necessary definitions for developers to interact with libdvr_client.so
.
Client utils contain FFI helpers for working with DVR types.
The zkpass-demo components :
data_holder.rs
: Handles the entire process, from generating tokens to verifying proofs.
data_issuer.rs
: Manages the process of generating user data tokens.
proof_verifier.rs
: Handles the generation of DVR tokens and the proof verification process.
lib_loader.rs
: Contains the detailed logic for interacting with libdvr_client.so
.
This section describes how we use the zkPass SDK in our demo code
This code snippet generates a zkPass proof. It requires 3 parameters:
SERVICE_URL
: you can use https://playground-zkpass.ssi.id
, or use your own endpoint if you deploy zkPass on your own server.
API_KEY
& API_SECRET
: Get yours at https://portal.ssi.id
userDataToken
: check section for more details.
dvrToken
: check section for more details.
This code snippet verifies a zkPass proof token. Components :
expectedMetadata
: this is the expected metadata of the dvr.
dvrPayload
: the dvr payload extracted from Dvr token.
This code snippet generate user data token. Components :
signingKey
: a private key used to sign user data.
data
: user data in JSON format.
verifyingKey
: a public key to verify that user data token.
This code snippet generate DVR token. Components :
signingKey
: a private key used to sign dvr.
dvrData
: Dvr data to sign.
Providing a REST API to retrieve the DVR
The Proof Verifier must also define a mechanism through which users can retrieve the DVR token. The retrieval could be accomplished through various means, such as QR code scanning, a RESTful API, or other methods. zkPass SDK provides the flexibility to choose a retrieval mechanism most appropriate to the application's architectural design.
Signing the DVR data
The Proof Verifier is the entity responsible for defining the Data Verification Request (DVR) against which user data is verified. To accurately create DVR queries, the verifier must have an in-depth understanding of the user data format as provided by the Data Issuer. Utilizing zkPass Query Language, the verifier can reference specific fields within the user data using the notion of 'Variable'.
Upon receipt of a Zero-Knowledge Proof (ZKP) from the user, the verifier invokes zkPass.verifyProof function to authenticate the proof. A successful verification indicates that the user's data complies with all conditions stipulated in the DVR query.
The Proof Verifier is responsible for generating tokens for the DVR content. To achieve this, it must manage a public/private key pair specifically for digital signing. Additionally, the Proof Verifier should expose a standard JWKS (JSON Web Key Set) endpoint through a RESTful API for signature verification purposes. This endpoint serves as the source for obtaining the public key required to validate the DVR token's signature.
To facilitate the zkPass flow, the verifier must tokenize the DVR object into a JWT (JSON Web Token). In the inner token’s JWT header, the following parameters will be included by the verifier:
jku The URL where the public verification key can be retrieved.
kid The Key ID, is a unique identifier for the specific verification key in use.
In the implementation of the DVR retrieval codes, the Proof Verifier needs to digitally sign the DVR. This is done using the zkpass-client SDK library as illustrated here.
Ubuntu version 20 or higher WSL (Windows Subsystem for Linux) is also supported. Other similar Linux distros should also work.
For WSL installation guide, .
Some APT package dependencies Run the following to install the required packages:
Rust compiler toolchain Follow this 2-step instruction to install the Rust toolchain.
Follow these steps to install the zkPass SDK and to run the demo application.
For the purposes of this guide, the zkpass-sdk
repository is cloned under the home directory of the current user, retaining its default name. This places the root directory for the zkpass-sdk
repository at ~/zkpass-sdk
. As a result, the directory for the Rust/Linux binding of the SDK is set at ~/zkpass-sdk/rust
.
Should you choose to clone the zkpass-sdk
repository into a different location, ensure that you adjust any referenced paths in the instructions to match your chosen directory structure.
Clone the zkpass-sdk repo
Enter zkpass-sdk/rust
Directory
From the zkpass-sdk/rust
directory, execute test.sh
script to build the SDK and run the demo application:
The correct output of zkpass-demo should look like the following:
This demo will download a binary file. If the download process times out, try the following solutions:
Ensure you have a stable internet connection when running the script.
Turn off any active VPNs and try again.
The error message "cannot open shared object file: No such file or directory" indicates an issue. This may occur due to missing or corrupted .so. Here are some possible solutions:
Ensure you have a stable internet connection when running the script.
Turn off any active VPNs and try again.
Manually download the .so file:
Move these files to zkpass-sdk/rust/lib
folder.
Comment out download-so.sh
in test.sh
script.
Run the test.sh
script again; the error should be resolved.
A collection of types used in the DVR module
▸ PublicKeyOrKeysetEndpoint: |
A union type that can either be a PublicKey or KeysetEndpoint.
▸ ZkPassOutput: { [key: string]: string | number | boolean }
Key-value pairs representing the output data from a zkPass operation.
▸ ZkPassProof: Object
Properties representing a zkPass proof.
▸ VerifyZkPassProofResult: Object
Result of verifying a zkPass proof.
A collection of interfaces used in the DVR module
▸ PublicKey: Object
Represents a public key with x and y coordinates.
▸ KeysetEndpoint: Object
Represents a keyset endpoint configuration.
▸ PublicKeyOptionUnion: Object
Union of possible public key options.
▸ PublicKeyOption: Object
Configuration for public key options.
▸ UserDataRequest: Object
Request format for user data.
▸ DvrData: Object
Data structure for DVR operations.
▸ DvrDataPayload: Object
Payload format for DVR data.
▸ ExpectedDvrMetadata: Object
Expected metadata for DVR operations.
A collection of constants used in the DVR module
The zkpass-client API Reference is available as .
Before using the Generating Proof Endpoint, There are three essential items you'll need to use the endpoint:
encryptedUserDataToken
: This token contains your encrypted user data
encryptedDvrToken
: This token holds your encrypted DVR data
apiToken
: This unique identifier authenticates your requests with the zkPass API
apiToken
is the base64 form of YOUR_API_KEY:YOUR_API_SECRET
.
For instructions on creating the encryptedUserDataToken
and encryptedDvrToken
, refer to our section. It provides a step-by-step guide that covers:
: This creates the keys you'll use for signing your data.
: This step adds a digital signature to your data tokens, ensuring their authenticity.
: This encrypts your data tokens, making them unreadable by anyone without the decryption key.
A collection of FFI types used in the DVR module
▸ FfiResultUserDataToken: StructType A structure representing the result of a user data token operation.
Parameters:
▸ FfiResultDvrToken: StructType A structure representing the result of a DVR token operation.
Parameters:
▸ FfiResultZkPassProofToken: StructType A structure representing the result of a zkPass proof token operation.
Parameters:
▸ FfiResultVerifyZkPassProofToken: StructType A structure representing the result of a zkPass proof verification token operation.
Parameters:
▸ PublicKeyFfi: StructType A structure representing a public key.
Parameters:
▸ KeysetEndpointFfi: StructType A structure representing a keyset endpoint.
Parameters:
▸ PublicKeyOptionUnionFfi: StructType A structure representing a union of public key and keyset endpoint.
Parameters:
▸ PublicKeyOptionFfi: StructType A structure representing a public key option with tag and value.
Parameters:
▸ UserDataRequestFfi: StructType A structure representing a user data request.
Parameters:
▸ DvrDataFfi: StructType A structure representing DVR data.
Parameters:
▸ ExpectedDvrMetadataFfi: StructType A structure representing expected DVR metadata.
Parameters:
Make sure you have key pair consisting of :
publicKeyJWKS
privateKey
Read section for detail info.
We need to sign and before sending a request to the zkPass service. This ensures that the payload is not tampered during transport.
The JSON Web Key Set (JWKS) is a set of keys containing the public keys used to verify any JSON Web Token (JWT) issued by the Authorization Server and signed, You can find a complete definition of JWKS .
Upload your publicKeyJWKS
so that it's accessible from the internet. This will be used by zkPass service to verify the validity of the user data.
Example of the uploaded publicKeyJWKS
This is an example code of how you can sign a JSON object as JWS format in Typescript. Let's say you uploaded your publicKeyJWKS
to https://mywebsite/my-keys.json
Example for User Data
Below is the example of Query in DVR, this query will be included in full DVR
Below is the example of full DVR that will be generated into DVR Token
After this section you should have :
User Data Token : User Data in JSON Web Signature (JWS) format.
DVR Token : DVR in JSON Web Signature (JWS) format.
Here's the example of User Data Token & DVR Token in JWS format.
This section describes how we use the zkPass SDK in our demo code
This code snippet generates a zkPass proof. It requires 3 parameters:
credentials
: Get yours API key and secret at https://portal.ssi.id
user_data_tokens
: stringified signed users data.
dvr_token
: signed Dvr query.
This code snippet verifies a zkPass proof token. Components :
expected_metadata
: this is the expected metadata of the dvr.
zkvm
: zkvm used to generate proof, currently we only support r0
.
service_url
: you can use https://playground-zkpass.ssi.id
, or use your own endpoint if you deploy zkPass on your own server.
This code snippet generate user data token. Components :
signing_key
: a private key used to sign user data.
data
: user data in JSON format.
verifying_key
: a public key to verify that user data token.
This code snippet generate DVR token. Components :
signing_key
: a private key used to sign dvr.
dvr_data
: Dvr data to sign.
User Data encapsulates a spectrum of sensitive and confidential attributes, ranging from governmental identification forms like driver's licenses and passports to bank accounts.
In the DVR model, this data is owned by the Data Holder (the user) but provisioned by an entity known as the Data Issuer.
Notably, the DVR and zkPass framework accommodates a high degree of data schematization flexibility. It is engineered to be agnostic to any particular data schema, seamlessly interfacing with JSON objects or any other structured format specified by the Data Issuer. The eventual consumer of the data user is the DVR app running on the zkPass Service.
For a complete definition of the user data, please follow this .
Make sure you have :
userDataToken
dvrToken
Read section for detail info.
zkPass enhances the security of your data during transport by encrypting it before sending it over the network. The are only two entities that can access the data: the holder and zkPass host running in a Trusted Execution Environment (TEE).
First, find the zkPass public key in the .well-known/jwks.json
file at this endpoint: The key you're looking for has a kid (Key ID) of "ServiceEncryptionPubK".
After this section you should have :
Encrypted User Data Token (in JWE Format).
Encrypted DVR Token (in JWE Format).
Here's the example
Helper functions for transforming data into FFI-compatible format
▸ transformPublicKeyOrKeysetToFfi
(value
: ): object
Parameters
Returns
object
- The FFI equivalent of the provided PublicKeyOrKeysetEndpoint
Throws
Error if PublicKeyOrKeysetEndpoint is missing required fields
Error if PublicKeyOrKeysetEndpoint has an invalid type
Parameters
Returns
object
- A new instance of DvrDataFfi containing the transformed data
Throws
Error if user_data_requests is empty
Parameters
Returns
object
- An FFI equivalent of the input metadata
Throws
Error if metadata.user_data_verifying_keys is empty
Before you get started with the zkPass API, here's what you'll need:
User Data Token
DVR Token
The zkPass API uses a familiar approach called basic authentication to ensure secure access. Here's what you'll need:
API Key: This unique identifier acts like your username for the API.
API Secret Key: Consider this your password, but much more secure. Keep it confidential!
Register on the to obtain your API and secret keys.
To access the API, you'll need to provide both your API Key and API Secret Key in every request you make. They should be included in the authorization header of your requests.
No worries! If you haven't received your API credentials, simply fill out our easy-to-use to request them. We'll get you set up in no time.
Our utilities section provides a detailed guide on creating a key pair. This key pair is used for signing and encrypting your user data token (and DVR token, if needed). Here's a quick overview of the steps involved:
Inner Token (for signing) This is the DVR data that gets signed by the Proof Verifier into a token. The signing ensures that the token's authenticity can be later verified. The signed DVR token is typically sent from the Proof Verifier to the Data Holder. Once received by the Data Holder application, the user can still view the content of the DVR for visual verification of what the query intends to check on the user data.
Outer Token (for encrypting) This is the previously signed DVR token which has been encrypted into a JSON Web Encryption (JWT) token by the Data Holder application. Prior to sending the signed DVR token to the zkPass Service, the Data Holder encrypts the token again by wrapping it with a token. This is to ensure that only the zkPass Query Host process (a critical component inside the zkPass Service), which runs in the Trusted Environment Environment (TEE), can decrypt and view the DVR's content while the data is in transit.
Inner Token (for signing) This is the user data that gets signed by the Data Issuer into a token. This digital signature guarantees that the token's origin and integrity can be verified at a later stage. Typically, this signed token is then transmitted from the Data Issuer to the Data Holder. Upon receipt, the Data Holder's application allows the user to visually inspect the content of their data. This ensures transparency while maintaining the token's secure and authenticated state.
Outer Token (for encrypting) The user data token, initially signed by the Data Issuer, undergoes another layer of security before it's sent to the zkPass Service. The Data Holder's application encrypts this signed token into a format. The reason for this additional encryption is to restrict access to the token's content while it's being transferred. Specifically, only the DVR app running in the zkPass Host process—a key component within the zkPass Service that operates in a Trusted Execution Environment (TEE)—is authorized to decrypt and view the content of the user data.
For a complete WSL installation guide, refer to .
Complete NVM documentation can be found .
Complete Git documentation can be found .
The serverComponentsExternalPackages
configuration ensures that the package @zkpass/dvr-client-ts
is excluded from NextJS' bundling and compilation process, allowing it to be imported directly from node_modules
. As a result, remember to include the node_modules
directory in your production build. See .
The demo application will run in a CLI and requires 2 parameters: DVR and user data. Please review to have better understanding of the use case.
zkPassProofToken
: check section for more details.
Download file from the website.
Please see example of encrypted User Data and DVR .
▸ UserDataRequestArrayFfi: ArrayType An array type of structures.
▸ UserDataVerifyingKeysFfi: ArrayType An array type of structures used for verifying keys.
A JSON Web Signature (abbreviated JWS) is an IETF-proposed standard (RFC 7515) for signing arbitrary data. This is used as the basis for a variety of web-based technologies including JSON Web Token. You can find a complete definition of JWS .
zkpass_proof_token
: check section for more details.
▸ transformDvrDataToFfi
(data
: ): object
▸ transformExpectedDvrMetadataToFfi
(metadata
: ): object
Trust Model
Data Privacy
Trusted (via TEE)
Data Integrity
Trusted (via TEE)
Computation Integrity
Trustless (via ZKVM)
zkproof
string
The zkPass proof string
dvr_title
string
Title of the DVR
dvr_id
string
Identifier of the DVR
dvr_digest
string
Digest of the DVR
user_data_verifying_keys
object
Keys used for verifying user data
dvr_verifying_key
object
Key used for verifying DVR
time_stamp
number
Timestamp of the proof generation
output
The output data
zkpass_proof
The zkPass proof data
jku
string
JSON Web Key Set URL
kid
string
Key identifier
keyset_endpoint?
Optional keyset endpoint
public_key?
Optional public key
tag
Type of the public key option
value
Value of the public key option
key
string
Key for the user data
value
Verifying key or endpoint
zkvm
string
ZK Virtual Machine identifier
dvr_title
string
Title of the DVR
dvr_id
string
Identifier of the DVR
query
string
Query string
user_data_requests
Array of user data requests
dvr_verifying_key
Key for verifying DVR
zkvm
string
ZK Virtual Machine identifier
dvr_title
string
Title of the DVR
dvr_id
string
Identifier of the DVR
query
string
Query string
query_engine_ver
string
Query engine version
query_method_ver
string
Query method version
user_data_requests
object
User data requests
dvr_verifying_key
object
Key for verifying DVR
ttl
number
Time to live
dvr
string
DVR string
user_data_verifying_keys
Array of user data verifying keys
MISSING_PUBLIC_KEY_VALUES
Thrown when a public key option is missing 'x' or 'y' values
MISSING_KEYSET_ENDPOINT_VALUES
Thrown when a keyset endpoint option is missing 'jku' or 'kid' values
INVALID_PUBLIC_KEY_OPTION_TYPE
Thrown when an invalid public key option type is provided
MISSING_USER_DATA_REQUESTS
Thrown when user_data_requests array is empty
MISSING_USER_DATA_VERIFYING_KEYS
Thrown when user_data_verifying_keys array is empty
ERROR_INVALID_PAYLOAD
Thrown when parsed payload is not of type DvrData
ERROR_INVALID_JWT
Thrown when JWT token format is invalid
ERROR_INVALID_ZK_PROOF
Thrown when ZK proof payload format is invalid
INVALID_INPUT
Thrown when input is neither a valid PublicKey nor KeysetEndpoint
INVALID_TOKEN
Constant string representing an invalid token
INVALID_VERIFY_PROOF
JSON string representing an invalid verify proof error
Authorization
base64 form of YOUR_API_KEY:YOUR_API_SECRET
Content-Type
Indicates that the content being sent or received is JSON data
user_data_token
string
Mandatory
encrypted user data token in JWE format
dvr_token
string
Mandatory
encrypted dvr token in JWE format
result
ref.refType(ref.types.CString)
The operation result
error
ref.types.CString
Error message if any
result
ref.refType(ref.types.CString)
The operation result
error
ref.types.CString
Error message if any
result
ref.refType(ref.types.CString)
The operation result
error
ref.types.CString
Error message if any
result
ref.refType(ref.types.CString)
The operation result
error
ref.types.CString
Error message if any
x
ref.types.CString
X coordinate of the public key
y
ref.types.CString
Y coordinate of the public key
jku
ref.types.CString
JSON Web Key Set URL
kid
ref.types.CString
Key identifier
public_key
The public key structure
keyset_endpoint
The keyset endpoint structure
tag
ref.types.uint64
Type identifier
value
The key data
key
ref.types.CString
Request key
value
Request value
zkvm
ref.types.CString
ZKVM identifier
dvr_title
ref.types.CString
DVR title
dvr_id
ref.types.CString
DVR identifier
query
ref.types.CString
Query string
user_data_requests
Array of user data requests
user_data_requests_len
ref.types.uint64
Length of user data requests array
dvr_verifying_key
DVR verifying key
ttl
ref.types.uint64
Time to live
dvr
ref.types.CString
DVR data token
user_data_verifying_keys
Array of verifying keys
user_data_verifying_keys_len
ref.types.uint64
Length of verifying keys array
data
The DVR data to transform
metadata
The metadata to transform
x
string
X coordinate of the public key
y
string
Y coordinate of the public key
HTTP Method
POST
API endpoint (Playground)
https://playground-zkpass.ssi.id/api/1.0/dvr/1.0/proof
value
The value to transform
400
INVALID_PARAMS
Invalid parameter(s).
The provided parameters don't meet the required format or validation rules for the app input
400
INVALID_PARAMS
Error serializing parameters
Our system failed to convert the provided parameters into the required format
404
INVALID_URL
Invalid URL
The requested privacy app endpoint or resource was not found in our system
500
ERROR_LOADING_APP
Something went wrong. Contact the administrator if the error persists
Our system failed to initialize or load the requested privacy app
500
ERROR_LOADING_INSTANCE
Something went wrong. Contact the administrator if the error persists
Our system failed to create a new instance of the privacy app
500
CUSTOM_ERROR
[Custom message]
A specific error occurred that requires custom handling (message varies)
500
MISSING_APPS_CONFIG
Something went wrong. Contact the administrator if the error persists
The required configuration for privacy apps is not found or inaccessible
500
ERROR_LOCKING_SOCKET
Something went wrong. Contact the administrator if the error persists
Our system failed to establish exclusive access to the communication socket
500
ERROR_SENDING_TO_SOCKET
Something went wrong. Contact the administrator if the error persistsrver is not ready yet, please try again later
Our system failed to send data through the communication socket
500
ERROR_RECEIVING_FROM_SOCKET
Something went wrong. Contact the administrator if the error persists
Our system failed to receive data from the communication socket
500
ERROR_DESERIALIZING
Something went wrong. Contact the administrator if the error persists
Our system failed to parse the output data from the privacy app
Welcome to the zkPass Developer's Guide. This document is engineered for developers, software architects, and technical leads who aim to implement Zero-Knowledge Proof (ZKP) functionalities in their applications via a scalable, cloud-based architecture. Through a Proof-As-a-Service model, zkPass offers an API-driven approach for ZKP computations, abstracting away the computational complexity and focusing on seamless integration.
zkPass is a specialized Proof-As-a-Service that enables the efficient execution of Zero-Knowledge Proofs (ZKPs) within a Trusted Execution Environment (TEE). The service exposes a set of APIs and an SDK library (zkpass-client) to facilitate the delegation of ZKP computational tasks to a cloud-based environment. This architectural choice is particularly beneficial for client devices with resource constraints, allowing for scalability without sacrificing data privacy.
The heart of zkPass is the zkPass module model. This is a privacy-preserving application which features the following characteristics:
Data Privacy zkPass uses state-of-the-art Zero Knowledge Proof (ZKP) to maintain data confidentiality. In addition, the cloud-based architecture operates within a TEE, providing an additional layer of security against the risks inherent to data centralization.
Verifiable Computation With Zero Knowledge Proof (ZKP) technology, the execution of zkPass modules becomes verifiable, ensuring the integrity and security of the code. This means that any attempt to tamper with or alter the application's code can be detected and prevented. This verifiability is crucial for maintaining trust in zkPass modules in a trustless fashion, as it ensures that the application operates as intended and that user data remains secure and confidential.
Scalable Computation Architecturally designed to serve a range of devices, from mobile endpoints to data centers.
Easy Integration The zkPass module presents high-level concepts that are easy to grasp, enabling a swift integration environment for third-party applications seeking to implement privacy-protecting features. This design ensures that developers can quickly understand and incorporate these concepts, facilitating the seamless addition of privacy measures into their applications.
While zkPass offers many advantages, it's crucial to note that the service-centric approach implies that sensitive user data will be processed on a centralized server. However, the TEE environment aims to mitigate this by adding an extra layer of security, ensuring the confidentiality and integrity of user data.
Continue to the subsequent sections for granular setup guidelines, extensive API documentation, code examples, and architectural discussions aimed to empower you to exploit the full capabilities of zkPass.
Thank you for considering zkPass for your application's ZKP requirements. We are eager to see your contributions to this evolving field!
A zkPass Proof is a token that the zkPass Service generates. It is a composite of several key components.
Zero-Knowledge Proof: This is the crux of the cryptographic proof generated by executing a specific query on user data using a Zero Knowledge Virtual Machine (ZKVM), which runs within a Trusted Execution Environment (TEE). It verifies that the query has been executed correctly while keeping the underlying data confidential.
Query Output: This results from the application running on the ZKVM. This output is intended to be shared, and the Zero-Knowledge Proof guarantees its integrity.
Metadata: This includes auxiliary information about the proof from the application's perspective. In the context of DVR, they are timestamps, the unique identifier for the Data Verification Request (DVR), and other contextual data that might be necessary for auditing or verification.
The zkPass proof is constructed in a DVR pipeline of processes that start with two main inputs: User Data and the DVR Info, as illustrated here.
The zkPass Proof object is signed by the zkPass Service into a JSON Web Signature (JWS) token to ensure its authenticity and integrity. Any tampering with the proof token can be easily detected, providing an additional layer of security.
The zkPass Proof facilitates a paradigm where the Verifier does not need direct access to the original, sensitive data. The Verifier can confirm the validity of a specific claim about the data by examining the Zero-Knowledge Proof. This is particularly powerful in scenarios that require stringent data privacy controls.
The zkPass Proof isn't just about data confidentiality; it also ensures transparency in query execution. It is an immutable record, confirming that a particular query has been executed faithfully against the user data, adhering to all specified conditions or requirements.
The zkPass Proof is a robust, secure, and flexible mechanism designed to facilitate privacy-preserving data operations. It encapsulates the cryptographic proof of a query's accurate execution, the query's output, and relevant metadata, all wrapped in a secure, authenticated package. It provides a versatile and transparent way to conduct data operations while maintaining the highest data privacy and integrity standards.
Helper functions for extracting and validating JWT payloads
▸ extractPayload
(token
: string
): DvrDataPayload
Extracts the payload from a JWT token and validates its type.
Parameters
token
string
The JWT token to extract payload from
Returns
DvrDataPayload
- The extracted payload
Throws
Error if token is invalid
Error if payload is not of type DvrData
▸ extractZkProofPayload
(token
: string
): ZkPassProof
Extracts the ZkPassProof payload from a JWT token.
Parameters
token
string
The JWT token containing zkPass proof
Returns
ZkPassProof
- The extracted zkPass proof object
Throws
Error if token is invalid
Error if payload is not of type ZkPassProof
▸ private decodeJwtPayload
(token
: string
): any
Parameters
token
string
The JWT token to decode
Returns
any
- The parsed payload from the JWT token
Throws
Error if token is invalid
▸ private isZkPassProof
(data
: any
): boolean
Parameters
data
any
The data to check
Returns
boolean
- True if data is a valid ZkPassProof
▸ private isDvrData
(data
: any
): boolean
Parameters
data
any
The data to check
Returns
boolean
- True if data is a valid DvrDataPayload
DVR defines a JSON query language that allows the Proof Verifier to check if the user has data that meets specific requirements, conditions, or constraints.
The query language is implemented by the DVR Query Engine component, which takes two inputs:
User Data This is the JSON data that is issued by the Data Issuer and is being inquired by the Proof Verifier to see if the data meets specific requirements or conditions. The data can follow any schema or structure as DVR does not set any specific format requirement on the user data.
DVR Query The query is a JSON-based script that sets the requirements or conditions for the user data. The query is expressed as a DVR scripting language and is included in the "query" field of the Data Verification Request (DVR) object. An example of the query would be “user must be either married or over 21 years of age”. The query is executed by the DVR Query Engine to produce the ZK Proof and the result of the query.
The goal of defining its own query language is to let the Proof Validator client be able to perform queries on the data using an expressive, flexible, intuitive, easy-to-use, and performant scripting language.
This section demonstrates how to use the DVR types to interact with the DVR client binary to:
Generate a DVR token.
Generate a User Data token.
Generate a zkPass proof.
Verify a zkPass proof.
A collection of utility functions for converting between PublicKey and KeysetEndpoint
▸ convertToPublicKeyOption
(item
: PublicKey
|
KeysetEndpoint
): PublicKeyOption
Converts a PublicKey or KeysetEndpoint object into a PublicKeyOption structure.
Parameters
item
|
The item to convert
Returns
PublicKeyOption
- A structured object containing the tag and value of the public key option
Throws
Error if input is neither a valid PublicKey nor KeysetEndpoint
Client class for the DVR module, accessing the DVR module functions
new DvrModuleClient(config
): DvrModuleClient
Constructs a new instance of the DvrModuleClient.
Parameters
Returns
private
credentials: PrivacyAppCredentialsStruct
The credentials structure containing authentication details for the Privacy App Client, including base URL, API key, and secret API key.
The loaded library instance containing the foreign function interface (FFI) definitions for DVR module functions.
private
PACKAGE_NAME: "@zkpass/dvr-client-ts"
: string
The NPM package name for the DVR client TypeScript library.
private
LIBRARY_NAME: "libdvr_client.so"
: string
The name of the shared library file that contains the DVR client implementation.
▸ private
loadLibrary(): Object
Loads the specified library and defines the foreign function interface (FFI) for the DVR module.
Returns
Object
- An object representing the loaded library with the defined FFI functions
The following functions are defined in the FFI:
dvr_generate_user_data_token
dvr_generate_query_token
dvr_generate_zkpass_proof
dvr_verify_zkpass_proof
▸ callDvrGenerateUserDataToken(signingKey
, stringifiedUserData
, verifyingKeyOptionParam
): string
Generates a user data JWS token using the provided signing key, user data, and public key option.
Parameters
Returns
string
- The generated user data token, or throws an error if generation fails
▸ callDvrGenerateQueryToken(signingKey
, dvrData
): string
Generates a DVR query JWS token using the provided signing key and DVR data.
Parameters
Returns
string
- The generated DVR query token, or throws an error if generation fails
▸ callDvrGenerateZkPassProof(stringifiedUserDataTokens
, dvrtoken
): string
Parameters
Returns
string
- The generated zkPass proof, or throws an error if generation fails
▸ callDvrVerifyZkPassProof(zkvm
, zkPassProofToken
, expectedMetaData
): VerifyZkPassProofResult
Parameters
Returns
VerifyZkPassProofResult
- The output committed into the zkPass proof, and the zkPass proof data
private
library: ReturnType
<typeof >
config
PrivacyAppClientConfig
Configuration object
config.baseUrl
string
The base URL for the API
config.apiKey
string
The API key for authentication
config.secretApiKey
string
The secret API key for authentication
signingKey
string
The key used to sign the user data token
stringifiedUserData
string
The user data in stringified format
verifyingKeyOptionParam
PublicKeyOrKeysetEndpoint
The associated key to verify the user data token
signingKey
string
The key used to sign the DVR query
dvrData
DvrData
The data required for generating the DVR query token
stringifiedUserDataTokens
string
Stringified representation of multiple user data tokens using tag as the key
dvrtoken
string
The DVR token to be used in the proof generation
zkvm
string
The zkVM identifier
zkPassProofToken
string
The zkPass proof token to be verified
expectedMetaData
ExpectedDvrMetadata
The expected metadata for the DVR verification
A collection of enums used in the DVR module
▸ PublicKeyOptionType: Enum
Enum for public key option types.
PublicKey
0
Indicates a public key option
KeysetEndpoint
1
Indicates a keyset endpoint option
Follow the instructions below to build the Rust doc yourself from the source code.
In this documentation, we refer to the project directory as /home/builder/zkpass-sdk
. This path is used as an example that represents the root directory of the clonedzkpass-sdk
repository on your local system. When following these instructions, please substitute /home/builder/zkpass-sdk
with the actual path to your project's root directory.
To generate the zkpass-client lib documentation locally, do the following:
After completing these steps, the documentation will automatically open on a browser or you can find the generated documentation in the ~/rust/target/doc
directory within the crate's source code directory.
We are using elliptic curve cryptography (ECC) for our encryption. The key pair should be generated using P-256
curve. Ensure the generated key pair is in PEM
format.
The public key should be encoded in SPKI
format, and the private key should be encoded in PKCS#8
format.
PEM
format
SPKI
encoding
PEM
format
PKCS#8
encoding
Here's the example of generating key pair in Typescript.
After this section you should have a key pair consisting of :
publicKeyJWKS
privateKey
Ideally, the issuer & verifier should have different key pairs.
Make sure you have both them before proceeding to the next section.
Here's the example for publicKeyJWKS
and privateKey
.
Data Verification Request
Data Verification Request (DVR) is the main application in the zkPass framework. It contains a query that serves as the criteria against which user data is verified. Created by the Proof Verifier, DVR Query works as conditional statements applied to relevant fields in the user data. These queries enable the Proof Verifier to validate user information without having the Data Holder expose the user's sensitive content.
For a complete definition of the DVR, please follow this link.