This specification defines the proof format used in OpenAttestation V3 Verifiable Credentials, which features a lossy progressive selective redaction scheme compatible with W3C Verifiable Credentials.

Introduction

Selective redaction is a desirable property of verifiable credentials. OpenAttestation implements a lossy progressive selective redaction scheme, which allows it to be used in applications where a verifiable credential is passed along a chain of multiple verifiers and where privacy and data minimization techniques are desired and/or required.

OpenAttestation

OpenAttestation is an open-source framework for implementing verifiable credentials. It has been used in production since 2018. OpenAttestation has been implemented:

For educational institutions to issue academic credentials to graduates;
For healthcare clinics to issue COVID-19 pre-departure test and vaccination records in line with international standards and the Singapore government.
For the trade, finance and logistics community to issue verifiable trade documents

Use Cases and Requirements

This section describes an example use case of OpenAttestation verifiable credentials, in cross-border trade.
The verifiable credential may be passed to multiple parties in the supply chain.
Along the chain, parties may wish to redact sensitive information before passing to the next party.
This use case requires a lossy progressive disclosure scheme that does not break the original signature.

Terminology

Placeholder for any new terminology that needs to be introduced.

Raw Document
...

Document Store
...

Producing

Wrapping

To generate an OpenAttestationMerkleProof2018 signature, the raw document first goes through a process we call [= wrapping =]. In this process, salts are generated for every property of the credential object in order to prevent rainbow table attack. They are then flattened and encoded as a string and embedded in proof.salts (see example).

Once the [= rawDocument/raw document =] has been salted, each field will be hashed with the value and salt. The output hashes will then be sorted and stored in an array.

Finally, with the array of sorted hashes, the stringified array is hashed again and embedded in proof.targetHash and proof.merkleRoot (same if only 1 raw document is wrapped at a time).

Issuance

To issue an OpenAttestation Verifiable Credential, the proof.merkleRoot is signed with the Decentralised Identifier (DID) of the issuer and embedded in the proof.proofs property of the Verifiable Credential.

            {
              // ...
              "proof": {
                "type": "OpenAttestationMerkleProofSignature2018",
                "proofPurpose": "assertionMethod",
                "targetHash": "82f51d6eb620e4264dff0ac2b9d99a965a88ff51e46192bb4808ea969ee67402",
                "proofs": [
                  "a1c633145bc0f37105fe510d335376c1919a6cf51030628877288bdee5541c22",
                  "c3d7c5908f25eba67baf7f607932f1924acdb7a6cf04ad5408dba251bf0a47bc",
                  "94c07ddcc4a2ade59e3120dce9f19f0f4ad80a58943555f4b51af4668b1c1d62"
                ],
                "merkleRoot": "f43045b0c57072a044e810b798e32b8c1de1d0d0c5774d55c8eed1f3fdec6438",
                "salts": "abc...",
                "privacy": {
                  "obfuscated": []
                },
                "key": "did:ethr:0x1245e5B64D785b25057f7438F715f4aA5D965733#controller",
                "signature": "0x4a054aaf881da5130a3b19160a7f0ce1afef1fe093c83be438c8c40b0a04ace5142f3d48a23c8ce7c32fabe04fc69e6fd4c94cf3ceb4adb4f3da5fa937208d4e1c"
              }
            }

See full example here.

The OpenAttestation Verifiable Credential can also be issued by publishing the proof.merkleRoot to a Verifiable Data Registry.

Cryptography Suites and Libraries

The OpenAttestation implementation of the algorithm described above uses the keccak256 hash to transform properties into the targetHash, and ECDSA with Secp256k1 to sign the targetHash. However, the algorithm is not permanently tied to these cryptography suites. In the event that they fall to new attacks and technology advances, this specification will be updated to upgrade the cryptography suites used.

Redacting

To obfuscate a property in the OpenAttestation Verifiable Credential, the key-value pair is hashed and the resulting hash is stored in the privacy.obfuscatedData property. The obfuscated object is removed. This method can be used to obfuscate multiple key-value pairs in the credential.

Obfuscation does not invalidate the proof property as the targetHash is computed over all hashed key-value pairs in the credential.

Verifying

To verify the integrity of the document, the verifier computes the targetHash via the same process in [= producing/Producing =], namely by hashing individual key-value pairs, appending and sorting the hashes of the individual key-value pairs with the hashes from privacy.obfuscatedData, and computing the targetHash from the array of sorted hashes. The verifier then checks that the computed hash matches the targetHash. Where the targetHash is signed with the issuer's DID, the verifier utilises the DID verification method to verify the signature.

OpenAttestationMerkleProofSignature2018

Introduction