W3C home > Mailing lists > Public > public-credentials@w3.org > August 2021

RE: Diagrams for VC HTTP API work [was Re: [AGENDA] VC HTTP API Work Item - August 17th 2021]

From: Joosten, H.J.M. (Rieks) <rieks.joosten@tno.nl>
Date: Tue, 17 Aug 2021 07:33:06 +0000
To: Joe Andrieu <joe@legreq.com>, Credentials Community Group <public-credentials@w3.org>
Message-ID: <fa8723a7ce4b4fa9aeba992c8cf8956d@tno.nl>
Hi Joe,

Looking at the VC Issuance Sequence diagram, it seems that the issuer role is not simply issuing a credential, but (in step 2) it also seems to send a presentation-request like message to the holder app, resulting in a VP that is verified in steps 9-11. I also get the impression that a new VC is minted based on the verification result.

Verification<https://www.w3.org/TR/vc-data-model/#dfn-verify> however is a test on the structure of data, whereas validation<https://www.w3.org/TR/vc-data-model/#dfn-credential-validation> tests the validity of such data for a particular (set of) purpose(s), which also has to do with meaning. Specifically, data that fails particular verification tests can still be valid for some purpose. For example, a passport that has recently expired may still be valid to identify its bearer, e.g. to allow him to enter a building. The converse may also be true: data that satisfies timeliness tests, e.g. hasn't expired yet, may still not be valid for for specific purposes. For example, in order to apply for a Chinese (tourist) visa, the passport must not expire within 6 months of arrival in China.

Since verification is a test on the structure of data, I can see verification-technology being standardized and being made part of some SSI-infrastructure. This is not the case for validation-technology, because validation requires business knowledge (i.e. an answer to the question "is the VP valid?" (i.e. are the risks of using this data in the argument for deciding whether or not to issue the credential acceptable for the party that will be issuing the credential).

Does it make sense to consider a specific 'validator' role - distinct from the 'verifier' role?


From: Joe Andrieu <joe@legreq.com>
Sent: maandag 16 augustus 2021 23:16
To: Credentials Community Group <public-credentials@w3.org>
Subject: Diagrams for VC HTTP API work [was Re: [AGENDA] VC HTTP API Work Item - August 17th 2021]

Howdy folks,

Based on conversations with the use case team, I've put together the attached diagrams, illustrating a minimum conceptual model based on the USCIS Green Card use case, as implemented using CHAPI.

I'm sure this model is lacking some elements for folks who have a slightly different configuration. I chose this use case because it is the one I'm most familiar with, making it easiest to be complete. I'd like to speak to folks with different scenarios and see if we can't come up with a variation that covers your requirements.

A few notes.

1. There are sequence and communications diagrams for both issuance and verification, plus a class diagram.

2. All of the components are "owned" by one of the core roles (Holder, Issuer, Verifier) are color coded.

3. The class diagram aggregates the method calls on each of the lifelines in the other diagrams.

4. The components are
  a. Holder The entity who holds the VC once issued and later presents it for verification.
  b. Holder Application The software or service that allows holders to manage their credentials. Often called a wallet. For symmetry, it could be called a Holder Service.
  c. Storage Service The software or service that actually stores VCs long term (on behalf of the holder)
  d. Issuer Role The website or software that provides issuing functionality to a holder on behalf of that issuer)
  e. Issuer Service Software or service that actually signs VCs and VPs) This component is used by both the issuer  (to mint VCs) and the holder (to create VPs for presentation)
  f. Verifier Role The website or software that uses a Verification Service as part of its decision making process for providing services to holders.
  g. Verifier Service The software or service that verifies VCs and VPs by checking proofs and checking status.

Note that there are more components than had previously been itemized in the vc-http-api work, because storage and status services had not be broken out as distinct capabilities. This sometimes caused confusion. Some implementations will bundle all or some of these components into a full-stack credential platform, however, the APIs, IMO, must support interoperability between these components. So, yes, a Holder Application will need to have a way to get VPs created. Instead of assuming that's a subcomponent of the Holder Application, breaking it out illustrates, for example, the API that might be useful at an Issuer when acting on behalf of a holder.

5. The class diagram is a distillation across all component instances in all sequence and communications diagrams, so it starts to suggest an API for each of those components. Since I have only modeled one scenario's issuance and verification, I expect the API is not full coverage. However, it is nice to see that I only have the messages indicated by the USCIS, CHAPI-based flow (where, for example, VCs are always delivered in VPs, so the Verifier Service doesn't need a Verify VC method).

6. The message names are chosen for logical consistency in "normal English"; they should likely be turned into camel case or something and we can have a bikeshed festival.

7. The dance between roles and services matches the architecture for the services operating SaaS style for a front-end that is providing the "role" functionality on behalf of the actual entity in that role. For example, the USCIS plugfest had mock-up USCIS websites that beneficiaries interacted with, and which, in turn, it interacted with Issuer services. It is understood that the enterprising organization could run both the role and service software using its own bespoke custom software.

8. It is worth noting that all of the user tasks from the VC Use Cases document, except two, are accomodated. https://w3c.github.io/vc-use-cases/#user-tasks In particular, "move claim" and "amend claim" don't really have much support: neither the spec nor any implementation I know of addressed these use cases. "Move claim" feels like it gets addressed by "store", "retrieve", and "delete". Notably, the "delete" is not in the VC use case document, but probably should be; It almost certainly needs to be a feature in at least the storage service API. For the "amend" claim, I believe the only real way to do that today (given cryptographic proofs) is to revoke and re-issue. FWIW, I think we should remove "move" and "amend" the VC Use Cases document.

9. The "revoke" capability is not modelled yet, but it makes sense to add it to the status service (we just have the verifier service checking status). I just didn't build out that diagram.

That's it for now.

Plenty of fodder for discussion.

Comments and feedback welcome.


On Sun, Aug 15, 2021, at 4:41 PM, Manu Sporny wrote:
VC HTTP API Work Item - August 17th 2021
Time: Tue 4pm ET, 1pm PT, 10pm CET, 8am NZDT (Wed)

Text Chat:

Jitsi Teleconf:

Duration: 60 minutes



1. Agenda Review, Introductions (5 minutes)

2. VC HTTP API Renaming Poll Reminder (5 minutes)

3. Simple Majority Objection w/ GNAP-KBAT (30 minutes)

4. Feature Scoping (15 minutes)

5. Pull Requests (5 minutes)

-- manu

Manu Sporny - https://www.linkedin.com/in/manusporny/
Founder/CEO - Digital Bazaar, Inc.
News: Digital Bazaar Announces New Case Studies (2021)

Joe Andrieu, PMP                                                                              joe@legreq.com<mailto:joe@legreq.com>
LEGENDARY REQUIREMENTS                                                        +1(805)705-8651
Do what matters.                                                                            http://legreq.com<http://www.legendaryrequirements.com>

This message may contain information that is not intended for you. If you are not the addressee or if this message was sent to you by mistake, you are requested to inform the sender and delete the message. TNO accepts no liability for the content of this e-mail, for the manner in which you use it and for damage of any kind resulting from the risks inherent to the electronic transmission of messages.
Received on Tuesday, 17 August 2021 07:33:24 UTC

This archive was generated by hypermail 2.4.0 : Thursday, 24 March 2022 20:25:21 UTC