w3c/vc-imp-guide

Verifiable Credentials Implementation Guidelines

vc-imp-guide's Issues

Add guidance to prevent unauthorized credential reuse by verifiers

Original issue: w3c/vc-data-model#203

If a credential may be delegated from one holder to another, what prevents a verifier from taking a presentation and pretending they are a delegated holder?

Add a section to the implementation guide about preventing unauthorized credential reuse by verifiers. To put it another way, add recommended mechanisms to prevent the stealing of credentials by verifiers (and impersonation of the subject).

Example existing mechanisms:

• audience restriction (from the OAuth2 Threat Model and Security Consideration document)
• Use of the "subject only" Terms of Use property
• others

Add sections outlining benefits of different syntax + proof formats

Decision from F2F Barcelona:
A proponent for each format will write a section in the implementation guide describing the format.

• JSON-LD proofs (Manu)
• JSON-LD + JWT and JSON + JWT (Oliver)

To do:

• @msporny will write the section on LD Proofs
• @awoie will write the section on JSON-LD + JWT and JSON + JWT
• @ken-ebert will write the section on ZKPs

Section 7.2 Issues

There is the table in 7.2 Benefits of JSON-LD and LD-Proofs where it states and X in the Designed to easily support experimental signature systems field, as JWTs allow usage of non-registered signatures to be used, via Collision-Resistant Name.
Also has an X in the Canonicalization requires only base-64 encoding for JWT, this is also not correct

Another example (or a clarification) needed for example given for Predicate Proofs

In the section on Predicate Proofs in chapter 11, this document states:
"Using zero-knowledge methods, predicate proofs can be generated by the holder at the time of presentation without issuer involvement. For example, a verifiable credential with the claim birthdate can be used in a verifiable presentation to prove age-over-18. The same credential could then be used in another presentation to prove age-over-25, all without revealing the holder's birthdate."

I understand that a zero knowledge proving system allows a holder to demonstrate that she knows a claim (which is authenticated by an issuer) and that she used that claim inside a defined and known computation to derive some other value. She will moreover be able to prove to a verifier that the new value was indeed correctly derived from the claim, without revealing the claim itself.

However, I think that this does not justify the given example of proving age-over-25 based on proven knowledge of birthdate. The problem I see that for this particular calculation, the holder needs to use the current date (or at least the date on which the age-over-25 claim is to have value TRUE). That current date cannot be included in the claim that she received from the issuer, because we assume no involvement of the issuer. Therefore, the current date must originate from the holder itself. But that means that in order to accept the age-over-25 claim, the verifier must trust the holder. And this obviously defeats the purpose of the claim.

Perhaps my thinking above is wrong. In that case, I think that a clarification would be helpful also for other readers. Please note that the same example is used at other places as well, for example section 12.3. Figure 11 in the VC Data Model suggests the same example.

If I am right, however, we need to find another example to demonstrate the power of ZKPs for real-life applications of VCs.

Verifiers MUST NOT trust visual indicators on apps they do not control

From this article:

https://arstechnica.com/information-technology/2022/05/digital-drivers-license-used-by-4m-australians-is-a-snap-to-forge/

There is this misguided notion that I've heard many times now... that the Holder App itself has a visual watermark that let's the verifier visually inspect that the app is a legitimate mDL app. I've heard government representatives from US states as well as some sales people from vendors in the space say this. We all know that digital images that you visually inspect are NOT a trustworthy security feature... even if you use the phone's tilt sensor to turn it into a "digital hologram".

We should state that Verifiers MUST NOT trust visual indicators on apps they do not control and ideally any visual indicator on their app is driven by some sort of cryptographic security process.

add caveats about impacts of group deadlines

for Status of the Document section

Use of aliases and extending VCs

The data model provides no guidance as to whether the short form aliases for properties should be used, may be used or must be used. Is it OK to use IRIs throughout? In addition, if I extend a VC with some new terms, is it OK to only use IRIs and to not produce a new @context value? Or does a new type of VC require a new @context value

Reference or attach generic (not-credential) data in credential

