Practical interoperability with other W3C VC software

[morgatron]

This is a continuation of some great conversation we've started with @HJunyuan and @lawwman

The summary is that we think OpenAttestation is great, and we're wanting to use it for cross-border trade scenarios where we need to verify VCs issued by other platforms, and issue VCs to be verified by other platforms. However, while OA v3 is technically compliant with the W3C VC data model OA's extensions to the model are not understood by other software. So the question is: can we make OA "practically" interoperable while keeping the useful features of OA?

I'm starting this issue to try and push the discussion further.

What does interoperable mean?

Other VC platforms (e.g. Transmute, DIDKit), can verify a VC issued by OA
OA can verify VCs issued by other platforms (e.g. Transmute, DIDkit)

In testing terms: if we wrap OA in the VC-API (which we are in the process of doing), it should pass the vc-api test suite

If these can be met, it should be a good indication of "Plugfest interoperability"- that is being a successful part of the USA's DHS/SVIP plugfest

What stops OA being interoperable?

The main barriers to practical interoperability I can see at this point:

• OA's proof method is essentially hard-coded (as type OpenAttestationMerkleProofSignature2018), both in verification and issuing.
• OA ignores "issuer" field, instead only looks at "OpenAttestationMetadata.proof" to determine the signing key for verification.
• The use of a "version" field to specify a schema. I suspect this should map to credentialSchema?
• Supported did:methods: OA seems to only really support did:eth. Other common did:methods should be useable (but their support will be dependant on how a new proof method is implemented)
• oa-verify looks for "OpenAttestationMetadata.identityProof" and will fail if it's not there. This should be less of a problem on issuing as it will be ignored by other software. If signing with did:methods such as did:dns or did:web, it seems somewhat redundant.

A couple of other minor points:

• The embedded renderer extension is "safe" to use for issuing as it should be ignored by other software. This is however a very useful extension. Perhaps this could be written up as a generic VC extension?
• The need to load OpenAttestation specific @contexts, (e.g. "https://schemata.openattestation.com/com/openattestation/1.0/OpenAttestation.v3.json") Other implementations will typically have to have these whitelisted or pre-cached in order to use them. The use of at least one extra context is certainly unavoidable, but it may be worth minimising the number of them.

Is the above a fair summary?

I'm still quite new to OpenAttestation, and I apologise for the mistakes I've probably made! Please let me know.

If the above does seems reasonable though, I'd like to raise some other issues to explore some of the solutions.

[HJunyuan]

Hi @morgatron, thanks for the detailed writeup! I will try to get the ball rolling to best of my ability. The rest of the OpenAttestation team may also chime in where necessary.

However, while OA v3 is technically compliant with the W3C VC data model OA's extensions to the model are not understood by other software.

Do you have any examples of such other software? I recall hearing you mention about a Transmute verifier over our earlier conversation. Perhaps you could link us to their verifier?

In testing terms: if we wrap OA in the VC-API (which we are in the process of doing), it should pass the vc-api test suite

Is this test suite similar to one laid out here? There is a column for OpenAttestation describing the respective test results.

OA's proof method is essentially hard-coded (as type OpenAttestationMerkleProofSignature2018), both in verification and issuing.

It's mainly because OpenAttestation only supports this proof method at the moment. There's currently no option that allows end-users to change or sign using another proof method.

OA ignores "issuer" field, instead only looks at "OpenAttestationMetadata.proof" to determine the signing key for verification.

Do you mean this code segment? I don't know the exact reason why the issuer field is left out during verification. Looking again at the W3C specs, the issuer.id field can be a DID URL. Which means it should be set the same value as openAttestationMetadata.proof.value. Would you agree?

The use of a "version" field to specify a schema. I suspect this should map to credentialSchema?

Yes, it does sound like we should use credentialSchema. Need to confirm with the rest of the OA team if we can make the change.

Supported did:methods: OA seems to only really support did:eth. Other common did:methods should be useable (but their support will be dependant on how a new proof method is implemented)

The OA verifier actually creates a resolver that can resolve both did:eth and did:web URLs. However, the verifier can only verify signatures signed using the EcdsaSecp256k1RecoveryMethod2020. That being said, there is also no toolkit offered by OA to manage the creation or hosting of did:web at this time.

oa-verify looks for "OpenAttestationMetadata.identityProof" and will fail if it's not there. This should be less of a problem on issuing as it will be ignored by other software. If signing with did:methods such as did:dns or did:web, it seems somewhat redundant.

Yes, that is correct. Once did:web or did:dns methods are used, the openAttestationMetadata.identityProof becomes redundant as the act of resolving such DIDs will already prove (or map) the DID to a domain.

[morgatron]

Hi @morgatron, thanks for the detailed writeup! I will try to get the ball rolling to best of my ability. The rest of the OpenAttestation team may also chime in where necessary.

(Apologies if it was a bit of a dump!)

Do you have any examples of such other software? I recall hearing you mention about a Transmute verifier over our earlier conversation. Perhaps you could link us to their verifier?

Some examples of other software (google search name + github will get you there for each of these):

• Transmute
• DIDkit
• Digital Bazaar
• DanubeTech

Of these, DIDkit's is probably the easiest to use, as they have a nice command line utility.

For installation-free testing, you can try:

