Cryptography core

[galin-chung-nguyen]

Hi guys, this is my proposal about the cryptography core for the system. Please raise questions in case you need me to clarify something or give me some feedbacks to improve it! Thank you! @tranvinh146 @tranhuyducseven

1. Credential format

• A credential issued by an issuer must consist of the below fields:
  • public fields => the fields that would be revealed to the public and sent through the unsecured channel
    • "issuer": issuer's public key
    • "holder": holder's public key
    • "id": SHA256 hash of proof
    • "@context": // in the first stage, there is no need to use this
    • "encryptedData": encrypted private fields' data using holder's public key
      • "proof": The signature signed by the issuer, not ZK proof
      • "type": "RsaSignature2018"/"EcdsaSecp256k1Signature2019"/...,
      • "created": ISO_date,
      • "proofPurpose": "assertionMethod"/"authentication"/...,
      • "value": "pYw8XNi1..Cky6Ed=",
        • proof = sign(issuer, holder, encryptedData)
      • "verificationMethod": verification method, corresponding to the signature sheme
  • private fields:
    • "type": an array of types of the credentials, e.g. ["RelationshipCredential", "UniversityDegreeCredential"]
      • "issuanceDate": ISO date format,
      • "expirationDate" : ISO date format, or not included if this field is ignored
      • "credentialSubject": a json containing content of the credential
      • => all these private fields are encrypted under the field: "encryptedData"
• Example:

  {
  "id": "ebfeb1f712ebc6f1c276e12ec21klj23h4o937842iuwlehasdf",  
  "type": [ "UniversityDegreeCredential" ],  
  "issuer": "732oi4uh2klj34bb879wfgasiudasdf",  
  "holder": "bklajsdfh78236jhbasdkfj23897123",  
  "issuanceDate": "2010-01-01T19:23:24Z",  
  "expirationDate": "2020-01-01T19:23:24Z",  
  "credentialSubject": {  
  "degree": {  
    "type": "BachelorDegree",  
    "name": "Bachelor of Science and Arts",
  },
  "department": "FIT",
  "class" : 2024
  },  
  "encryptedData": "asdfnlaksh2l34hqq32987roaidshalskjdaslkdjf239862o34"
  "proof": {  
  "type": "Ed25519Signature2020",  
  "created": "2022-02-25T14:58:43Z",  
  "verificationMethod": "Ed25519SignatureVerification2020",  
  "proofPurpose": "assertionMethod",  
  "proofValue": "z3zwi434j3HdZv3C3TJxBnwmmiBgrtzRjM2oeDtZyAEkDeNDBeB9Metc  
  vyB4ZZUvQswKqPdgk5cFSAnyJ3yjvButH"  
  }  
  }

  2. User flow

  2.1 Issuer issues a credential