Moving from VCWG issue 136 (w3c/vc-data-model#136) based on decision at Barcelona F2F

Add section describing value of JSON-LD

The intention is that PR w3c/vc-data-model#1270 be closed on the VCDM repository and that text be added to the implementation guide instead.

Verifier perspective needed on subject-holder relationships

Section C of the VCDM (subject-holder relationships) informs readers that IF (a particular subject-holder relationship exists), THEN (some specific things can be done).

In practice, though, verifiers need to establish whether or not a particular subject-holder relation exists, which implies that they cannot rely on whether or not they can do the specific things that they could if they knew that relationship to exist.

And obviously, it is not true that if "some specific things can be done", then "the particular subject-holder relationship exists".

I suggest that section C is rewritten from the verifier perspective, i.e., the sections should inform how verifiers can learn whether or not a particular subject-holder relationship actually exists

examples allow copying non-JSON elements

The examples in the implementation guide should allow for the same magic as the data model where non-JSON elements such as comments can't be selected.

Add additional reasons to JSON-LD+LD-Proofs section

Making some notes from discussion had earlier today with @dlongley, where he stated something to this effect:

LD proofs allow data translation, remove redundant bloat, and keep the data model layer separate from the signature layer

JWTs mix the data model and the signature layer, you can't translate data formats (can't do CBOR-LD/other things and keep signatures), and you need a full copy of the serialized version of what you signed kept around ... which becomes worse the more the more signatures you add

The fact that you can sign an actual graph with LD proofs means you can actually selectively disclose relationship data down to the most granular level ... a single triple, you can't do that with anything else

Can't do that with JWT ... unless you reinvent a graph format... and ... ultimately, you need JSON-LD processing (or something like it) to do the above ... which is why you can't remove that particular operation and claim there is equivalence between the two mechanisms.

Therefore graph normalization is a fundamental difference. it's a trade off. can you represent your data as a graph, can you translate between data formats / representations without losing a signature, and can you aggregate multiple signatures, etc. without bloat? You can only do that if you have a graph representation for your data and some kind of canonicalization algorithm that can be reapplied to different data that produces the same result.

variable vocab is being discussed as if invariable

We don't want them to have to worry about terms being redefined
in unexpected ways. That way their software can inspect only the
<code>@context</code> values and then be hard coded to understand
the meaning of the terms.

This basically says, "we want them to act as if the definition of those terms is immutable" even as we're saying "the definition of these terms might change."

That's not OK!

Anything that's being hard-coded SHOULD (and I really want this to be MUST) be based on something that's immutable. The meaning of schema:name might change between VC creation and verification, and that's a problem.

If the @context were hashlinked, that might be a solution.

Or the example could be based on a static, immutable vocab that we include with this guide.

See comment threads in #18

Suggestions on how to do progressive trust or graceful degredation

Issue added from discussion in Barcelona F2F: https://www.w3.org/2019/03/05-vcwg-minutes.html
add suggestions on how to do progressive trust or graceful degredation

See discussion in w3c/vc-data-model#222

Multiple times

The proposed ISO mDL standard recognised 4 times for a credential (in this case a driving license):

1. the time the original credential was issued
2. the time the electronic credential was issued
3. the time the electronic credential becomes invalid
4. the time the original credential becomes invalid

It is recognised that this could be a common requirement for many VCs, e.g. a passport VC, a vaccination record, a European Health Card etc.

It would be very helpful if we could provide text in the guide recommending how these 4 times should be encoded as VC properties.

Clarification needed regarding "the subject of a VC"

In the VCDM, the term 'subject' is only defined in relation to claims, not in relation to credentials. Since a VC is a (non-empty) collection of claims, the phrase "subject of a VC" is generally indeterminate - it only makes sense if the VC contains a single claim.

I have witnessed many discussions in which people have assumed that every VC does have a subject, and it causes lots of confusion, for example between people that are attempting to author a paper in the context of RWOT on 'holder binding'.

It would really help if the VCDM were very clear in this respect, but it currently is not: the phrase "subject of the [verifiable] credential" appears multiple times (even in the definition of "holder"), and it causes various people to argue that it is ok to talk about "the subject of a VC".

I suggest to

• change the replace all occurrences of "subject of the credential" and "subject of the verifiable credential" by texts that state what actually is the case, e.g., "subject of a claim in the (verifiable) credential".
• replace the definition of 'subject' with something like "The (single) entity to which a given set of coherent data relates/pertains. In a VC, every claim has a subject (VCs themselves do not)."

Add section on ZKPs and where to find more information

The current document is pretty light on ZKPs and Brent offered to add some text about it.

Selective Disclosure

The current guide suggests two ways of performing selective disclosure.
The mobile driving license ISO working draft specifies a third way: release one VC where all the subject property values are hashes. The holder then releases the VC with the clear contents of the properties s/he wants to disclose, and the verfier can compute the hash to validate the value is correct. Shall we add this as well?

Are there any open-source reference implementations of this spec?

