zkPass
zkPass Developer's Guide
zkPass Developer's Guide
  • â›Šī¸Introduction
  • ZKPASS OVERVIEW
    • đŸ›ī¸Architecture
    • 🧱zkPass Components
    • 🤝Trust Models
    • 🚚Deployment
      • Public-Cloud Hosting
      • Private-Cloud Hosting
      • On-Premise Hosting
    • đŸŽ¯SDK Objectives
    • 🔑API Key
  • zkPass Modules
    • â˜ī¸DVR
      • đŸ—ģHigh Level View
      • đŸ—ī¸Key Concepts
        • User Data
        • DVR Info
        • zkPass Proof
      • đŸ‘ĨDVR Client Roles
        • Data Issuer
          • Providing User Data Retrieval API
        • Data Holder
          • 1. Retrieving the DVR
          • 2. Retrieving the User Data
          • 3. Generating the Proof
          • 4. Verifying the Proof
        • Proof Verifier
          • 1. Providing DVR Retrieval API
          • 2. Providing Proof Verification API
      • 🔎DVR Query
        • Building Query Engine
        • Processing Query
        • Query Grammar
      • đŸ—ī¸Integration Guidelines
      • 🌊DVR Workflows
  • SDK Tutorial
    • Typescript
      • Running Code
      • Code Snippet
      • Directory Structure
    • Rust
      • Running Code
      • Code Snippet
      • Directory Structure
  • API Reference
    • Typescript
      • Classes
        • Class: DvrModuleClient
      • Functions
        • Functions: ffiHelper
        • Functions: jwtHelper
        • Functions: publicKeyOptionUtils
      • Type Aliases
        • Types
        • Types: ffiType
      • Interfaces
        • Interfaces
      • Constants
        • Constants
        • Enums
      • Errors
    • Rust
      • Building Rust doc
    • RESTful API
      • Overview
      • Endpoints
        • Generate Proof
      • Utilities
        • Generate Key Pair
        • Sign User Data and DVR
        • Encrypt User Data and DVR
      • Errors
  • Glossary
    • DVR
    • User Data
    • ZKP
Powered by GitBook
On this page
  • Prerequisites
  • Overview
  • Example Implementation
  • Output Example
Export as PDF
  1. API Reference
  2. RESTful API
  3. Utilities

Sign User Data and DVR

Prerequisites

Make sure you have key pair consisting of :

  1. publicKeyJWKS

  2. privateKey

Read Generate Key Pair section for detail info.

Overview

We need to sign User Data and Data Verification Request (DVR) before sending a request to the zkPass service. This ensures that the payload is not tampered during transport.

Example Implementation

JWKS

The JSON Web Key Set (JWKS) is a set of keys containing the public keys used to verify any JSON Web Token (JWT) issued by the Authorization Server and signed, You can find a complete definition of JWKS here.

Upload your publicKeyJWKS so that it's accessible from the internet. This will be used by zkPass service to verify the validity of the user data.

Example of the uploaded publicKeyJWKS

{
  "keys": [
    {
      "x": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAELOmrNI4A9ML4iGJXpYlaZiYGVCxB",
      "y": "k+evjhOZEbCLj17o/ZdfEv7dUZIRKRoZ1bud5Gq8OCItDlXkTyMrtWrhdA==",
      "kid": "q6ZFSOJcTiZWJWkvUshpFw5v20xstZN/T4lt4zpKsUg="
    }
  ]
}

JWS

A JSON Web Signature (abbreviated JWS) is an IETF-proposed standard (RFC 7515) for signing arbitrary data. This is used as the basis for a variety of web-based technologies including JSON Web Token. You can find a complete definition of JWS here.

This is an example code of how you can sign a JSON object as JWS format in Typescript. Let's say you uploaded your publicKeyJWKS to https://mywebsite/my-keys.json

import { SignJWT, importPKCS8 } from "jose";

async signDataToJwsToken(
    privateKey: string,
    userDataOrDVR: any
  ): Promise<string> {
    const verifyingKeyJwks = {
      jku: "https://mywebsite/my-keys.json",
      kid: "q6ZFSOJcTiZWJWkvUshpFw5v20xstZN/T4lt4zpKsUg="
    }
    
    const alg = "ES256";
    const importedPrivateKey = await importPKCS8(privateKey, alg);
    
    return await new SignJWT({ data: userDataOrDVR })
      .setProtectedHeader({
        alg: alg,
        jku: verifyingKeyJwks.jku,
        kid: verifyingKeyJwks.kid,
      })
      .sign(importedPrivateKey);
  }

Example for User Data

{
  "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",
    "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
  }
}

Below is the example of Query in DVR, this query will be included in full DVR

