This section provides a high-level overview of how zkPass works, designed for clarity and ease of understanding. Whether you're a developer, a business owner, or just someone curious about zero-knowledge technology, you'll find this guide an essential starting point.

The Essence of zkPass

zkPass serves as a bridge between devices with limited computational capabilities and the robust world of ZKPs. By offloading the heavy lifting of ZKP computations to a secure server, zkPass enables devices of all kinds to participate in privacy-preserving data verification without exposing the actual data. It's a service that maintains confidentiality while allowing certain aspects of the data to be verified, all without the verifier ever seeing the data itself.

Participants in the zkPass System

Three roles are central to the zkPass ecosystem: the Data Issuer, the Data Holder, and the Proof Verifier. The Data Issuer issues the data, the Data Holder is the custodian of their own data, and the Proof Verifier sets conditions on the data and verifies its integrity. Each plays a pivotal role in the delicate dance of data privacy and verification.

The zkPass Workflow

The diagram above illustrates the typical holder-centric zkPass workflow. The workflow is centered around the user, as explained below:

1. It starts with the Data Holder requesting a Data Verification Request (DVR) from the Proof Verifier. The DVR contains the query about the user data. The Proof Verifier signs the DVR to ensure authenticity and returns it to the Data Holder.

2. The Data Holder then retrieves the user data from the Data Issuer. This is the user data that is referenced by the DVR query. The Data Issuer also signs user data to ensure authenticity and returns it to the Data Holder.

3. With the DVR and the user data in hand, the Data Holder submits these items to the zkPass Service, initiating a RESTful API call request to generate a cryptographic zkPass Proof.

4. zkPass Service receives the API request and generates the zkPass Proof. It returns the proof to the Data Holder

5. The proof is then sent by the Data Holder to the Proof Verifier for verification.

6. The Proof Verifier verifies the proof and receives the query result which determines if the Data Holder has met the conditions specified in the query.

A Secure and Transparent Process

Throughout the entire process, the integrity and confidentiality of data are rigorously maintained. By employing robust encryption and digital signatures, zkPass ensures that the user data and DVR maintain their authenticity and privacy, especially during transit. This unwavering dedication to security is further reinforced by the use of Zero-Knowledge Proofs (ZKP) and the Trusted Execution Environment (TEE). In the TEE, the ZKP computations are carried out, guaranteeing that both the data and the queries performed on it remain secure, confidential, and verifiable.

For detailed insights on integrating your applications with the zkPass Service, consult the Developer's Guide. This comprehensive resource provides in-depth coverage of utilizing the SDK client library and outlines the necessary requirements for your application.

zkPass 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 zkPass in various settings.

Holder-Centric Workflow

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.

Verifier-Centric Workflow

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, common in business-to-business interactions.

zkPass'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, zkPass 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 zkPass – 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 zkPass, ensuring a seamless, secure, and user-friendly experience in their data verification processes.

To address the limitations of the client-based proof system architecture, we introduce zkPass Service, 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.

It should be noted that this server-centric approach has its downside. Most notably, 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, we run the zkPass server within a Trusted Execution Environment (TEE). This secure and isolated environment aims to provide an additional layer of protection, safeguarding the privacy of user's data while allowing for the efficient execution of ZKP computations. In other words, zkPass can still protect data confidentiality through the trusted privacy model.

zkPass Service is a Proof-As-a-Service that facilitates the execution of Zero-Knowledge Proofs (ZKPs) within a Trusted Execution Environment (TEE). By merely initiating a service request through the SDK client library, you can delegate heavy ZKP computational tasks to the server. This is ideal for devices with limited computational resources, providing an efficient and scalable solution without compromising data privacy.

Highlights

• Trusted Data Privacy and Integrity zkPass ensures that the user's data remains confidential and integral throughout the process. While necessitating a degree of trust, the cloud architecture mitigates the risks associated with centralization by running within a TEE. This secure environment safeguards your data privacy while efficiently executing ZKP computations.

• Transparent and Verifiable Query Execution zkPass Service doesn’t just run your queries; it also crafts a cryptographic proof that verifies the query was executed exactly as intended, ensuring the integrity and accuracy of the execution without any third-party verification. As a user, you can trust the zkPass Service to run your scripts faithfully, offering a seamless, trustless verification process where the service itself guarantees the truthfulness of the execution and its results, thus serving as a foundation of "trustless truth as a service".

• Scalable Computation Designed to accommodate various devices with varying computational capabilities. This adaptability is what sets zkPass Query apart, as it breaks away from the limitations of conventional client-side ZKP solutions that are typically restricted to a narrow set of proof functions. With zkPass Query, you can tailor your logic to meet diverse data requirements and conditions.

• Flexible Query Language The JSON-based query language enables customization to suit any user data schema. In addition, the zkPass service simplifies the querying process with its zkPass Query, a user-friendly, JSON-based query language designed for versatility and ease of use. When you utilize this language to construct queries, the Zero-Knowledge Virtual Machine (ZKVM) steps in to execute these queries.

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.

Key Benefits of On-Premise Hosting

• 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.

Considerations for On-Premise Hosting

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.