We are trying to implement a digital infrastructure for education and skilling sector in our country. Just wondering if there are any open-source implementations of this specification. Any industry sector would do. Any references would be greatly appreciated. Thanks

Add section pointing to the test suite and implementation report.

We need a section that links to the test suite and also that allows developers to judge which existing implementation best fits their needs. https://w3c.github.io/vc-test-suite/implementations/

Game vault verification code

I need a verification code for game vault

all vocab links should be versioned

Please note that my points are not philosophical. The text discusses the importance of using an un-changing vocab for VCs, and then uses a changing vocab for the example. The example would be much better (and more realistic) if it used versioned URIs for all schema.org terms, or switched to using an un-changing (i.e., already and more cleanly versioned) vocab.

Originally posted by @TallTed in #54 (comment)

We need to do a full review of this doc, and change most to versioned (especially, but probably not only, schema.org links).

Ensure that credential storage should be encrypted using strong entropy sources

From this article:

https://arstechnica.com/information-technology/2022/05/digital-drivers-license-used-by-4m-australians-is-a-snap-to-forge/

One of the security failures above was that the app used a 4-digit PIN to encrypt the driver's license. I would hope that those doing client-side encryption for digital wallets would use an encryption key from a proper entropy source. Granted, if the credential was digitally signed in the first place, it couldn't be tampered with, but we should be treating all data in a digital wallet as something you don't want falling into the hands of anyone that has access to the data on your phone (like your backup provider). There is also the question around proper protection of private key material. I know that some of the digital wallets in our space don't protect their private keys at all, and that's a problem that's going to come back and bite our community.

Credential storage should be encrypted using strong keys from cryptographically safe entropy sources. Private keys should be hardware-backed if at all possible, and if not, encrypted when not in use (using strong keys from cryptographically safe entropy sources).

@context value ordering

The data model says that @context values must be in order, but as a JSON implementor I do not appreciate the reason nor requirement for this. An explanation in the implementation guide is needed

Add section detailing how to author a new VC (semantics and schema)

See #9.

preview/diff magic isn't active on vc-imp-guide

None of the active PRs have the preview / diff links that are seen on the other VCWG repos. Can this be activated?

Be suspicious of QR Code flows that don't also check digital signatures at some point

From this article:

https://arstechnica.com/information-technology/2022/05/digital-drivers-license-used-by-4m-australians-is-a-snap-to-forge/

One of the security compromises had to do with the QR Code being trusted in some way without a digital signature being used. It's unclear what, if any, protection mechanism was in place for the QR Code, but what is clear was that it was not a digital signature that was being verified. Or if it was, the signature was created client-side and was not being checked for validity or revocation by the verifier.

Implementers should strive for digitally signed QR Codes. For example, every QRCode in the TruAge age verification program is a unique, digitally signed VC encoded as CBOR-LD and displayed as a QR Code. The verifier must check that the issuer is valid and the signature is valid before processing the data. QR Codes that don't result in a digital signature check happening at some point in the process are asking for trouble. We should provide some guidance to implementers that note that the use of QR Codes w/o some sort of digital signature validation at some point in the process is dangerous.

Specify that VCs that are not signed are not VCs

Based on this security compromise:

https://arstechnica.com/information-technology/2022/05/digital-drivers-license-used-by-4m-australians-is-a-snap-to-forge/

One of the issues in the compromise described by the article above is that there are no digital signatures on any of the data transmitted by the mobile driver's license app. Verifiable Credentials would've prevented this first error because VCs have to be digitally signed to be trusted. At least, we hope that's what people out there are doing. The takeaway for us is to clearly outline this in the implementation guide -- it's not a VC if it's not signed by an issuer, there is no security if it is not signed.

It's important for us to provide guidance to implementers that VCs that are not signed are not VCs and are not safe to use for any critical task. An unsigned VC is effectively self-asserted information.

Reference or attach credential in another credentials

Moved from VCWG as per decision at VCWG Barcelona f2f March 2019. See w3c/vc-data-model#135.

Determine how/if WebAuthn will work with VCs

Moving issue from the VCWG Data Model repo. see w3c/vc-data-model#162

Add section on related work

Include references to digital wallets, secure data hubs, identity hubs, agent communication, etc.

Add standard (generic) JSON Schema for implementors to validate their verifiable credentials (see pending PR #17)

Consensus at the Barcelona f2f meeting on Mar 4 2019 was to add a JSON schema for the VC data model, to help implementors.
(Original issue: w3c/vc-data-model#128)

Add section on ZKPs and where to find more information

Add section on ZKPs and best practices.

Verification section is incomplete

The verification section has only placeholders, no real content