RE: the intersection between Swagger-style APIs and SSI/decentralized identity

>While I'm the one who wrote this first draft and posted the proposal, this wasn't really my idea.
>It was specifically requested by the U.S. Department of Homeland Security, to have common APIs
>which the different participating startups of the Silicon Valley Innovation Program (SVIP) should agree on.

I wanted to provide some context, background and rationale for the scope of the request that DHS made to the 8 portfolio companies we currently have under contract who are building out DID and VC based systems to address the following problem sets:


  1.  Digital Issuance of Citizenship, Immigration & Employment Authorization
  2.  Digital Validation and Verification of Identity Documents for Travel
  3.  Digital Validation and Verification of Tribal Identity Documents for Travel
  4.  Validation and Verification of the Identity of Organizations and Organizational Delegates
  5.  Cross-Border Oil Import Tracking
  6.  Origin of Raw Material Imports (such as Timber, Steel etc.)

Two of our hard, non-negotiable requirements that need to be met by a startup working on ANY of the our problem sets above are:

  *   All APIs that are presented to the Issuer and the Verifier SHALL be publicly documented, patent free, royalty free, nondiscriminatory, available to all, and free to implement using widely available and supported programming languages.
  *   The solution SHALL incorporate, if appropriate to the particular use case, the following emerging and/or mature specifications for interoperability that have been funded, tested and/or championed by DHS:
     *   Decentralized Identifiers (Standards Development Organization World Wide Web Consortium
     *   Verifiable Credentials (Standards Development Organization W3C)
     *   JavaScript Object Notation for Linked Data / JSON LD (Standards Development Organization W3C)

Our conversation with the startups under contract referenced the following points as context and background:

  *   As an entity that sources its technology from the global marketplace, we are interested in ensuring that there exists a vibrant, competitive and diverse ecosystem of capability providers that we have access to that are building innovative capabilities on a foundation of interoperability
  *   DO NOT build anything that is government specific as that is contrary to our intent around the Interop & Open API language above.
  *   As an authoritative issuer of credentials, vendors using proprietary APIs to lock us into their infrastructure or platform is not a path to success for us. We are not going down that path again!
  *   Issuance APIs (i.e. In the VC Model the APIs between the Issuer and the Holder and the APIs between the Issuer and the Verifiable Data Registry) for us are not a differentiator.
     *   We expect companies to differentiate themselves based on the value added services ‘behind’ a standardized API
     *   We are fine with a standardized Issuance API that, from an Issuer’s perspective, allows for common baseline of functions that provide a minimum, useful and most importantly interoperable set of functions across multiple vendors with potential extensibility points that may be utilized by a vendor to differentiate themselves – As the entity that will ultimately make the decision on whether or not to buy the tech, we reserve the right to make the call on the gain to pain ratio of utilizing those proprietary extensions.

To that end, our guidance to the startups under contract was the following:

  *   We are NOT going to require that you conform to our Internal APIs or utilize APIs that we control or specify.
  *   We want you to work together to come up with an Issuer API that our Issuance infrastructure will interface with, but the specifics of that implementation is something we want you to drive forward together because it is in your common business and engineering interests – we will provide feedback as appropriate regarding our constraints.
  *   We require you to conduct the Issuer API development work in a manner that minimizes the echo chamber effect, provides global transparency and visibility to the work, and allows the broader technical community to participate in and provide feedback if they so choose --  the desire and intent here is that work becomes broadly relevant and useful enough that it ends up on the W3C standards track because the community sees value in that outcome.

Best Regards,

Anil

Anil John
Technical Director, Silicon Valley Innovation Program
Science and Technology Directorate
US Department of Homeland Security
Washington, DC, USA

Email Response Time – 24 Hours

[https://www.dhs.gov/science-and-technology/svip]


From: Markus Sabadello <markus@danubetech.com>
Sent: Tuesday, December 31, 2019 7:23 AM
To: daniel.hardman@evernym.com
Cc: W3C Credentials CG <public-credentials@w3.org>; Justin P Richer <jricher@mit.edu>
Subject: Re: the intersection between Swagger-style APIs and SSI/decentralized identity


Hello Daniel,

Thanks for the comments, I definitely agree with all the benefits of transport-independent messaging you describe!

Ironically, I remember a time when Sam Curren, Nathan George, and other leaders in the Sovrin community advocated an agent architecture where each agent "extension" would be required to publish a Swagger/OpenAPI specification for a REST API that would be called over a DID-TLS HTTPS connection (e.g. see slides 37-40 in this presentation<https://docs.google.com/presentation/d/1Xw-W2hkICy6Zy86GX2t9D6zVLHHAMDMvny1YUbzaVdQ/edit#slide=id.g20d243e53b_5_6>).

Quite some time before that, in XDI messaging, we had already designed and implemented transport-independent messages, routing, relays and mediators, message-level security, and related concepts (e.g. see this presentation<https://www.oasis-open.org/committees/download.php/56309/Message%20Forwarding%20v2.pdf>). I was very happy to see Sovrin/Indy/Aries/DIDComm then move into the same direction and adopt the same (and even more and better!) design patterns for transport-independent digital identity protocols.

Let me point out a few things about the proposed Work Item for Issuer and Verifier APIs<https://github.com/w3c-ccg/community/issues/102>:

1. While I'm the one who wrote this first draft and posted the proposal, this wasn't really my idea. It was specifically requested by the U.S. Department of Homeland Security, to have common APIs which the different participating startups of the Silicon Valley Innovation Program (SVIP) should agree on. This also means that after posting the initial proposal, I really hope I won't be the one doing most of the work on it, especially since there are definitely other people in the community who have more experience with credential issuing and verifying APIs than me.

2. As you note in your subsequent message in this thread, the proposed API is only meant for INTERNAL use, for integration of an Issuer's or Verifier's existing infrastructure with software that is able to issue and verify credentials. This is NOT about communicating between Issuers, Verifiers, and Holders. I'm sorry if I didn't make this clear enough. So I think the arguments around Bolivian farmers and power imbalance don't really apply to this. If a company or government institution wanted to use Evernym's Verity product, or Esatus' SeLF product, or any other VC software product built by this community, then there's usually a way how those products can be integrated with existing enterprise infrastructure. Such existing infrastructure may consist of legacy CRM systems, or microservices, or Kubernetes clusters, or whatever else. While I am sure that this integration of different internal components could be done with DIDComm, it could also be done in other (potentially lighter-weight) ways such as gRPC or protobuf or Webhooks or HTTP REST APIs. The benefit of standardizing those internal interfaces is to avoid vendor lock-in.

3. You are correct that the first draft of the proposed Issuer API<https://app.swaggerhub.com/apis/danubetech/credential-issuer/0.0.1> contradicts some of what I wrote above. It actually DOES have two operations right now that don't seem to be for internal-only use; they are even marked "Public APIs facing the Holder and Verifier" :) Those have already been rightfully criticized by some of my SVIP colleagues, and therefore I have added some warning text. I think those would simply be removed as soon as the Work Item is approved, since - again - protocols for interaction between Issuers, Verifiers, and Holders should really be out of scope here.

4. I imagine that in a typical deployment, calling these internal Issuer or Verifier APIs would then trigger one or more of the credential exchange protocols that are being developed by the community, such as the DIDComm issuance and presentation protocols, various OIDC flows, CHAPI, etc. How exactly that would work hasn't really been discussed yet.

5. I am also definitely interested in reducing the dependency on HTTP or Swagger. One of the objectives of this Work Item could absolutely be to define the APIs in some abstract way, and then create the Swagger/OpenAPI definition as merely one instance of that. I know the Aries community is already doing some great work to bridge/convert between DIDComm message types and Swagger/OpenAPI definitions, perhaps we can build on this!

Markus
On 12/30/19 8:54 PM, Daniel Hardman wrote:
Markus has recently proposed a work item for the CCG to develop Swagger-style APIs for issuers and verifiers. Justin has recently proposed a charter for a TxAuth group to start working on HTTP-based APIs to accomplish delegation. Digital Bazaar has advocated their RESTful Credential Handler API (CHAPI) in CCG and other circles as well. No doubt many others on this thread are aware of efforts to standardize APIs with similar style and similar intersection to the SSI/decentralized identity space.

I would like to raise a red flag about such efforts, and trigger a thoughtful follow-up conversation. I love Swagger-style APIs and have advocated them extensively at past junctures of my career, but I am concerned that they are exactly the wrong thing to standardize right now. I'll explain my concerns below, in red, and then offer an alternative path that has most of the same benefits, in blue.

1. RESTful APIs are web-only.

How do two farmers with cheap android devices in the highlands of Bolivia (or a Canadian Mounty and a speeder on a lonely highway in Yukon Territory, or friends in Frankfurt whose cell service has a brownlout, or two anti-government protesters) use RESTful APIs to transact business? If the answer is, "they subscribe to a service in the cloud so they can talk device-to-device," I hope we are embarrassed. We need something that also works over BlueTooth and email and other transports where a web server isn't a component.

By standardizing a solution that doesn't think about these scenarios, we are further marginalizing them, and we are enthroning a you-must-be-connected-and-you-can-be-surveilled model that guarantees it-isnt-a-standard FUD for any other efforts to fix the problem.

2. RESTful APIs perpetuate the PKI model that we claim to be replacing with DIDs.

Servers are authenticated in these APIs with a cert. Clients are authenticated with a session that follows from an OAuth token or an API key or basic auth material. It is possible to imagine "DID Auth" being used for a client of a RESTful API, and there have been several efforts to describe and standardize such a thing. So far, none has meaningful traction, so all APIs in the SSI space that use APIs are also allowing non-DID authentication for clients. But even if we solve the problem for the client side, nobody is proposing to solve the problem for the server side. Institutions in these APIs don't use DIDs for anything meaningful. Thus none of the decentralized properties of DIDs are brought to bear for the server side of the interaction, and any decentralized qualities of DIDs are relegated to minor, optional status for clients.

3. RESTful APIs foster a power imbalance

What if there's a standard way for institutions to be a verifier or issuer, but no way for ordinary people to be a verifier or issuer? Or a standard way for institutions to delegate, but no way for ordinary people to do it? That's effectively what APIs like the ones I mentioned above guarantee. There are multiple reasons why, including:

  *   Institutions have web servers; farmers in Bolivia don't. (Saying that they *could* is not helpful; we're just creating more adoption burden for SSI by making the tech harder and more expensive for them.)
  *   Servers can't make the first move in RESTful APIs; everything begins when a client initiates the interaction. This makes it natural for an institution (or a regulatory regime) to impose terms of service or reputation criteria on a client, and unnatural for a client to do the opposite. It's also convenient for hackers and surveillers, since they know they can catch all interactions at inception by simply listening on the server.
  *   Because these APIs are online-only, and because the server always waits for the client to make the first move, they can only be operated by those who have a 24x7x365 cloud presence. Institutions and ordinary people don't have equal access to 24x7x365 cloud capabilities.
  *   Because these APIs are secured on the server side by a cert, they can only be operated by those who have access to expensive, premium, centralized reputation. Again, institutions and people don't have equal access to this.
This is not an exhaustive list of my concerns, but I think it's enough to trigger a conversation.

Proposed Alternative

We create web APIs, but we think about them differently. We conceive of all of them as exchanges of messages that could also be accomplished over BlueTooth, email, etc. HTTP(S) is just another transport, where messages happen to be passed by HTTP POST (or GET, as appropriate). Security properties associated with the exchange are based on the control of DIDs and embodied in the messages themselves (e.g., through encryption/signing), not in a transport layer. All semantics for the interaction are conveyed by the message content. The traditional URL namespacing of Swagger can still exist, but it becomes less interesting, since the message content must be enough to convey semantics on its own (so the messages are enough in other transports). Either party can initiate an interaction. Institutions and people are actually peers.

This is the world of didcomm and application-level protocols built atop it; it's described in Aries RFC 0003<https://github.com/hyperledger/aries-rfcs/blob/master/concepts/0003-protocols/README.md>. But before folks get their hackles up about not wanting to work with Aries or DIF, note that I didn't propose that Aries protocols have to be the basis for this approach. Instead, I proposed some characteristics we need to avoid. Can we explore that assertion on its merits, without getting immediately entangled in politics?

There are already maybe 8-10 software stacks, some independent from top to bottom, that implement an "API" for issuing credentials and an "API" for verifying presentations based on the model I just articulated. These implementations are demonstrably interoperable with one another. By proposing a new work item for a Swagger API for issuance and verification, we are walking away from interoperability with these implementations, and we are incurring all of the architectural disadvantages I highlighted in red above.

What if we did this instead?

  *   Agree that for issuance and verification, the goal about payloads and sequencing for HTTP calls should be alignment between those defined in the Aries protocol and those used by people who aren't Aries-centric. This could involve give and take in either direction; I'm not proposing that it has to be done by simply adopting the Aries work.
  *   Agree not to depend on HTTP-specific constructs (e.g., HTTP headers, HTTP status codes) to signal important semantics--so the payloads could be exchanged over BlueTooth or email just as easily.
  *   Agree that, while URL namespacing gives us a nice hook into Swagger-oriented tools, all semantics required for the interaction are detectable from the payloads themselves.
Then we'd have an HTTP solution that is Swagger-compatible but not limited to HTTP. The "API" we created would be interoperable on a much broader canvas than simple web.

If we further agreed to this:

  *   Authentication of both parties in the interaction will be done on the basis of DID control, not on the basis of certs.
Then we'd also eliminate the dependence on the web's flawed PKI model, and the power imbalance of today's web. But I know this is more controversial.