Guideline

This is the guideline to implement proof-based authorization logic.

From a high-level view, four entities are involved in the proof-based authorization flow: the user (client), the server, the oracle, and the PII source. Overall, the flow should follow the sequence call illustrated by the diagram below.

Depending on the actual PII source that you use for your application, the actual steps may vary a bit from the ones illustrated above. The following explains the call sequence flows.

  • The user authenticates directly to the PII source. The user receives some sort of access token from the PII source, which the oracle uses. (arrows 1 and 2)

  • The oracle pulls the PII on the user's behalf using the access token, and it signs the PII. (arrows 3, 4, 5, and 6)

  • The user runs the proof generator on the client (browser).

  • The server runs the proof verifier to confirm the proof.

  • The client never sends the PII to the server; it only sends the proof and its output. (arrow 7)

Implementation High-Level Steps

Steps for implementing a proof-based flow:

  1. Provide an oracle service Implement an oracle service specific to the PII source of your application. You can use the sample OZKi oracle service as the starting guide. The oracle must provide a REST API (see arrow 3) for the client (browser) to call for pulling the signed PII data.

  2. Write the proof function in circom. The proof function contains the contraints or requirements on the user's PII, specific to the business logic of your application. Use the OZKi-recommended parameter convention. Use the ozki-toolkit CLI to generate the three zkp file components (wasm, proving key, and verification key files)

  3. Write the subclasses for the proof generator and proof verifier. Use the provided typescript interface to do this. Integrate the proof generator with the client-side of the web application. Integrate the proof verifier on the server-side.

Sample Test Codes

The ozki-toolkit repository has unit test codes which are very useful for getting some ideas on how the implementation and the integration of the proof generator and proof verifier would be done. Under the tests/src directory, see these files:

  • ProofOfLoginTester.ts

  • ProofOfPaymentTester.ts

  • ProofOfHashTester.ts

  • All of the *Verifier.ts and *Generator.ts

Complete Implementation

For a complete demo implementation of proof-based authorizations, you can see the codes in the ozki-oracle and the ozki-bot Github repositories.

PreviousOAuthNextProof Function

Last updated