• Step 1: Issuer fill credential's content
• Step 2: Issuer encrypt private fields with public key of holder to create a new field "encryptedData"
  • encryptedData = ECCEncryption(holder's public key) // ECC + Diffie-Hellman method
• Step 3: Generate signature & id
  • proof.value = sign(signature_method, issuer, holder, encryptedData)
  • id = sha256(proof.value)
• Step 4: Send the credential (only public fields) to holder -> holder stores credential in local storage
• Step 5: Call the smart contract to create an anchor to the credential
  • credentials[id] = {
    • issuer: askdfhlaksdf
    • holder: lakhewjlkajsdfhasdf
    • status: issued/revoked/disputed/...
  • }

    2.2 Verifier creates a schema

    Verifier chooses a schema template (e.g. UniversityDegreeCredentialSchema) or creates a new schema and then send to the holder/publish this schema. The schema should be constructed with the format below:

• "name": "Computer Science University Degree Check"
• "verifier": verifier's public key
• "checks": an array [] of check, each check corresponds to one specific credential, which means a schema can be used to asserts multiple credentials
  • each check in the array is a json:
    • "field":
      • "operator" : value
      • operator is a comparison operator (gt, gte, le, lte, eq) => would scale to arbitrary expression later
      • "sub_field": { ... similar pattern }
    • or just use "field": "value" to represent equality
    • the field "type" is a must-have check
• "requests": ["index_of_credential_in_checks_field.requestField1", "index_of_credential_in_checks_field.requestField2", ...] => request holder to shows these fields
• "proof": The signature signed by the verifier, not ZK proof
  • "type": "RsaSignature2018"/"EcdsaSecp256k1Signature2019"/...,
  • "created": ISO_date,
  • "proofPurpose": "assertionMethod"/"authentication"/...,
  • "value": "pYw8XNi1..Cky6Ed=",
  • proof = sign(name, verifier, checks, requests) using verifier's private key
  • "verificationMethod": verification method, corresponding to the signature sheme
• id = sha256(proof.value)
• Example:

  {
  "name": "Computer Science University Degree Check",
  "verifier": "asdnfklj234o123498ssdfasdjfagsdf",
  "checks":[
      {
          "type": {
              "eq" : "UniversityDegreeCredential"
          },
          "degree" : {
            "type": "BachelorDegree",   // based on the global standard
            "name": "Bachelor of Science and Arts"
          },
          "class": {
              gte: "2023" // only allows guys graduate this year to apply into the job
          }
      },
      {
          "type": {
              "eq" : "NationalIdentificationCredential"
          },
          "country": "VI",
          "nationality": "VI",
          "dateOfBirth": {
              "gte": "2000-01-01T00:00:00Z",  // only allows Vietnamse guys born in 21'st century
          }
      }
  ],
  "requests": ["0.schoolName", "1.name"] // get name & school name
  }

  2.3 Holder submits credentials to a schema

• Step 1: After getting the schema from the verifier, the holder chooses corresponding credentials that satisfy the checks and requests
• Step 2: Holder generates & encrypt the requested fields (using verifier public key) into encryptedRequestedData (encryptedRequestedData = ECCEncrypt(verifier_pubic_key, requestedData))
• Step 3: Holder generate ZK proof: proof = generateProof(rawCredentials[], public rawSchema, public requestedData)
  • This function do the below checks:
    • Check if credentials satisfy the schema
    • Check if requestedData is the requested fields specified in rawSchema and taken from rawCredentials
• Step 4: Holder sends proof + encryptedRequestedData to the verifier through public channel or in-secure private channel (like BE)
• • (Optional) Step 5: Holder submit an anchor of the proof to the verifier smart contract:
  • schema_submissions[schema_id][proof] = true/false (true means the proof passes the verifier checks)

2.4 Verifier verifies submission

Step 1: Verifier decrypt the requestedData: requestedData = ECCDecrypt(verifier_private_key, encryptedRequestedData) Step 2: Verifier run the check:

• verifier verifies proof: verify(proof, rawSchema, requestedData)
• if the check passes, the verifier updates the status of this submission to

[vinhtrand8]

About Credential format:

• public fields
  • "issuer": issuer's public key -> issuer's did (1 did can have more than 1 public key).
  • "holder": holder's public key -> holder's did.
  • "proof":
  • "verificationMethod": specific the key id issuer using to sign message ref. If someone to get detail of this key (signature schema, public key,...), he will query the did document of issuer in blockchain. Example: did:flow:2345asdfg#key1

[vinhtrand8]

In 2.1. section, Issuer issues a credential,

Step 4: Send the credential (only public fields) to holder -> holder stores credential in local storage

Should the tech be like that:

0. BE stores this credential (public fields),
1. When user logs in app, mobile will fetch data from db.
2. If new credential is issued, alert and require them to authenticate to get private key.
3. Using private key decrypt encryptedData,
4. Store complete credential (private & public fields) to local device.

[vinhtrand8]

About 2.2 Verifier creates a schema, we should have a field (nonce or challenge) to prevent relay attack ref. For example, a challenge is a random number for every request schema, it can prevent an holder from creating a Verifiable Presentation and send it for his friends,

[vinhtrand8]

We should follow W3C term

• in the case issuer issue credential for holder, we call "Verifiable Credential"
• in the case holder present a claim about credential to verifier, we call "Verifiable Presentation"

[galin-chung-nguyen]

About 2.2 Verifier creates a schema, we should have a field (nonce or challenge) to prevent relay attack ref. For example, a challenge is a random number for every request schema, it can prevent an holder from creating a Verifiable Presentation and send it for his friends,

It feels like the nonce couldn't help here. Because this is not jwt. Once the attacker observed the data sent (proof + encryptedData), they just submit the same things and the check will still pass. We might solve this by filtering the duplicated submissions, or using some other methods. @tranvinh146 What do you think?

[vinhtrand8]

{
    "name": "Computer Science University Degree Check",
    "verifier": "asdnfklj234o123498ssdfasdjfagsdf",
    "checks":[
        ...
    ],
    "requests": ["0.schoolName", "1.name"],
        "nonce": "0x123456789abcdef" // add this field
}

I think checking a signature of nonce is easier than storing and checking duplicated submissions. Holder has just sent ( proof + encryptedData + signature(nonce) ), so verifier can make sure that holder owns the particular key in DID document (verifier can check assertMethod in DID document of holder).

cc @galin-chung-nguyen

[galin-chung-nguyen]

But if someone does replay attack, they could just send all of proof + encryptedData + signature(nonce), the verifier cannot realize whether it is the real holder or the attacker @tranvinh146

[vinhtrand8]

In my case, each request can use only one time, so malicious user can not use this proof to send other verifiers.

P/S: maybe we need to discuss in the next meeting.