DIF Grant #1: JWS Test Suite

DIF announces its first community microgrant, sponsored by Microsoft and rewarding the timely creation of a comprehensive test suite for detached-JWS signatures on Verifiable Credentials

· 4 min read

The Decentralized Identity Foundation announced recently a new mechanism for rewarding and funding work in the common interest of its membership, the DIF Grants Program. The Steering Committee ratified an addendum defining these collaborations between a specific DIF working group and a grant sponsor, and this shiny new tool sits ready to be debuted in the toolkit available to DIF community work.  DIF's work is leveling up with this new mechanism for transparently funding work that supports DIF's mission and benefits the membership as a whole.

The first such grant was initiated by Microsoft, which has a long history of collaborations in DIF. Of the various modalities described by the grant program, The Claims and Credentials Working Group will be overseeing a new work item open to all DIF members that creates and harden a JWS test suite, with this grant funding a lead editor to drive the work and keep it to a pre-determined timeline, paid upon stable and complete release.

Envelope with decorative wax seal, artfully photographed
Photo by Natasya Chen


Pamela Dingle, co-chair of the Interoperability WG, identified a recurring theme in conversations about interoperability across the great "JSON"/"JSON-LD" divide: while considerable cross-vendor, cross-stack alignment had happened over the last years to address many other aspects of credential exchange and identifier resolution, "translation issues" and varying interpretations of the JSON sections of the VC data model specification lead to divergent ways of structuring, defining, signing, and parsing VCs in JWT form.  The kinds of signature suite definitions that define Linked Data Proofs made strange bedfellows with the in-built mechanisms of JWT, which were hardened and commoditized earlier.  This results in a slightly "balkanized" landscape of VC-JWTs that make different concessions to the expectations of JSON-LD-native parsers and systems.

Initially, the idea of iterating one or more foundational specifications seemed a natural solution: a few key sections of any specification could be made more explicit, more normative, or less ambiguous. But just as the plural of anecdote is not data, so too is the plural of specifications not disambiguation. Another tack was chosen: implementers of the existing specification would come together and compare their running code to identify every difference and incompatibility, defining a test suite that interpreted the current specification.  They might still produce a list of changes they would like to see in a future specification, and that list might contain some contentious items that take a long time to align.  But in the meantime, they would have a practical roadmap to alignment and a benchmark for conformance to drive interoperability amongst each other and clarity for external interoperability.

A signature suite that spans two worlds

The specification under test in this new work item is Json Web Signature 2020 ("JWS2020" for short), a CCG signature suite that defines how the signature mechanisms and data structures native to "detached signature" JWS tokens can be parsed as Linked Data Proofs. The signature mechanisms of the JWT world and the LDP world are quite different– bridging them requires a deep understanding of both: differing security models, canonization and serialization complexities, explicit reliance on IANA registries, URDNA dataset normalization, and the like.  Advanced topics, even for this blog!

Understanding such a specification on a deep intellectual level and understanding its design decisions requires a firm grasp on all these complexities spanning two very different engineering traditions. Implementing the specification, however, should not; to be blunt, our community cannot afford such understanding gating off successful implementation, particularly if industrial adoption of decentralized identity is a shared goal.  Before the specification gets iterated, it needs to be testable, and even more implementable than it already is.

This is where a test suite offers pedagogical tool for first-time implementers, as well as a negotiation tool for seasoned veterans and large corporations managing vast roadmaps and production development pipelines. While many DIF members do not encode VCs in JWT form, this grant is clearly in the common interest because mainstream adoption will indisputably benefit from a clearer, more explicitly-defined, and definitively-testable "normative VC-JWT".

Selection Process

From 26 July 2021 to 9 August 2021, the chairs fielded applications through a google form, and submitted all valid application to github for posterity.  The selection criteria for the work item lead is as follows:

  1. familiarity with JWS mechanics and common JOSE libraries/best-practices
  2. experience with automated testing, vector design, and test scripts/suites
  3. familiarity with LD Proofs and signature suites generally
  4. familiarity with JSON/JSON-LD interop problems, at the semantic, signature-verification, and representation/parsing levels

Grantee Announcement

On 12 August 2021, The Claims & Credential (C&C) Working Group at DIF gladly announced Transmute Industries as the recipient of the first DIF Grant to provide a JWS Test Suite for Verifiable Credentials. One of the chairs, Martin Riedel, summarized the chairs' decision thusly:

Transmute has been a thought leader in the SSI space for years and uniquely fits the requirement profile laid out in the Grant announcement.

  1. Orie Steele, the CTO of Transmute, is the initiating author of, lead editor of, and main contributor to the (LD-) JSON Web Signature 2020.
  2. Transmute has a strong background in TDD and is a strong proponent of delivering test vectors with specifications in order to achieve greater implementation-level interoperability. Examples include Test Vectors in Sidetree.js and did-key.js.
  3. The company already provides integrated libraries to support (LDS)-VC and JWT-VC side-by-side, demonstrating their familiarity with both representations. See vc.js.
  4. Lastly, Transmute has a strong track record of making specifications and libraries accessible to the general public in a variety of deployed web-projects (https://did.key.transmute.industries/, https://wallet.interop.transmute.world/ and others…)

Therefore we regard Transmute Industries as the ideal candidate to provide a comprehensive JWS test suite for LDS-VC and JWT-VC and support the community interactions around this project within DIF’s C&C Group.

Next Steps

The new work item will be announced and regular meetings initiated at the 23 August meeting of C&C– if you are interested in participating, please attend and/or drop a note in the C&C slack channel.