• DanubeTech's "universal verifier"
• Transmute's https://api.did.actor

Is this test suite similar to one laid out here? There is a column for OpenAttestation describing the respective test results.

This is a subtle point. That test suite you link is purely for the VC data model. Applying it to OA simply checks that the correct fields exist in an issued doc and that no un-qualified data is in there. This is a great first step...

but: it does not check that the fields are used as the spec intended, OR that the methods used are understood by other software.

The vc-api test suite I linked is a step toward interoperability testing. It assumes a given issuance/verification api (the 'vc-api'), and attempts to issue and verify generic VCs. We've already put a simple vc-api wrapper around OA and applied this test suite. I can share the initial results if you're itnerested.

In our meeting, Richard also mentioned a related test suite, fromthe w3c-ccg 'traceability interop' project and the SVIP 'plugfest'. This is an actual interop test between different VC issuers/verifiers, and is implemented as a set of postman collections calling the a vc-api. Ideally we should go green on this too.

Do you mean this code segment? I don't know the exact reason why the issuer field is left out during verification. Looking again at the W3C specs, the issuer.id field can be a DID URL. Which means it should be set the same value as openAttestationMetadata.proof.value. Would you agree?

Yep, exactly! This is an example of where OA fits the VC data model (it has an 'issuer' field), but isn't practicaly interoperable (because it doesn't actually use the 'issuer' field). The simple change of openAtttestationMetadata.proof.value -> issuer.id would do it from our point of view. But the caveat is I'm not sure how to support multiple issuers at this time, as you do with OAv2.

Yes, it does sound like we should use credentialSchema. Need to confirm with the rest of the OA team if we can make the change.

Great!

The OA verifier actually creates a resolver that can resolve both did:eth and did:web URLs. However, the verifier can only verify signatures signed using the EcdsaSecp256k1RecoveryMethod2020. That being said, there is also no toolkit offered by OA to manage the creation or hosting of did:web at this time.

Yes I'm sorry, I didn't do a good job in my description. I do know that OA uses the standard did:ethr resolver from DIF, and can use one for did:web too (which is great!). But as you say, it only supports signing a hash using EcdsaSecpk1. Which means that most did:web's used in the wild won't work , even when using OA's own proof method, because EcdsaSecpk1 is pretty rare outside of block-chain use cases.

Have you put much thought in how best to do general DID resolution- e.g. using JS components compared to an external service implementing something like https://dev.uniresolver.io? An e.g of the latter is this Transmute example. This would relate to #234.

Yes, that is correct. Once did:web or did:dns methods are used, the openAttestationMetadata.identityProof becomes redundant as the act of resolving such DIDs will already prove (or map) the DID to a domain.

This is part of that verification discussion that I explained badly this morning. What does the verifier look like for such a document? I'm wondering if it's cleanest if a single verifier could return two fragments, so that verifying a did:dns signature could return DOCUMENT_INTEGRITY and ISSUER_IDENTITY... but perhaps I should write about that over here

[superical]

This is a subtle point. That test suite you link is purely for the VC data model. Applying it to OA simply checks that the correct fields exist in an issued doc and that no un-qualified data is in there. This is a great first step...

but: it does not check that the fields are used as the spec intended, OR that the methods used are understood by other software.

The vc-api test suite I linked is a step toward interoperability testing. It assumes a given issuance/verification api (the 'vc-api'), and attempts to issue and verify generic VCs. We've already put a simple vc-api wrapper around OA and applied this test suite. I can share the initial results if you're itnerested.

Hi @morgatron! I'm just dropping by and trying to see how I can help. I'm pretty new to this whole OA and W3C VC thing. I beg your pardon whenever I'm having more questions than answers. hehe.🫢

1. How does the vc-api test suite work? Is it like a test runner where you could input a VC file and it returns the results of all the W3C standard test cases pre-implemented in the runner?
2. You mentioned about VC data model. Is the VC data model referring to the wrapped version of an OA document?
3. You mentioned about already having a simple vc-api wrapper around OA for the test suite. Do you mean you already have something where you could convert a wrapped OA document into a compatible VC document of equivalence that can then be input directly into the vc-api test runner and we get the test results? If I understood this correctly, this sounds like pretty cool stuff!

[morgatron]

Nice to meet you @superical, thanks for dropping by :)
I've still got plenty to learn myself, but I'll do my best to answer with what I know.

1. How does the vc-api test suite work?

The vc-api-test-suite applies a bunch of tests to a standardised interface. This interface is known as the "vc-api" and consists of a few HTTP end points. The API is described here. It has seperate test suites for issuing, verifying (and for the 'holder' too, but don't worry about that for now). The issuer tests are defined in here for example.

To use the test suite, we need OA to use the VC-API. That is the 'wrapper' I was talking about. It is a thin wrapper around OpenAtttestation to implement the VC-API. For instance, posting a credential to /credential/issue will attempt to call OA'swrapDocument then signDocument on it and return the result with 201. It will give a 400 code on error.

2. You mentioned about VC data model. Is the VC data model referring to the wrapped version of an OA document?

Nothing to do with OA's wrapDocument! The VC data model is the W3C spec here. OpenAttestation V3 docs are very close to satisfying this data model.

3. You mentioned about already having a simple...

See above :)

results.zip