Default vocab for credentials context v2

[tplooker]

JSON-LD defines a way to specify the default vocabulary for properties and types that otherwise do not match a term definition. Currently the credential context v1 does not make use of this feature, meaning producers of VC's must be explict in their term decelerations for all properties used, otherwise the jsonld signatures signing process will error due to the usage of a strict expansion map that requires all properties to be defined.

If instead a default vocabulary was included in a new revision of the credentials context, then the signing process would proceed and the properties without a formal term definition would be expanded with the default vocab. Take for instance the following example where the credentials context v2 would include the definition of "@vocab" set to "https://www.w3.org/2018/credentials/undefinedTerm"

{
  "@context": [
    "https://www.w3.org/2018/credentials/v2"
  ],
  "type": ["VerifiableCredential"],
  "issuer": "did:example:28394728934792387",
  "issuanceDate": "2019-12-03T12:19:52Z",
  "expirationDate": "2029-12-03T12:19:52Z",
  "credentialSubject": {
    "id": "did:example:b34ca6cd37bbf23",
    "someClaim": "A claim",
    "someOtherClaim": "Another claim"
  },
  "proof": {
     "type": "Ed25519Signature2018",
     "created": "2020-01-30T03:32:15Z",
     "jws": "eyJhbGciOiJFZERTQSIsI...wRG2fNmAx60Vi4Ag",
     "proofPurpose": "assertionMethod",
     "verificationMethod": "did:example:28394728934792387#keys-7f83he7s8"
  }
}

The properties "someClaim" and "someOtherClaim" during signing would be expanded to be https://www.w3.org/2018/credentials/undefinedTerm#someClaim and https://www.w3.org/2018/credentials/undefinedTerm#someOtherClaim which when browsed to would resolve to a page informing the user that the property is not formally defined and perhaps link to some helpful resources on how to define the term formally.

[tplooker]

Interested in feedback and thoughts from @msporny @dlongley @OR13

[OR13]

I think defaulting is probably slightly better than dropping properties, but throwing an error remains the best thing to do here.

The question remains, why would you sign anything you don't understand?

If we added @vocab it would need to come with some strong warnings, and I would want pretty much all processors to throw instead of warn...

Right now, using undefined terms is more likely to cause an error.

I'm not sure if this is an improvement but if "undefinedTerm" had a human readable definition that said "don't trust anything from this issuer until they define this term"... I supposed that would be an improvement over what we have today.

[David-Chadwick]

This is not a new problem or issue. LDAP introduced the extensibleObject object class for the same reason, so that undefined attributes could be added to an LDAP entry. Personally I dont like this. I think all VCs that cannot be fully understood should be rejected. This is because, different to LDAP entries, VCs are primarily security tokens. So having unknown information in a security token is dangerous. If you want to address this in a secure way, you should consider doing something like X.509 with its critical extension feature. With this feature, every attribute at the outer level is fully understood, even if an inner value is not. But the outer level says whether you can safely ignore inner values or not.

[OR13]

@tplooker and I had a chat about this... I can see the advantage of "making the tent bigger" by welcoming folks who don't understand why signing unknown properties might not be a good idea, weakening the security model of VCs if we can add the following to the spec:

https://www.w3.org/2018/credentials/v2 documents MAY contain properties that are defaulted to "https://www.w3.org/2018/credentials/undefinedTerm#someClaim " via the use of @vocab.

A JSON-LD Processor SHOULD throw an error when the @vocab is used.

A JSON-LD Processor MUST warn if no error is thrown and @vocab is used.

https://www.w3.org/2018/credentials/undefinedTerm leads to a definition which warns that the document containing this term cannot be trusted, and is likely experimental or test data.

Reasons this would be better than what we have today.

1. Including schema.org essentially does this already, and silently defaults undefined terms to https://schema.org/someClaim
2. Many JSON-LD VC Processors already check for https://www.w3.org/2018/credentials/v1, when they check for https://www.w3.org/2018/credentials/v2 we can require them to handle errors better, and we SHOULD.
3. Some properties like type are already dropped silently by some (not all) libraries, see Add feature to throw error when unmapped elements are dropped during processing digitalbazaar/jsonld.js#199
4. We are loosing an ability to protect users from undefined terms through a security in depth:

Throw Error > Default Member and Produce Warning > Default Member > Drop Property and Produce Warning > Drop Property.

We should start at the top, and only compromise when the risk to users is outweighed by the convenience to developers, and we are honest about which constituency we care more about in the spec.

[tplooker]