Beyond merely transferring the computational load of proof generation from the client device to the server, zkPass Service incorporates a robust JSON-based query language (zkPass 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.zkPass Service inherits the two pivotal features from its client-side predecessor, enhancing them within its server-centric architecture:

1. Trusted Data Privacy By generating a cryptographic proof, zkPass ensures that the underlying data remains confidential. The 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, zkPass Service 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.

2. 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, zkPass 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, zkPass Service strives 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 query language, adaptable to any user data schema, offering users even greater flexibility.​​​

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.

Key Features of Private Cloud Hosting

• 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.

Security Considerations in Private Cloud

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.

Secure and Versatile Folder

The User Data can be envisioned as a digital personal folder, where you securely store confidential information like driver's licenses, birth certificates, diplomas, and others. This system represents a flexible and secure way to manage a variety of data, inspired by W3C's Verifiable Credentials but extending beyond to accommodate diverse document types, irrespective of their format. Unlike the complex W3C format, we are using the ubiquitous and versatile JSON Web Token as the folder. Thus the User Data is essentially formatted as a JSON Web Token.

Authenticity and Trust

The items stored within your User Data, akin to the confidential information in your personal folder in this analogy, generally originate from external entities referred to as Data Issuers. These are typically authorities or institutions issuing official documents. To ensure the authenticity of the document added to your folder, the Data Issuer stamps it, similar to placing an official seal on the physical folder. This digital stamping on the folder is effectively implemented using JSON Web Signature (JWS), serving as a digital seal that verifies the genuineness and trustworthiness of your data.

Schema-Agnostic Design and JSON Format

zkPass's 'schema-agnostic' design enables the storage of various types of data without the need to follow a specific layout or format. Whether it's an official certificate or an informal note, as long as it’s in the universally understandable JSON format, it can be included in your folder. This approach ensures that your personal folder is not only flexible but also coherent and user-friendly.

Confidential Verification and Sharing

When sharing or verifying your personal document contained in the User Data, confidentiality and security are paramount. The zkPass Query Host facilitates the verification of your document without compromising their integrity, similar to a secure viewing room where confidentiality is maintained at all times. This setup offers you a digital personal folder that is organized, accessible, and fortified with robust security, ensuring peace of mind in managing sensitive data.

For a more detailed explanation of the User Data, please refer to the Developer's Guide.

Safeguarding User Data Privacy

In today's digital landscape, data privacy is paramount. zkPass stands as a bulwark in the protection of user data, ensuring that sensitive information remains confidential and secure. By utilizing Zero-Knowledge Proofs (ZKPs) within a Trusted Execution Environment (TEE), zkPass enables the verification of data without ever exposing the actual content. Whether you're a Data Holder seeking to keep personal credentials private or a Data Issuer looking to protect issued data, zkPass serves as a vigilant protector of information. The Data Holder can confidently share proof of their information's validity without revealing the information itself, turning the tide in how we approach privacy and data sharing in a security-conscious world.

Mitigating Ransomware Risks

zkPass plays a critical role in the fight against ransomware by fundamentally changing the data storage paradigm. Traditional security measures often focus on fortifying defenses around data repositories, but zkPass minimizes the need to store sensitive data at all. Instead, it processes and verifies only Zero Knowledge Proofs, ensuring that the actual data does not reside on potentially vulnerable servers. This approach deprives ransomware attackers of the valuable data they target, thereby reducing the incentive for attacks and the impact they can have on an organization. In the event of a breach, the attackers find themselves with a Zero Knowledge Proof, which is useless to them because the proof reveals no confidential data at all.

Additionally, zkPass enhances an organization's resilience to ransomware by maintaining the integrity of operations even during an attack. The verification of data does not rely on the data being accessible on the server, but rather on the Zero-Knowledge Proofs that the system processes, essential verifications, and operations can continue uninterrupted. This capability is crucial for maintaining business continuity and can be particularly advantageous for critical infrastructure sectors, where the consequences of downtime or data compromise can be far-reaching.

Enabling Transparent and Verifiable Computing

Transparency and verifiability are the cornerstones of trust in digital systems. zkPass champions this cause by ensuring that every computation, every query, and every verification is transparent and cryptographically verifiable. With zkPass, Proof Verifiers can set precise conditions for user data, which are then executed and verified without any intermediary. The result is a system where trust is not assumed but established through mathematical proofs. This level of transparency is not just a feature; it's a foundational element that provides peace of mind and fosters trust between all parties involved.

Facilitating Regulatory Compliance

In an environment where data protection laws like the GDPR and CCPA dictate stringent data management protocols, zkPass provides a streamlined approach to regulatory compliance. Its framework minimizes the amount of personal data retained by processing and verifying data through cryptographic proofs rather than the data itself. This approach inherently supports privacy-by-design and default principles, essential tenets of modern data protection laws, which can significantly simplify an organization's compliance efforts.

zkPass's method of handling data aligns with the increasing global emphasis on user privacy. By enabling the verification of private information without storing or exposing the data, organizations can demonstrate due diligence in protecting user information. This is particularly crucial for sectors handling sensitive data, where compliance with data protection standards is not just regulatory but also critical to maintaining consumer trust.

Streamlining Verification Processes

zkPass revolutionizes the verification process by providing a means to authenticate data quickly and securely, leveraging the robustness of Zero-Knowledge Proofs. This technology enables the validation of credentials or conditions without revealing any underlying personal information, streamlining operations that traditionally required extensive checks and balances. For industries that rely on identity verification, such as banking or online services, zkPass can dramatically reduce the time and resources spent on these procedures, allowing for near-instantaneous confirmation of data accuracy. This efficiency gain not only boosts productivity but also enhances the user experience, providing a competitive edge in service delivery.

Moreover, by automating the verification process, zkPass eliminates human error and biases that often accompany manual verification. The use of ZKPs ensures that the verification process is consistent and reliable, fostering a high-trust environment. This automation can be particularly transformative for sectors that manage a high volume of verification requests, such as the healthcare sector for patient records or the education sector for academic credentials, making zkPass an invaluable tool in an increasingly data-driven world.

Reducing Data Storage Costs

With zkPass, there is less need to store large amounts of sensitive data, which can reduce the costs associated with data storage solutions. This can be particularly advantageous for small to medium-sized enterprises (SMEs) that may have limited budgets for IT infrastructure.

Enabling Secure Digital Transformations

For organizations looking to digitally transform their operations, zkPass provides a secure foundation. By ensuring data privacy and integrity, organizations can confidently shift towards more digital and cloud-based environments.

Empowering User Sovereignty

zkPass empowers users with control over their data. It shifts the balance of power from institutions to individuals, as users can prove their data’s integrity without revealing the actual information, thereby maintaining sovereignty over their personal information.

Building Trust in Digital Ecosystems

zkPass can be instrumental in building trust within digital ecosystems. In sectors like finance, healthcare, and education, where data sensitivity is paramount, zkPass provides a trust layer that reassures all parties of the data's integrity without compromising privacy.

Enhancing User Experience

By reducing the friction associated with data sharing and verification, zkPass can greatly enhance the user experience. Users can engage in transactions or processes that require proof of certain credentials without the hassle of exposing sensitive data, leading to smoother and more user-friendly experiences.

Promoting Innovation

zkPass opens up new possibilities for innovation in various industries by providing a secure way to handle sensitive data. Developers and businesses can build novel applications and services that leverage the power of ZKPs, knowing that user privacy and data security are well-managed.

Data Verification Request (DVR) is like a question that the Proof Verifier asks the Data Holder or the user. This "question" is usually about some specific information a user has stored on the user data. For example, the Proof Verifier might ask, "Is this user over 21 years old?" or "Is this user married?"

The concept of DVR is pivotal in grasping the zkPass workflow. Essentially, the flow of zkPass kicks off with the Proof Verifier creating a DVR.

Structure of a DVR

Each DVR has two main parts:

1. Metadata (The Envelope of the DVR) Think of the metadata as the envelope that holds the DVR. Some of the core metadata are:

   • 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 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.

2. 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.

[
  {
    assign: {
      loan_application: {
        and: [
          { "==": [{ dvar: "bcaDocID" }, "DOC897923CP"] },
          { "~==": [{ dvar: "personalInfo.firstName" }, "Ramana"] },
          { "~==": [{ dvar: "personalInfo.lastName" }, "Maharshi"] },
          {
            "~==": [{ dvar: "personalInfo.driverLicenseNumber" }, "DL77108108"],
          },
          {
            ">=": [{ dvar: "financialInfo.creditRatings.pefindo" }, 650],
          },
          {
            ">=": [
              { dvar: "financialInfo.accounts.savings.balance" },
              55000000,
            ],
          },
        ],
      },
    },
  },
  { output: { result: { lvar: "loan_application" } } },
]

In this example query, variable "personalInfo.firstName" references the JSON element "firstName" whose parent element is "personalInfo". This element exists in the user data.

For a more in-depth explanation of the DVR, please refer to the Developer's Guide.

Imagine zkPass Proof as a special kind of digital token created by the zkPass Service. It's like a detailed report that contains several important parts, all designed to keep your data safe and verify important information without revealing any secrets.

The Core Elements of zkPass Proof

• Zero-Knowledge Proof This is the heart of the proof. It's a clever piece of the ZKP technology that checks if certain things are true about your data without actually seeing the data itself. It works in a super secure space called the Trusted Execution Environment, ensuring everything is done correctly and privately.

• Query Result After the zkPass Service checks your data, it gives a result. This is what we call the Query Output. It's safe to share this part because the Zero-Knowledge Proof makes sure it’s accurate and hasn't been tampered with.

• DVR Metadata Think of this as the detailed label on your report. It includes the time the proof was made, a unique ID for your Data Verification Request, and other useful information that helps in checking and verifying the integrity of the DVR information used by the zkPass Service when generating the zkPass Proof. The metadata validation is performed by the Proof Verifier.

Safety and Trustworthiness

The entire zkPass Proof is sealed by the zkPass Service, kind of like putting it in a tamper-proof envelope. This ensures that the proof is genuine and hasn’t been altered, adding an extra layer of security.

Protecting Your Data Privacy

What’s really great about zkPass Proof is that it lets someone verify information about your data without ever accessing the actual data. This means your sensitive information stays private, but you can still prove certain things about it. It’s a powerful tool, especially when you need to keep your data under strict privacy control.

Clear and Honest Query Checks

zkPass Proof isn't just about keeping things confidential. It also makes sure that the queries or checks done on your data are transparent and honest. The proof acts like an unchangeable record, confirming that the query was done exactly as it should be, following all the rules and conditions set out.

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.

Advantages of Public Cloud Hosting

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.

Enhanced Security in the Cloud

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.

Now, the zkPass Query Host is where the real magic happens. Picture it as a vault, nested within another vault, sitting in a Trusted Execution Environment (TEE). This is the Fort Knox of zkPass, shielded and isolated from the outside world. Communication with the outside, even with the REST API Web Service, happens only through a secure, specialized channel.

Inside this vault is a specialized engine, a component known by the intriguing name of <zkvm>-zkpass-query, where <zkvm> denotes the specific ZKVM (Zero Knowledge Virtual Machine) engine in use. Given the user data and DVR inputs, this engine crafts something quite valuable—a secure proof, the zkPass Proof.

So, when you make that initial RESTful call to generate_zkpass_proof, what you get back is this zkPass Proof, fresh from the secure confines of the zkPass Query Host's vault. And there you have it, the tale of how zkPass takes your user data and DVR on a journey from a humble reception desk to a high-security vault, only to return to you a valuable proof. Armed with this understanding, you're now ready to make the most of zkPass in your own engineering endeavors.

Imagine your personal data is like a precious gemstone, and you want to keep it safe while also showing it off under certain conditions. Welcome to the world of zkPass, a service designed to protect your "gemstone" like a high-security vault while still letting you make use of it.

At the heart of zkPass is something called a Trusted Execution Environment, or TEE for short. Think of TEE as an ultra-secure vault room where special processes can take place without anyone else peeking in. It's like a VIP lounge for data, where only the most trusted operations are allowed to enter.

In this VIP lounge, zkPass performs two main tasks on your data. First, it verifies that the data is genuinely yours, kind of like a bouncer checking your ID at the door. This is done through digital signature verification. Second, it performs some fancy math—called Zero-Knowledge Proof calculations—to make sure that your data can be used without revealing any sensitive information.

You might wonder, "Why not just keep the data encrypted all the time?" Well, some operations need to look at the data in its raw form, just like a jeweler needs to take the gemstone out of the safe to inspect it or reshape it. Also, techniques like Homomorphic Encryption, which can do some calculations on encrypted data, just aren't powerful enough for what zkPass needs to do.

So, what it comes down to is trust. You have to trust that zkPass's VIP lounge is as secure as it claims to be, and that it's been set up correctly to protect your precious gemstone—your data. In other words, the zkPass service is built on a Trusted Model. You're trusting that everything behind the scenes is working to keep your data both useful and secure.

And there you have it! That's how zkPass works to keep your data safe yet functional, all wrapped up in a layer of trust.

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.

In the cloud, far from the complexities of your local machine, lies the zkPass Service. This service is like a well-orchestrated duo, composed of the RESTful API Web Service and the zkPass Query Host. Each has a role to play in the secure creation of what's known as a zkPass Proof.

Imagine you have a digital helper that can securely verify important information for you without ever needing to see the details – that's what the RESTful API web service component of zkPass Service is all about. It's like a trusted messenger that carries sealed envelopes (your and the ) to a secure vault (zkPass Query Host) and brings back a stamp of approval, all without peeking inside.

Here's how it works for you: Whenever you want to check if certain information is true or meets specific criteria, you don't need to handle the sensitive details yourself. Instead, you send a request to our web service RESTful API called generate_zkpass_proof. This request is like a special envelope containing a question you want to be answered, based on the data you're curious about.

The zkPass Query Host, the digital vault, then works its magic. It carefully examines your request, verifies the information against the criteria you've set, and sends back proof – a kind of digital stamp – that confirms whether the information meets your requirements. The best part? This all happens without the web service ever actually seeing or storing the sensitive data you're inquiring about.

zkPass offers a robust, service-centric approach to Zero-Knowledge Proof (ZKP) computations, designed to offload the computational burden from client devices to the cloud.

This documentation provides a comprehensive guide to integrating and utilizing the zkPass service in your applications. Read on to understand its key features, architecture, and capabilities.

Depending on the application, the client of zkPass can take one of these roles:

1. Data Issuer The entity responsible for issuing the original data that requires protection.

2. Data Holder (User) The individual whose confidential data is being protected.

3. Proof Verifier The Proof Verifier is the client that is responsible for setting conditions and requirements on user data using the zkPass Query language, which are then encapsulated in a Data Verification Request (DVR). The concept of a Proof Verifier is similar to that of the DID's Data Verifier. Unlike a generic DID's Data Verifier, the Proof Verifier specifically validates zero-knowledge proofs generated from the query execution to ensure the user data meets the specified conditions. The term "Proof Verifier" is therefore used here to emphasize its specialized capability for verifying data through zkPass Proofs.

This multi-faceted trust model allows the proper flow of data and communications among the zkPass stakeholder clients and ensures that the user’s confidential information remains protected and secure.

Central to the ecosystem is the zkPass service, which provides the generateProof RESTful API. This method takes the user data token and the dvr token, both of which are signed and encrypted JWT content. This is a nested JWT message in which the inner token is the signed JWT (JWS), and the outer token is the encrypted JWT (JWE). The caller of the API first signs the inner token with its signing private key and then encrypts the outer token with the zkPass service’s public key. Upon receiving the user data and dvr tokens, zkPass service first decrypts the outer token with its private key and then verifies the signature of the inner token with the public of the caller. Since the public key of the zkPass must be known to the caller of the API, zkService exposes the JWKS endpoint, which contains the URL and the key name for its public key.

Imagine you're playing a high-stakes poker game, and you want to make sure that the deck isn't stacked against you. In the world of zkPass, the role of an impartial dealer is played by something called a Zero Knowledge Virtual Machine, or ZKVM for short. This special "dealer" ensures that the game—here, the process of creating a secure proof—is completely fair and above board.

The beauty of this ZKVM dealer is that it operates on what's known as the Trustless Model. This means you don't have to take anyone's word that the game is fair; you can see it for yourself. The dealer's actions are so transparent that you, as the Verifier in this poker analogy, can confidently confirm that the proof you're given is valid. You don't have to trust the zkPass service or any other third party; the integrity of the game stands up to scrutiny all on its own.

So, with zkPass and its ZKVM engine, you're not just hoping for a fair game; you're guaranteed one. And that assurance comes not from trust, but from verifiable, transparent actions.

Imagine you're sending two very important sealed letters through a courier service: one is a signed credential and the other is a signed DVR. You want to be absolutely certain that no one has tampered with these letters by the time they reach their destination. Welcome to zkPass, a service designed to act like that ultra-secure courier for your digital "letters."

In the world of zkPass, these letters go through a process similar to a high-tech, digital wax seal check—something called DSA verification. This ensures that your letters are exactly as you sent them, untampered and intact. Now, this seal check can happen in one of two rooms in zkPass's secure facility.

The Trusted Room

In the first room, the seal check happens separately from the main operation, which creates something known as a Zero-Knowledge Proof (ZKP). Think of this as zkPass first unsealing and reading your letters in a secure room, verifying they are legit, and then moving on to another task. This is what's called the Trusted Data Integrity model.

The All-in-One Room

In the second room, everything happens at once. The letters are unsealed, verified, and the ZKP is generated, all in one go. This is known as the Trustless Data Integrity model. It's like having a super-efficient clerk who can multitask like a pro.

Now, you might wonder, "Why not always use the All-in-One Room?" Well, the issue is that the seal-checking process is quite demanding. It's like asking the clerk to juggle too many tasks at once, and right now, the zkPass system can't handle that level of multitasking efficiently.

So, for the time being, zkPass recommends using the Trusted Room approach. It's not that it's the best option, but it's the most doable one right now, and it's still pretty secure. But keep an eye out! As zkPass gets better at juggling tasks, we might soon be able to use the All-in-One Room for even greater security.

In a nutshell, zkPass is currently taking a practical approach to keeping your data untampered, but it's always looking to step up its game.

The concepts of User Data, Data Verification Request (DVR), and zkPass Proof are central to understanding how zkPass works. The diagram below illustrates the relationship among the three:

The user data and the DVR, which contains the query, are inputs to the zkPass Service, which are needed to create the zkPass proof object.

Fortunately, Namaste Tech is very committed to protecting the privacy of its employees. It has developed the “My Namaste” App based on the zkPass Proof-as-a-Service architecture, which allows third-party entities to examine users’ information without compromising confidential information.

Taking the Proof Verifier role, Namaste Tech needs to create a DVR to query the blood test results of the incoming new employee.

Query

Namaste Tech defines the “Employee Onboarding” DVR Query for user Jane Doe as follows:

[
  {
    "assign": {
      "blood_test_status": {
        "and": [
          {
            "==": [{ "dvar": "lab.ID" }, "QH801874"]
          },
          {
            "==": [{ "dvar": "testID" }, "SCREEN-7083-12345"]
          },
          {
            "~==": [{ "dvar": "subject.firstName" }, "jane"]
          },
          {
            "~==": [{ "dvar": "subject.lastName" }, "doe"]
          },
          {
            "==": [{ "dvar": "subject.dateOfBirth" }, "1985-12-12"]
          },
          {
            "==": [{ "dvar": "measuredPanelsNgML.amphetamines" }, 0]
          },
          {
            "<=": [{ "dvar": "measuredPanelsNgML.cocaine" }, 10]
          }
        ]
      }
    }
  },
  { "output": { "title": "Blood Test Result" } },
  { "output": { "result": { "lvar": "blood_test_status" } } },
  { "output": { "name": { "dvar": "subject.firstName" } } }
]

In the realm of zkPass, think of trust as a multi-layered security system. Each layer—data privacy, data integrity, and computation integrity—has its own unique set of locks and keys, or "trust models," that govern how secure and reliable it is. Just like a well-guarded fortress, zkPass uses different strategies for each layer to ensure that your data is as safe as possible.

Here is the summary table of the trust models supported by zkPass:

The blood test is necessary as Namaste Tech has a strict hiring policy prohibiting people with a history of Cocaine and Amphetamine use from entering its workforce. QualityHealth Labs clinic administers the blood test and issues the blood test result.

Criteria for Drug Test Eligibility

For successful completion of the onboarding process, prospective employees are required to satisfy the following conditions during the initial screening stage:

• Cocaine levels must be below 10 ng/ml

• Amphetamine levels must be zero

Meeting these criteria is crucial for securing employment.

Objectives for the Employee Onboarding System

Namaste Tech aims to build a system that can onboard the employees with the following objectives:

• Privacy Protection for the Employees of Namaste Tech To ensure the privacy of customer data, QualityHealth Lab Clinic will not directly transfer any sensitive information to Namaste Tech. Instead, a proof-of-eligibility token, confirming that the applicant meets the predefined criteria, will be sent to Namaste Tech. This strategy minimizes the risk of data exposure while preserving the integrity of the onboarding process.

• Verifiable Drug Use Assessment Maintaining transparency in the employee onboarding workflow is essential. The assessment outcome must be based solely on a quantitative analysis of the applicant's blood test results. Namaste Tech mandates that its query executes without modification, maintaining its original logic. Furthermore, the query must be applied to the correct blood test results, and the test result must belong to the applicant being evaluated.

The purpose of this case study is to present an all-encompassing plan for seamlessly integrating all stakeholders with the zkPass Service in order to build an employee onboarding system that respects the employees' confidential information and enforces a transparent onboarding process. The following sections will delve into the details of the system's technical framework, the nuances of data movement, and the specific integration plans tailored for each participating entity.

The heart of zkPass is the privacy application model. zkPass Module is an application designed to enhance the privacy and security of user data. zkPass Modules leverage advanced cryptographic techniques, such as Zero-Knowledge Proofs (ZKP), to ensure that user data remains private while still being verifiable. This means that specific properties of the data can be confirmed without revealing the actual data itself.

zkPass Module operates within the zkPass ecosystem and supports one or both of the following features:

1. Protecting the privacy of user data

2. Operating in a secure environment, Trusted Execution Environment (TEE)

3. Providing verifiable results

zkPass Modules operate as pluggable modules within the zkPass system. These modules are loaded by the zkPass Host and run within a Trusted Execution Environment (TEE), ensuring that all operations are secure and isolated from potential threats.

Each implementation of a zkPass module consists of two executable modules: Service module and Client module. The service module is the component of the zkPass module that communicates with the zkPass Service. The client module links with the third-party application that needs to utilize the functionalities provided by the zkPass module.

The design for incorporating multiple zkPass modules within the zkPass ecosystem should adhere to the following three architectural guiding principles:

1. Modular App Design: zkPass Modules should be architected as autonomous, encapsulated modules with clearly defined boundaries.

2. Pluggable App Module: Integrating new applications ideally should not necessitate rebuilding or recompilation of the core zkPass Service codebase.

3. Versatile Polymorphic Interfaces: zkPass should implement robust and concise polymorphic interfaces that control the interactions between zkPass modules and the core zkPass Service.

For a more in-depth explanation of the zkPass Module, please refer to the .

QualityHealth Labs, which takes the client role of the Data Issuer, defines and issues the Blood Test Result user data, which is shown here in two different formats.

{
  "testID": "SCREEN-7083-12345",
  "testName": "QualityHealth Comprehensive Screen",
  "testDate": "2023-08-27T14:00:00Z",
  "lab": {
    "name": "QualityHealth Labs",
    "ID": "QH801874",
    "address": "1234 Elm St, Oakland, USA"
  },
  "subject": {
    "firstName": "Jane",
    "_firstName_zkpass_public_": true,
    "lastName":  "Doe",
    "dateOfBirth": "1985-12-12",
    "bloodType": "A+",
    "DNAInfo": {
      "markers": {
        "APOE": [
          "E3",
          "E3"
        ],
        "BRCA1": "Normal",
        "MTHFR": [
          "C677T",
          "A1298C"
        ]
      },
      "haplogroups": {
        "paternal": "R1b1",
        "maternal": "H1a1"
      }
    },
    "contact": {
      "email": "jane.doe@gmail.com",
      "phone": "650-555-1234"
    },
    "address": {
      "street": "789 Oak Street",
      "city": "San Jose",
      "state": "CA",
      "zip": "95134"
    }
  },
  "measuredPanelsNgML": {
    "amphetamines": 0,
    "cocaine": 8,
    "opiates": 102,
    "benzodiazepines": 0
  }
}

As indicated above, the blood test result actually contains several sensitive information on the patient, such as the blood type, DNA information, home address, and contact information.

However, Namaste Tech only wants to know if the user has no history of Amphetamine and Cocaine use. Sending the entire blood test to Namaste Tech is not only unnecessary but also reveals sensitive information about the user, which over time can leak out of Namaste Tech’s database, thus compromising the privacy of the user.

In this use case, BCA Bank keeps a "BCA Customer Profile" user data for each account holder, encompassing a variety of essential attributes such as driver's license particulars, current account balance, credit scores, and other relevant financial data.

Take, for example, Ramana Maharshi, who is applying for a car loan via BCA Finance. He is a multi-account holder with BCA Bank, and his customer profile is structured in the following manner:

{
  "bcaDocID": "DOC897923CP",
  "bcaDocName": "BCA Customer Profile",
  "customerID": "BCA123756108",
  "personalInfo": {
    "firstName": "Ramana",
    "_firstName_zkpass_public_": true,
    "lastName": "Maharshi",
    "dateOfBirth": "04/12/2003",
    "driverLicenseNumber": "DL77108108"
  },
  "financialInfo": {
    "averageMonthlyBalance": 200000000,
    "creditRatings": {
      "pefindo": 710,
      "CreditKarma": 755,
      "_CreditKarma_zkpass_public_": true,
      "EquiInfo": 695
    },
    "accounts": {
      "checking": {
        "accountNumber": "CHK1238569",
        "balance": 89000000
      },
      "savings": {
        "accountNumber": "SAV1231770",
        "balance": 380000000
      }
    }
  },
  "contactInfo": {
    "email": "Ramana.Maharshi@karma.org",
    "_email_zkpass_public_": true,
    "phone": "+62-856-685-0108",
    "address": {
      "street": "1000 Komodo Street",
      "city": "Jakarta",
      "zip": 12880,
      "_zip_zkpass_public_": true
    }
  }
}

As demonstrated by the above BCA Customer Profile, the user data contains sufficient information needed for the loan screening criteria set forth by BCA Finance. However, the profile also contains extraneous sensitive attributes that hold no relevance for BCA Finance's screening assessment. Transmitting the full profile to BCA Finance would not only result in superfluous data transfer but also introduce considerable risk to customer privacy. Once stored in BCA Finance's server database, such data becomes susceptible to a myriad of security vulnerabilities, ranging from advanced persistent threats (APTs) to unauthorized data access and insider attacks. This escalates the probability of data exfiltration events.

For seamless integration with the zkPass framework, every key stakeholder should follow the SDK integration guidelines. Within the scope of the employee onboarding scenario, there are three main parties engaged, as elaborated below.

• QualityHealth Labs (Data Issuer) The lab takes the Data Issuer role as defined in the zkPass SDK. The lab defines user data as the blood test result with the above JSON content. The zkPass SDK supports any format of the user data. Therefore, the above definition of the “Blood Test Result” user data can work with the zkPass Service.

• My Namaste App (Data Holder) This is the mobile app used by the new employee of Namaste Tech required to take a blood test. The mobile app takes the role of the Data Holder on behalf of the user. The app securely retrieves the blood test result from the clinic and the "Employee Onboarding" DVR from Namaste Tech. It then talks to the zkPass Service to create the zkPass proof.

• Namaste Tech (Proof Verifier) This is the Proof Verifier role defined in the zkPass SDK. Namaste Tech defines the “Drug Screening DVR”, which contains the query to be executed on the blood test data. Namaste Tech is interested in receiving the zkPass proof to determine if the user has passed the drug screening test.

The following diagrams illustrate interactions among the three zkPass clients.

Interaction Flow in zkPass Clients: A Six-Step Process

The following section outlines the six key steps involved in the interaction between zkPass clients. Each step corresponds to the numbered arrow in the diagram and is elaborated here for clarity:

Step 1: Collecting the "Employee Onboarding" token

Jane Doe starts the "My Namaste" application to retrieve the "Employee Onboarding" token from Namaste Tech. This token is essentially a Data Verification Request (DVR) for "Employee Onboarding," which has been cryptographically signed by Namaste Tech into a JSON Web Signature (JWS) token.

Step 2: Acquiring the "Blood Test Result" token

The "My Namaste" application further fetches a "Blood Test Result" token from QualityHealth Lab. Similar to the previous step, this token represents the "Blood Test Result" user data and is signed into a JWS token by QualityHealth Lab.

Step 3: Calling the zkPass Service REST API

The "My Namaste" application invokes the generate_zkpass_proof REST API provided by zkPass Service with the retrieved "Employee Onboarding" token and the "Blood Test Result" token as the input parameters. This API call is made to generate a zkPass proof based on the query specified in the "Employee Onboarding" DVR, which is executed against the "Blood Test Result" data.

Upon receiving the API request, the zkPass Service processes the call, generates the zkPass proof, and returns it to the "My Namaste" application. The zkPass proof contains:

• The cryptographic proof that the query has been executed properly as-is without any code modifications

• The output or result of the query

Step 4: Returning the zkPass Proof to the Data Holder

After completing the processing of the zkPass Proof, zkPass Service returns the proof to the My Namaste app.

Step 5: Calling the Verifier to verify the proof

The "My Namaste" application calls the Verifier (Namaste Tech) site, passing the received zkPass Proof for verification.

Step 6: Verifying the zkPass Proof and getting the query result

The Verifier (Namaste Tech) validates the zkPass proof and extracts the query result, which could either be true or false. At this point, Namaste Tech determines whether Jane Doe has passed the drug screening test, and it can return the result of the query to the Data Holder (My Namaste app), which completes the entire zkPass data flow.

Confidentiality Note

It's crucial to emphasize that Namaste Tech never gains access to Jane Doe's actual blood test results, which contain sensitive and confidential information irrelevant to drug screening. Instead, what Namaste Tech receives is merely the zkPass proof, encompassing the cryptographic proof of query execution and its output, devoid of any confidential information about Jane Doe.

Following the zkPass SDK guideline, BCA Finance which takes the client role of the Proof Verifier, defines the “Loan Screening” for users who are applying for the car loan. The requirements for the car loan are encapsulated in a query, which is detailed in the Data Verification Request (DVR). This query is formulated using the zkPass Query language, which is JSON-based.

Query

The DVR Query for Ramana Maharshi looks like the following.

Overview

BCA Finance, a prominent player in car loan solutions, manages a high-volume stream of applications on a daily basis. The application processing pipeline is segmented into two pivotal phases: Preliminary Screening and Comprehensive Evaluation. This use case is confined to defining the architecture and implementation methodologies for the Preliminary Screening phase, with a particular emphasis on privacy preservation and execution transparency using the zkPass architecture. The Comprehensive Evaluation phase, although crucial, falls beyond the scope of this use case.

Minimum Eligibility Criteria for Preliminary Screening

To be eligible for car loan coverage through BCA Finance, applicants must meet the following hypothetical criteria as part of the initial screening phase:

• Hold an active BCA Bank account with a minimum balance of Rp 55,000,000.

• Have a credit score of 650 or above.

Fulfilling these prerequisites is imperative for advancing to the comprehensive evaluation stage of the application process.

Objectives of the Screening Process

BCA Bank and BCA Finance intend to develop a screening process that meets the following objectives:

• Cost-Efficient Application Filtering The objective is to expedite the initial sorting of incoming applications, consequently lowering operational overhead. Utilizing an automated, secure, real-time processing system allows BCA Finance to substantially reduce the financial burden associated with manual intervention.

• Privacy Protection for BCA Bank Customers In order to safeguard customer data privacy, BCA Bank will not directly transfer any sensitive information to BCA Finance. Rather, a proof-of-eligibility token, which confirms that the applicant satisfies the predefined criteria, should be sent to BCA Finance. This approach mitigates the risk of data exposure while maintaining the integrity of the application process.

• Verifiable Loan Evaluation Ensuring transparency in the car loan application workflow is crucial. The evaluation result must be solely based on a quantitative analysis of the applicant's credentials. Specifically, the decision-making must be controlled by the business rules defined in a query, which lays out the particular criteria for car loan eligibility. BCA Finance requires that its query runs unmodified, retaining its original logic. Additionally, the query must be performed on the customer profile data and should correspond to the applicant under assessment.

The objective of this use case study is to provide a comprehensive blueprint for zkPass integration to implement a loan application screening mechanism that maintains a good balance between operational efficiency, user data privacy, and verifiable execution. Subsequent sections will delve into the intricate details of the technical architecture, data flow dynamics, and the integration strategies for each stakeholder.

Here are the two simple steps that the ShopSphere OIDC Provider, which takes the Data Issuer client role, must implement:

Providing the user data retrieval API

The ShopSphere OIDC Provider is required to expose a RESTful API that facilitates secure user data retrieval. The API should be designed to authenticate the user robustly, ensuring that only the legitimate owner can access the data. zkPass does not dictate the actual authentication mechanisms, API semantics, or response formats, providing developers the flexibility to implement the API. The API will be typically called by the Data Holder to download the user data needed by the query specified in the DVR.

Signing the user data

To ensure seamless integration with the zkPass framework, the ShopSphere must sign this sensitive information into a JWS (JSON Web Signature) token to ensure the authenticity of the data. To this end, the zkpass-client SDK library provides a function that will simplify the signing process.

Additionally, the ShopSphere OIDC Provider must also distribute the public key needed to verify the signed user data. This can be done via manual or out-of-band public key distribution, or via a programmatic API call as defined by the JSON Web Key Set (JWKS) protocol.

Following the zkPass SDK guideline, Krisna defines the “ShopSphere Account Holder” DVR for user Jane Doe. The query of the DVR looks like the following:

[
  {
    "assign": {
      "account_holder": {
        "and": [
          { "==": [{ "dvar": "iss" }, "http://oidc-provider.ShopSphere.com"] },
          { "~==": [{ "dvar": "firstName" }, "Jane"] },
          { "~==": [{ "dvar": "lastName" }, "Doe"] },
          {
            "==": [{ "dvar": "driverLicenseNumber" }, "DL00718256"]
          }
        ]
      }
    }
  },
  { "output": { "title": "ShopSphere Account Holder Results" } },
  { "output": { "result": { "lvar": "account_holder" } } },
  { "output": { "name": { "dvar": "name" } } }
]

The query contains four requirements or conditions for the "ShopSphere Account Holder" verification, which are explained below

1. iss == "http://oidc-provider.ShopSphere.com" This condition is to ensure that the DVR works on ShopSphere-issued ID token. The "iss" keyword stands for "issuer".

2. firstName == “Jane” This cross-reference condition is to ensure that the user is Jane Doe.

3. lastName == “Doe” This cross-reference condition is to ensure that the user is Jane Doe.

4. driverLicenseNumber == "DL00718256" This cross-reference condition is to ensure that the applicant is Jane Doe by verifying the expected driver's license number. The Krisna previously, through other means, had already acquired and verified Jane Doe’s driver's license number.

Upon receipt of a zkPass proof from the ShopSphere app, Krisna service backend calls the zkpass-client's verify_zkpass_proof function to authenticate the proof. A successful verification indicates that the user indeed has an account with ShopSphere.

Krisna's service takes on the responsibility of formulating the "ShopSphere Account Holder" Data Verification Request (DVR), which serves as the benchmark for validating "ShopSphere ID Token" user information. In the zkPass ecosystem, the Krisna service takes the role of the Proof Verifier. To craft precise DVR queries, Krisna needs a comprehensive grasp of the data structure of the ShopSphere ID Token, as specified by the ShopSphere OIDC Provider. By employing the zkPass Query Language, Krisna is able to target particular fields within the user data through the concept of 'Variable'. Key guidelines for integration consist of the following two main steps:

Providing the DVR retrieval API

The Krisna service needs to provide a RESTful API that allows for the secure retrieval of DVRs. This API must be equipped with strong user authentication measures to ensure that only the rightful owner can access their data. While zkPass doesn't specify the exact methods for authentication, the semantics of the API, or the formats of responses, it offers developers the freedom to create their own implementation. Generally, this API is used by the Data Holder as a starting point in the data verification process.

Signing the DVR

To support the smooth functioning of the zkPass process, the Krisna service is required to sign the "ShopSphere Account Holder" DVR object into a JWS (JSON Web Signature) token. To make this task easier, the zkpass-client SDK library offers a function specifically designed to streamline the signing process.

In addition, the Krisna service needs to provide the necessary public key that allows for the verification of the signed DVR. This distribution can be handled either manually or through an out-of-band method, or more efficiently, through a programmatic API call, as outlined by the JSON Web Key Set (JWKS) protocol.

Providing the zkPass proof verification API

After the ShopSphere app obtains the zkPass proof from the zkPass Service, it will send this proof to the Krisna service for validation. This is accomplished by the app using a proof verification API offered by the Krisna service. Similar to other aspects of zkPass, the specific methods for authentication, the design of the API, and the response formats are not rigidly defined by zkPass, allowing developers the flexibility to tailor their own implementations.

To process this verification request, the Krisna service will employ the verify_zkpass_proof function, which is a part of the zkpass-client SDK library. This function is designed to efficiently handle the verification of the zkPass proof.

By adhering to these guidelines, Krisna reinforces the overall security and effectiveness of the zkPass ecosystem, thereby providing a reliable and secure means of data verification.

When a ShopSphere user has successfully logged into the ShopSphere e-commerce site, the user will receive the ShopSphere ID token from ShopSphere’s backend system. The ID token contains various personal information about the user.

Take, for example, Jane Doe, who is an account holder with ShopSphere, and her ID token is structured in the following manner:

{
  "iss": "http://oidc-provider.shopsphere.com",
  "sub": "auth0|123456",
  "aud": "client_id_58347",
  "exp": 1311281970,
  "iat": 1311280970,
  "name": "Jane Doe",
  "_name_zkpass_public_": true,
  "firstName": "Jane",
  "lastName": "Doe",
  "gender": "female",
  "birthdate": "2000-10-31",
  "driverLicenseNumber": "DL00718256",
  "email": "janedoe@live.com",
  "picture": "http://live.com/janedoe/me.jpg"
}

As demonstrated by the above ID token, the user data contains sufficient information needed for determining the “ShopSphere Account Holder” requirement. However, the profile also contains extraneous sensitive attributes that hold no relevance for the “ShopSphere Account Holder” assessment. Transmitting the full profile to Krisna would not only result in superfluous data transfer but also introduce considerable risk to customer privacy. Once stored in Krisna’s server database, such data becomes susceptible to a myriad of security vulnerabilities, ranging from advanced persistent threats (APTs) to unauthorized data access and insider attacks. This escalates the probability of data exfiltration events.

The "ShopSphere" application acts as the guardian of user-sensitive data and therefore takes the role of the Data Holder. It engages with both the ShopSphere OIDC Provider (Data Issuer) and Krisna service (Proof Verifier) within the scope of the zkPass infrastructure. The primary steps for the ShopSphere app to integrate with the zkPass are explained below.

Retrieving user data from ShopSphere OIDC Provider

In this workflow, the user data consists of the OIDC ID token, which Krisna OIDC Provider generates post-successful authentication. This interaction is strictly limited to the ShopSphere user and the ShopSphere OIDC Provider, ensuring the confidential data is only accessible to these specific parties.

Retrieving DVR from Krisna Service

The ShopSphere app receives the "ShopSphere Account Holder" Data Verification Request (DVR) token from the Krisna app. Note that the DVR is actually generated by Krisna's service during user authentication. To respond to the DVR query, the ShopSphere app avoids sending any sensitive information directly to Krisna. Instead, it dispatches a Zero-Knowledge Proof (ZKP) produced by the zkPass.generateProof method. This function submits both the user data token and the DVR token to zkPass, which then formulates a Zero-Knowledge Proof on behalf of the user. Once this ZKP is created, it is submitted to the Krisna service for verification. Krisna then evaluates the proof to determine if the user data meets the criteria specified in the DVR.

The entire interactive process is designed with a focus on privacy. No Personally Identifiable Information (PII) is ever shared with the Proof Verifier, emphasizing zkPass's dedication to maintaining user confidentiality while enabling secure data validation.

Calling generate_zkpass_proof RESTful API

After the app has successfully gathered both the user data and the DVR, the next step is to initiate a RESTful API call to the zkPass Service. This call is for the generation of the zkPass proof. To facilitate this, the zkpass-client library includes a handy function named generate_zkpass_proof, which is designed to make this process more straightforward and efficient.

Calling Krisna service RESTful API to verify the zkPass proof

The app's concluding task involves forwarding the zkPass proof, received from the zkPass service, to the Krisna service for the ultimate verification step. At this stage, the Krisna service can ascertain whether the user in question holds a ShopSphere account. Notably, this entire process is conducted without disclosing any confidential user information to the Krisna service, ensuring data privacy is maintained throughout.

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.

To achieve full integration with the zkPass framework, all key stakeholders must adhere to the SDK integration guidelines. In the context of the car loan screening process, there are three primary parties involved, as detailed below.

• BCA Bank (Data Issuer) BCA Bank assumes the role of the Data Issuer, as specified by the zkPass framework. In this capacity, the bank defines the attributes encapsulated within the "BCA Customer Profile," as previously described. Thanks to the format-agnostic nature of zkPass concerning user data, the articulated "BCA Customer Profile" is fully interoperable with the zkPass Service. This provides substantial flexibility for the Data Issuer, enabling it to work seamlessly with any data schema or format for its user data.

• BCA Finance (Proof Verifier) Taking the Proof Verifier role within the context of the zkPass framework, BCA Finance defines the criteria for the "Loan Screening" Data Verification Request (DVR). This DVR encapsulates the eligibility requirements established by BCA Finance for assessing car loan applications. Before generating the DVR, BCA Finance has already ascertained the applicant's identity through alternative mechanisms, such as manual verification or AI-based OCR scanning. Having acquired and validated the applicant's full name and driver's license number, this data serves as a cross-referential check against the customer profile to ensure its attribution to the correct individual.

• My BCA (Data Holder) Developed by BCA Bank, the "My BCA" mobile application serves as the main tool for account holders to access a multitude of banking features. This application represents the “User”, also called the “Data Holder,’ role in the zkPass ecosystem. In the zkPass workflow, the Data Holder is usually the user who is interested to answer or resolve the query posed by the Proof Verifier. My BCA is designed to securely retrieve customer profile data from BCA Bank's backend databases, implementing stringent authentication protocols to ensure that only authorized account holders gain access to sensitive information. The application collects the “Loan Screening” DVR from BCA Finance, and the user’s “BCA Customer Profile” from BCA Bank, and relays the information to zkPass Service to create the ZK proof for the loan eligibility.

All of the three stakeholders above, BCA Bank, My BCA app, and BCA Finance, are essentially the client components of the zkPass framework. Each client uses the zkpass-client library to interact with the ecosystem, as illustrated by the diagram.

As depicted above, BCA Bank circumvents direct access from external organizations to the user's exhaustive customer profile, which comprises various personal and sensitive attributes irrelevant to the car loan assessment. Instead, BCA Finance must outline the criteria in the "Loan Screening" Data Verification Request (DVR), which the "My BCA" app subsequently fetches. Upon collecting the user data and the DVR, the app employs the zkPass Service to generate proof. This proof, stripped of any personally identifiable information (PII), constitutes the sole data payload transmitted to BCA Finance, thereby preserving the privacy of BCA's customers.

Moreover, an implicit trust relationship exists between BCA Finance and BCA Bank, as demonstrated. BCA Finance relies on the assumption that the data encapsulated within the user's BCA Customer Profile is both accurate and verifiable.

Despite facing hurdles, ShopSphere continues to be steadfast in its dedication to ensuring customer privacy and fostering transparency in the evaluation of ShopSphere account holder verification, as required by Krisna, its new business collaborator.

To fulfill this commitment, ShopSphere has revamped its mobile app to incorporate the zkPass Proof-as-a-Service framework and to facilitate interactions with the Krisna app on mobile devices. A significant advantage of this integration is that ShopSphere doesn't need to alter the existing architecture or implementation of its OIDC Provider service, resulting in considerable savings in development costs. On the other hand, Krisna only needs to make minor adjustments to its login server to return the "ShopSphere Account Holder" DVR upon successful login. Additionally, Krisna must update its mobile app to launch the ShopSphere mobile app for authentication via the ShopSphere OIDC Provider, enabling its dual user to log into the ShopSphere system securely and receive the ZK proof for being a ShopSphere account holder.

zkPass empowers associated organizations within the ShopSphere network to perform thorough evaluations of account holder profiles while maintaining the confidentiality of sensitive data.

zkPass Client Roles

For a complete integration with the zkPass framework, there are three principal stakeholders engaged in the ShopSphere account holder verification screening process as outlined below:

• ShopSphere OIDC Provider (Data Issuer) ShopSphere OIDC Provider assumes the role of the Data Issuer, as specified by the zkPass framework. In this capacity, ShopSphere defines the attributes encapsulated within the ShopSphere ID token as previously described.

Thanks to the format-agnostic nature of zkPass concerning user data, the articulated ShopSphere ID token is fully interoperable with the zkPass Service. This provides substantial flexibility for the Data Issuer, enabling it to work seamlessly with any data schema or format for its user data.

• Krisna Service (Proof Verifier) Taking the Proof Verifier role within the context of the zkPass framework, the Krisna service backend defines the criteria for the "ShopSphere Account Holder” Data Verification Request (DVR). This DVR encapsulates the eligibility requirements established by Krisna for assessing ShopSphere account holder verification. Krishna user who passes this DVR is deemed as a ShopSphere account holder and, therefore, will be eligible for the 10% discount.

Before generating the DVR, Krisna has already ascertained the applicant's identity through alternative mechanisms, such as manual verification or AI-based OCR scanning. Having acquired and validated the applicant's full name and driver's license number, this data serves as a cross-referential check against the customer profile to ensure its attribution to the correct individual.

• ShopSphere App (Data Holder) Developed by ShopSphere, the "ShopSphere" mobile application serves as the main tool for account holders to access a multitude of e-commerce features. This application represents the “User”, also called the “Data Holder,’ role in the zkPass ecosystem. In the zkPass workflow, the Data Holder is usually the user who is interested to answer or resolve the query posed by the Proof Verifier. ShopSphere app is designed to securely retrieve customer ID profile data from ShopSphere OIDC Provider databases, implementing stringent authentication protocols to ensure that only authorized account holders gain access to sensitive information. The application collects the “ShopSphere Account Holder” DVR from Krisna and the user’s “ShopSphere ID Token” from ShopSphere, and relays the information to zkPass Service to create the ZK proof for the ShopSphere account holder verification eligibility.

All of the three stakeholders above, ShopSphere OIDC Provider, ShopSphere app, and Krisna service, are essentially the client components of the zkPass framework. Each client uses the zkPassClient library to interact with the ecosystem, as illustrated by the following diagram.

As depicted above, ShopSphere circumvents direct access from external organizations to the ID token, which comprises various personal and sensitive attributes irrelevant to the ShopSphere account holder verification assessment. Instead, Krisna must outline the criteria in the "ShopSphere Account Holder” Data Verification Request (DVR), which the ShopSphere app subsequently fetches. Upon collecting the user data and the DVR, the app employs the zkPass Service to generate proof. This proof, stripped of any personally identifiable information (PII), constitutes the sole data payload transmitted to Krisna, thereby preserving the privacy of ShopSphere's customers.

Moreover, an implicit trust relationship exists between Krisna and ShopSphere, as demonstrated. Krisna relies on the assumption that the data encapsulated within the ShopSphere ID Token is both accurate and verifiable.

In order to showcase the OIDC (Open ID Connect) Login use case, ShopSphere, and Krisna Bali serve as hypothetical representations for the roles of Data Issuer and Proof Verifier, respectively. It's crucial to state that all underlying components, such as the alliance partnership, ShopSphere and Krisna's authentication systems, and any other related artifacts, are purely hypothetical and fictitious, created solely for the objective of demonstration.

Background

In a strategic effort to accelerate revenue growth, the Krisna Bali store has entered into a strategic alliance with ShopSphere, a foremost player in the national online retail landscape. This collaboration offers a compelling advantage to customers of Krisna who also maintain ShopSphere accounts; they become eligible for up to a 10% discount on select items showcased on Krisna's online platform.

While there are additional facets and details to this partnership, the primary focus of this document is to elaborate on the technical aspects surrounding the login integration between Krisna and ShopSphere. The objective is to enable Krisna's backend server to validate whether a Krisna customer user also maintains an active ShopSphere account.

Integration Challenges

Merging the distinct user ecosystems of ShopSphere and Krisna presented a complex set of engineering hurdles. ShopSphere utilizes the industry-standard OpenID Connect (OIDC) for authentication, while Krisna employs a proprietary login system with its own dedicated user database. These two systems are inherently divergent and incompatible.

A seemingly straightforward integration strategy would be for Krisna to utilize the OIDC ID tokens from ShopSphere to confirm the identity of a mutual customer, cross-referencing their full name and date of birth. However, this raised justifiable security concerns, particularly from ShopSphere's Vice President of Engineering, about the ramifications of sharing ID tokens containing sensitive customer information with external parties. The concern is further validated by recent security incidents targeting the OAuth protocol, which is integral to OpenID Connect (OIDC), underscoring the importance of implementing robust security measures when sharing ID tokens.

The fundamental requirement for Krisna isn't necessarily accessing the ShopSphere's ID tokens but rather a secure and authenticated assertion that a user, identifiable by their full name and date of birth, is an active ShopSphere account holder. To overcome this challenge, both parties adopted the zkPass Proof-as-a-Service framework. This solution enables the secure, privacy-preserving verification of user credentials, thereby satisfying both parties' technical and security requirements.

Eligibility Criteria for the 10% Discount

To be eligible for the 10% discount on items sold in the Krisna store, a Krisna user account must also have an account with the ShopSphere system. In other words, the “ShopSphere Account Holder” requirement must be defined to determine if the two separate accounts actually belong to the same individual. The user must be able to log in to ShopSphere and Krisna stores, and user attributes of the two user accounts are compared with the following criteria:

• The first name and last name must match

• The driver's license number must match

Objectives of “ShopSphere Account Holder” Verification

The design of the ShopSphere account holder verification aims to achieve the following objectives:

• Privacy Protection for ShopSphere Customers In order to safeguard customer data privacy, ShopSphere will not directly transfer any sensitive information to Krisna via its OIDC ID token. Rather, a proof-of-eligibility token, which confirms that the applicant satisfies the predefined “ShopSphere Account Holder” criteria, should be sent to Krisna's backend servers. This approach mitigates the risk of data exposure while maintaining the integrity of the application process.

The objective of this document is to provide a comprehensive blueprint for developing a “ShopSphere Account Holder” verification mechanism that maintains a good balance between operational efficiency, user data privacy, and verifiable query execution. Subsequent sections will delve into the intricate details of the technical architecture, data flow dynamics, and the integration strategies for zkPass.

Insecure Implementation Example

A straightforward but insecure implementation for the “ShopSphere Account Holder” verification system can be done by sharing the ShopSphere’s ID token with Krisna’s backend system. This is illustrated by the following diagram:

As illustrated in the above diagram, in step 10, Krisna's service receives the ShopSphere ID token. At this point, the Krisna service has some level of access to ShopSphere customer profiles defined in the token. This extraneous information is certainly not needed by Krisna service to determine if the user is a ShopSphere account holder.

The call sequence for the solution with zkPass integration is illustrated here:

As illustrated in the above diagram, in the zkPass-based implementation, the Krisna service no longer receives the ShopSphere ID Token. Instead, it receives the zkPass proof, which protects the privacy of ShopSphere users.

zkPass Proof

As depicted in the prior interaction diagram, the ShopSphere app retrieves both the "ShopSphere ID" user data from the ShopSphere OIDC Provider service and the "ShopSphere Account Holder" Data Verification Request (DVR) from the Krisna service. These data sets are then forwarded to the zkPass service for verification processing. Inside the zkPass service, the legitimacy of both data sets is confirmed, and the DVR query is run on the Zero Knowledge Virtual Machine (ZKVM). Subsequently, zkPass constructs a proof outcome, which is then sent back to Krisna service for ultimate validation.

The proof generated by zkPass Service contains a boolean value that signifies whether the Krisna customer meets the conditions set forth in the "ShopSphere Account Holder" DVR. Crucially, this whole process is executed without exposing any sensitive or confidential user data, thus upholding rigorous data privacy standards.

This approach offers optimal privacy safeguards for the input data, which often contains sensitive Personally Identifiable Information (PII).

Zero Knowledge Proof (ZKP)-based system offers two pivotal advantages:

1. Data Privacy By generating a cryptographic proof via ZKP, the system guarantees the confidentiality of the underlying data. Verifiers can ascertain the proof's legitimacy without the necessity to access or expose the original, sensitive information. This offers a significant leap in privacy measures, especially valuable in contexts where Personally Identifiable Information (PII) is involved.

2. Execution Transparency The cryptographic proof produced by the ZKP mechanism also serves as an unalterable testament to the fidelity of the proof function's execution. It confirms that all the pre-defined conditions or requirements have been met without deviation. This level of execution transparency is crucial for building trust within systems that require stringent compliance and verification processes.

These twin features make ZKP an invaluable tool in modern software engineering, offering both robust data privacy and unparalleled execution transparency.

To illustrate the workflow of a typical client-based proof system, below is a block diagram of an example Decentralized Identity (DID) wallet application for generating proofs for derived credentials. In this typical setup, the ZKP proof generation occurs within the wallet application residing on the user's mobile device.

Challenges of Client-Side Proof-System Architecture

The Trade-Off in Data Privacy Client-side proof-system architecture is often lauded for its effectiveness in protecting data privacy, arguably making it the best approach in this regard. By processing data and generating proofs directly on the client's device, this architecture ensures that sensitive data is never exposed to external entities or servers, thereby significantly enhancing privacy and security.

Limitations Due to Computing Power Primarily stemming from the limitations of the client's computing resources. In many cases, client devices, such as smartphones or personal computers, possess limited processing power. This limitation becomes particularly apparent when attempting to process complex proofs, which require substantial computational resources. The result is a significant bottleneck in proof processing capabilities, which can lead to prolonged processing times. In an era where speed and efficiency are paramount, this delay can be a critical drawback.

Constraints on Query Complexity Another major issue with client-side proof-system architecture is the inherent limitation on the complexity of the queries it can handle. Due to the limited computing power available on most client devices, the architecture often restricts queries to simpler logic. This limitation can render the system impractical for scenarios requiring more sophisticated or intricate queries. In situations where advanced data analysis or complex verification processes are needed, the client-side architecture may struggle to deliver, hindering its practicality and applicability in more demanding environments.

Impact on User Experience The combined impact of limited processing power and restricted query complexity can significantly affect the user experience. Users may find themselves waiting for extended periods for proofs to process, which can be frustrating and counterproductive. Moreover, the inability to execute complex queries may force users to seek alternative solutions, potentially compromising the data privacy benefits that the client-side architecture aims to provide.

In conclusion, while client-side proof-system architecture excels in protecting data privacy, it is important to weigh this advantage against the practical limitations it imposes. The challenges related to limited computing power and restricted query complexity must be carefully considered, especially when evaluating the architecture's suitability for specific use cases or environments. In doing so, organizations can make informed decisions about the best architecture to meet their data privacy and processing needs.

User Data encapsulates a spectrum of sensitive and confidential attributes, ranging from governmental identification forms like driver's licenses and passports to financial credentials like bank account details. In the zkPass model, this data is owned by the Data Holder (User) but provisioned by an entity known as the Data Issuer.

Notably, the 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 zkPass Service.

For a complete definition of the user data, please follow this .

Data Verification Request (DVR) is a very important concept 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. The eventual consumer of the DVR Query is the zkPass Service.

For a complete definition of the DVR, please follow this .

The zkPass Proof is a vital element in the zkPass system, functioning as a digital seal that validates specific data through Zero-Knowledge Proofs (ZKPs) without disclosing the underlying information. This cryptographic token, generated by the zkPass Service, contains a unique cryptographic proof, identifiers, and titles related to the data verification request, and special keys that establish the authenticity of the user data and the request. It also includes a timestamp to mark the generation time, ensuring traceability to its origin. Integral to this proof is the Zero-Knowledge Proof, confirming correct query execution while preserving data confidentiality, and the query output, which is the result of the executed query. Signed into a JSON Web Signature (JWS) token, the ZkPassProof is a testament to the authenticity and integrity of the query results, epitomizing the commitment to security, privacy, and verifiability in the zkPass process.

For a more in-depth definition, please follow this .