[
  {
    "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": { "result": { "lvar": "blood_test_status" } } }
]

Below is the example of full DVR that will be generated into DVR Token

{
  "zkvm": "r0",
  "dvr_title": "My DVR",
  "dvr_id": "d5bba9dc-e90c-456d-811c-79aa73755f54",
  "query_engine_ver": "1.3.0",
  "query_method_ver": "24555fe163e523bb313df8355ca39fbd79d49a02c642373b19c2a31cfc7a78d",
  "query": "[{\"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\":\"subject.contact.email\"},\"jane.doe@gmail.com\"]},{\"==\":[{\"dvar\":\"measuredPanelsNgML.amphetamines\"},0]},{\"<=\":[{\"dvar\":\"measuredPanelsNgML.cocaine\"},10]}]}}},{\"output\":{\"name\":{\"dvar\":\"subject.firstName\"}}},{\"output\":{\"email\":{\"dvar\":\"subject.contact.email\"}}},{\"output\":{\"result\":{\"lvar\":\"blood_test_status\"}}}]",
  "user_data_requests": [
    {
      "key": "",
      "value": {
        "jku": "https://raw.githubusercontent.com/gl-zkPass/zkpass-sdk/main/docs/zkpass/sample-jwks/issuer-key.json",
        "kid": "k-1"
      }
    }
  ],
  "dvr_verifying_key": {
    "jku": "https://raw.githubusercontent.com/gl-zkPass/zkpass-sdk/main/docs/zkpass/sample-jwks/verifier-key.json",
    "kid": "k-1"
  }
}

Output Example

After this section you should have :

  1. User Data Token : User Data in JSON Web Signature (JWS) format.

  2. DVR Token : DVR in JSON Web Signature (JWS) format.

Here's the example of User Data Token & DVR Token in JWS format.

