JSON-LD canonicalization and unmapped keys in V2 verification


One aspect of JSON-LD canonicalization that isn’t obvious at first is that keys unmapped to Internationalized Resource Identifiers (IRIs) in a JSON-LD document are dropped when converting the JSON-LD document to RDF. In V2 verification, we added an explicit step to the verification procedure to check for unmapped keys.

This issue arises only if (1) unmapped key/value pairs are added to the document, and (2) the @vocab keyword (which uses a common prefix for all keys) is not used. In other words, changing or deleting a key/value for a mapped key would result in a different canonicalized form, thus invalidating the certificate.

How someone would attempt to exploit this is a bit obscure. For example, a recipient could add an unmapped grades key, associated with a value of straight As, and the altered certificate would pass verification because the unmapped key would be dropped. The reason it’s obscure is that the key is not part of the vocabulary for the certificate – so tools and viewers would not render or otherwise do anything with them. But a recipient could attempt to persuade someone to accept these bogus key/value pairs.

We wanted to avoid this possibility by detecting during verification if there are any unmapped keys, and if so, flag them and fail verification. To do this, we add a “fallback”/bogus vocabulary, and then check if any keys mapped to existence of keys mapped to this bogus IRI. This is not the perfect long-term solution – i.e. avoiding collisions with the fallback name indefinitely.

In future versions of JSON LD normalization, options to detect this condition will likely be available in a more first-class manner.