Another option we discussed, is for the default vocab to be defined as a security term that in present in both the credentials and security context and therefore making it a concept present at the JSON-LD signatures level not just a verifiable credentials concept (so instead of https://www.w3.org/2018/credentials/undefinedTerm a https://www.w3.org/security/undefinedTerm as the default vocab)

[peacekeeper]

I don't know.. https://www.w3.org/2018/credentials/undefinedTerm#someClaim feels like a contradiction to me.

This sounds like someClaim is "undefined", and I understand this is exactly the intention, but now that term can actually be expanded just fine and there won't be any warning or error, since the default vocabulary makes it all 100% correct JSON-LD, no?

If there's an undefined term in your JSON-LD, the processor should simply throw an error...

[tplooker]

@peacekeeper I understand that it appears as a contradiction.

To be clear I think in general JSON-LD processors SHOULD at least emit a warning when any property is expanded with @vocab so that this behaviour can be caught regardless.

[OR13]

If we are talking about a spec where we get to make normative requirements, I would repeat my assertions:

1. JSON-LD Processors SHOULD throw an ERROR
2. JSON-LD Processors MUST emit a warning if they don't throw an error

This is a spec related to cryptographic assertions / security... swallowing errors / warning is a terrible idea from a security perspective.... I can understand developers from untyped languages like javascript or python feeling like types are a "burden" and "slow me down / are confusing"... but frankly... they are wrong :)

types and strictness are part of good security engineering... we should not be failing open... we should be failing closed.

https://cwe.mitre.org/data/definitions/636.html

[tplooker]

This issue goes right to the core of the extensibility model for verifiable credentials. If we look at neighbouring technologies such as JWT they support what are known as public and private claims where public are recommended to be registered in the IANA registry, private are subject to collision and should be used with caution. At the moment we force users of verifiable credential technology when expressing in JSON-LD to define all their properties in some form in the JSON-LD context (note they are free to use @vocab for this too) and do not allow essentially "private claims". I understand the argument that this is a good natural force in the technology, driving producers to be precise, however I think it negatively harms the usability of the technology and also doesn't always work, e.g if I include schema.org in my context, im free to define any property and it wont error and really have no idea what is going on. If we instead allowed for the "private claims" equivalent via the inclusion of @vocab I think we strike a better balance where producers who want their credentials to use a fully defined vocab can, and those who dont won't and will suffer the consequences of poorly contexualized data.

[tplooker]

I also dont think a signed property that has been expanded to an IRI of https://www.w3.org/2018/credentials/undefinedTerm#someClaim that when dereferenced clearly states to the user "Hey this property is not formally registered so we dont have a formal definition for you" doesn't mean we are defaulting open from a security perspective IMO

[OR13]

1. @vocab being used indicates a potential security issue that at least should yield a warning.
2. @vocab is useful for folks who like seeing warnings instead of errors in their security applications.

I personally don't like seeing warnings, and I don't like setting additionalProperties:true in JSON Schema or const data: any = {} in typescript.

I don't think we should hand developers a tool which lets them accidentally poison themselves and their users... the recommendation should remain to at least warn, and best practice would be to throw.

I do think making changes to the VC Data Model in this regard would be helpful, but I would formally object to swallowing undefined terms by adding @vocab without a mandatory warning, its like turning off a lint rule that protects against prototype pollution... the only reason to do so, is because the developer is not good at security, and can't figure out how to fix the issue correctly.

[OR13]

case in point, if I add __proto__ and it gets preserved with a warning instead of a thrown error, and then some system passes that "valid VC" to another verifier systems that is vulnerable, I can actually get remote code execution on the verifier...

https://itnext.io/prototype-pollution-attack-on-nodejs-applications-94a8582373e7#:~:text=The%20Prototype%20Pollution%20attack%20(%20as,Remote%20Code%20Execution%20%E2%80%94%20RCE).

The fact that including schema.org allows for this exploit today, with no changes, does not mean we should normalize this behavior... it means we should patch the VC Data Model spec immediately to throw when @vocab is detected.

[tplooker]

I do think making changes to the VC Data Model in this regard would be helpful, but I would formally object to swallowing undefined terms by adding @vocab without a mandatory warning, its like turning off a lint rule that protects against prototype pollution... the only reason to do so, is because the developer is not good at security, and can't figure out how to fix the issue correctly.

+1 to a warning

[OR13]

perhaps we can split this up into:

1. @vocab detection MUST/SHOULD yield a warning.
2. @vocab is included in credentials/v2

I could be supportive of both, but 1 is decidedly less controversial given the disclosed issue above.

[OR13]

apparently folks are already exploiting this behavior... https://github.com/blockchain-certificates/cert-verifier-js/blob/master/src/inspectors/computeLocalHash.js#L67