{
  "userDataToken": "eyJ0eXAiOiJKV1QiLCJqa3UiOiJodHRwczovL3Jhdy5naXRodWJ1c2VyY29udGVudC5jb20vZ2wtemtQYXNzL3prcGFzcy1zZGsvbWFpbi9kb2NzL3prcGFzcy9zYW1wbGUtandrcy9pc3N1ZXIta2V5Lmpzb24iLCJraWQiOiJrLTEiLCJhbGciOiJFUzI1NiJ9.eyJkYXRhIjp7InRlc3RJRCI6IlNDUkVFTi03MDgzLTEyMzQ1IiwidGVzdE5hbWUiOiJRdWFsaXR5SGVhbHRoIENvbXByZWhlbnNpdmUgU2NyZWVuIiwidGVzdERhdGUiOiIyMDIzLTA4LTI3VDE0OjAwOjAwWiIsImxhYiI6eyJuYW1lIjoiUXVhbGl0eUhlYWx0aCBMYWJzIiwiSUQiOiJRSDgwMTg3NCIsImFkZHJlc3MiOiIxMjM0IEVsbSBTdCwgT2FrbGFuZCwgVVNBIn0sInN1YmplY3QiOnsiZmlyc3ROYW1lIjoiSmFuZSIsIl9maXJzdE5hbWVfemtwYXNzX3B1YmxpY18iOnRydWUsImxhc3ROYW1lIjoiRG9lIiwiZGF0ZU9mQmlydGgiOiIxOTg1LTEyLTEyIiwiYmxvb2RUeXBlIjoiQSsiLCJETkFJbmZvIjp7Im1hcmtlcnMiOnsiQVBPRSI6WyJFMyIsIkUzIl0sIkJSQ0ExIjoiTm9ybWFsIiwiTVRIRlIiOlsiQzY3N1QiLCJBMTI5OEMiXX0sImhhcGxvZ3JvdXBzIjp7InBhdGVybmFsIjoiUjFiMSIsIm1hdGVybmFsIjoiSDFhMSJ9fSwiY29udGFjdCI6eyJlbWFpbCI6ImphbmUuZG9lQGdtYWlsLmNvbSIsIl9lbWFpbF96a3Bhc3NfcHVibGljXyI6dHJ1ZSwicGhvbmUiOiI2NTAtNTU1LTEyMzQifSwiYWRkcmVzcyI6eyJzdHJlZXQiOiI3ODkgT2FrIFN0cmVldCIsImNpdHkiOiJTYW4gSm9zZSIsInN0YXRlIjoiQ0EiLCJ6aXAiOiI5NTEzNCJ9fSwibWVhc3VyZWRQYW5lbHNOZ01MIjp7ImFtcGhldGFtaW5lcyI6MCwiY29jYWluZSI6OCwib3BpYXRlcyI6MTAyLCJiZW56b2RpYXplcGluZXMiOjB9fX0.TwoIFlHXnKjhKGlhW6tCfuc20pgvFFUmZ_wEMBvrQyKaub7aN3SBT0_zPPeDn_EUi2UP6eo0pr7ofNjfXEtgsA",
  "dvrToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9.eyJkYXRhIjp7Inprdm0iOiJyMCIsImR2cl90aXRsZSI6Ik15IERWUiIsImR2cl9pZCI6ImQ1YmJhOWRjLWU5MGMtNDU2ZC04MTFjLTc5YWE3Mzc1NWY1NCIsInF1ZXJ5IjoiW3tcImFzc2lnblwiOntcImJsb29kX3Rlc3Rfc3RhdHVzXCI6e1wiYW5kXCI6W3tcIj09XCI6W3tcImR2YXJcIjpcImxhYi5JRFwifSxcIlFIODAxODc0XCJdfSx7XCI9PVwiOlt7XCJkdmFyXCI6XCJ0ZXN0SURcIn0sXCJTQ1JFRU4tNzA4My0xMjM0NVwiXX0se1wifj09XCI6W3tcImR2YXJcIjpcInN1YmplY3QuZmlyc3ROYW1lXCJ9LFwiamFuZVwiXX0se1wifj09XCI6W3tcImR2YXJcIjpcInN1YmplY3QubGFzdE5hbWVcIn0sXCJkb2VcIl19LHtcIj09XCI6W3tcImR2YXJcIjpcInN1YmplY3QuZGF0ZU9mQmlydGhcIn0sXCIxOTg1LTEyLTEyXCJdfSx7XCI9PVwiOlt7XCJkdmFyXCI6XCJzdWJqZWN0LmNvbnRhY3QuZW1haWxcIn0sXCJqYW5lLmRvZUBnbWFpbC5jb21cIl19LHtcIj09XCI6W3tcImR2YXJcIjpcIm1lYXN1cmVkUGFuZWxzTmdNTC5hbXBoZXRhbWluZXNcIn0sMF19LHtcIjw9XCI6W3tcImR2YXJcIjpcIm1lYXN1cmVkUGFuZWxzTmdNTC5jb2NhaW5lXCJ9LDEwXX1dfX19LHtcIm91dHB1dFwiOntcIm5hbWVcIjp7XCJkdmFyXCI6XCJzdWJqZWN0LmZpcnN0TmFtZVwifX19LHtcIm91dHB1dFwiOntcImVtYWlsXCI6e1wiZHZhclwiOlwic3ViamVjdC5jb250YWN0LmVtYWlsXCJ9fX0se1wib3V0cHV0XCI6e1wicmVzdWx0XCI6e1wibHZhclwiOlwiYmxvb2RfdGVzdF9zdGF0dXNcIn19fV0iLCJxdWVyeV9lbmdpbmVfdmVyIjoiMS4zLjAiLCJxdWVyeV9tZXRob2RfdmVyIjoiMjQ1NTVmZTE2M2U1MjNiYjMxM2RmODM1NWNhMzlmYmQ3OWQ0OWEwMmM2NDIzNzNiMTljMmEzMWNmYzdhNzhkIiwidXNlcl9kYXRhX3JlcXVlc3RzIjp7IiI6eyJ1c2VyX2RhdGFfdXJsIjpudWxsLCJ1c2VyX2RhdGFfdmVyaWZ5aW5nX2tleSI6eyJLZXlzZXRFbmRwb2ludCI6eyJqa3UiOiJodHRwczovL3Jhdy5naXRodWJ1c2VyY29udGVudC5jb20vZ2wtemtQYXNzL3prcGFzcy1zZGsvbWFpbi9kb2NzL3prcGFzcy9zYW1wbGUtandrcy9pc3N1ZXIta2V5Lmpzb24iLCJraWQiOiJrLTEifX19fSwiZHZyX3ZlcmlmeWluZ19rZXkiOnsiS2V5c2V0RW5kcG9pbnQiOnsiamt1IjoiaHR0cHM6Ly9yYXcuZ2l0aHVidXNlcmNvbnRlbnQuY29tL2dsLXprUGFzcy96a3Bhc3Mtc2RrL21haW4vZG9jcy96a3Bhc3Mvc2FtcGxlLWp3a3MvdmVyaWZpZXIta2V5Lmpzb24iLCJraWQiOiJrLTEifX19fQ.3sGHmQZ_lbEJei9OKTxlshDoYs2wWurjEyiA767BEBrxU5u5fSV-s1qHghVlp748MqZf_cLb7j6g3MrsL34wbw"
}
PreviousGenerate Key PairNextEncrypt User Data and DVR

Last updated 7 months ago