§ Decentralized Identity Interop Profile v2

Profile Status: Draft

Latest Draft: https://dutchblockchaincoalition.github.io/DIIP

Editors:: Niels Klomp (Sphereon); Timo Glastra (Animo Solutions); Maaike van Leuken (TNO)
Contributors:: TODO

Special Thanks:

This profile is based on a lot of work done by the Decentralized Identity community, given this profile is largely based on and uses sections of the DIF JWT VC Presentation Profile, we would like to place special thanks to the editors and contributors of that profile.

Participate:: GitHub repo; File a bug; Commit history

§ Abstract

The Decentralized Identity Interop Profile, or DIIP for short, defines a set of requirements against existing specifications to enable the interoperable issuance and presentation of Verifiable Credentials (VCs) between Wallets and Verifiers.

This document is not a specification, but a profile. It outlines existing specifications required for implementations to interoperate among each other.

The main objective of this interop profile is to allow for easy adoption, through the choice of standards that are relatively easier to implement.

The profile uses OpenID for Verifiable Presentations (OID4VP D20) as the base protocol for the request and verification of W3C JWT VCs as W3C Verifiable Presentations (VC Data Model v1.1). A full list of the open standards used in this profile can be found in Overview of the Open Standards.

§ Audience

The audience of the document includes Dutch organisations aiming to adopt Decentralized Identity, and Verifiable Credential implementers and/or enthusiasts. The first few sections give an overview of the problem area and profile requirements for DIIP. Subsequent sections are detailed and technical, describing the protocol flow and request-responses.

§ Status of This Document

The status of the Decentralized Identity Interop Profile v2.0.0 is a DRAFT specification under development.

§ Description

The VC Data Model v1.1 specification defines the data model of Verifiable Credentials (VCs) but does not prescribe standards for transport protocol, key management, authentication, query language, etc. As a result, if implementers decide which standards to use for their implementations on their own, there is no guarantee that other companies will also support the same set of standards.

This document aims to provide a path to interoperability by standardizing the set of specifications that enable the presentation of JWT VCs between implementers. Future versions of this document will include details on issuance and Wallet interoperability. Ultimately, this profile will define a standardized approach to Verifiable Credentials so that distributed developers, apps, and systems can share credentials through common means.

§ Scope

In this section, the scope of the interoperability profile is discussed.

§ Within Scope

This document is currently scoped for the presentation of VCs between the Wallet and the Verifier. The Wallet is a native mobile application. The following aspects are in scope:

Data model
Protocols to request presentation of VCs, including query language
User authentication layer using Self-Issued ID Token
Mechanism to establishing trust in the Decentralized Identifier via Domain Linkage
Identifiers of the entities
Revocation of VCs
Cryptographic signature suites

§ Out of Scope

The following items are out of scope for the current version of this document:

Issuance of the VCs
Advanced concepts in the VC Data Model v1.1: credentialSchema (credentialType is used instead), refreshService, termsOfUse, evidence, and Disputes.
Selective disclosure and unlinkability
Zero-Knowledge Proofs
Non-native Wallets, such as web applications, PWAs, etc.

§ Future Work

DIIP v1 describes technologies that are relatively easy to implement. However, a future version will include more advanced standards.

§ Structure of this Document

First, this profile outlines open standards required to be supported. Then, it describes the considerations for choosing these open standards. We discuss the standards specific to issuing or presentation separately. This document then lists security and privacy considerations, use cases and examples, implementations and testing.

§ Terminology

This section consolidates in one place common terms used across open standards that this profile consists of. For the details of these, as well as other useful terms, see text within each of the specification listed in References.

Decentralized Identifier: An identifier with its core ability being enabling Clients to obtain key material and other metadata by reference, defined in DID Core.
End-User: Human Participant.
Holder: An entity that possesses or holds Verifiable Credentials and can generate Verifiable Presentations from them as defined in VC Data Model v1.1.
Issuer: A role an entity can perform by asserting claims about one or more subjects, creating a verifiable credential from these claims, and transmitting the verifiable credential to a Holder, as defined in VC Data Model v1.1.
OpenID Provider (OP): OAuth 2.0 Authentication Server implementing OpenID Connect Core and OID4VP D20
Presentation: Data derived from one or more Verifiable Credentials, issued by one or more Issuers, that is shared with a Verifier.
Relying Party (RP): OAuth 2.0 Client application using OpenID Connect Core and OID4VP D20 in SIOPv2 D13. Synonymous with term Verifier.

Self-Issued OpenID Provider (Self-Issued OP): An OpenID Provider (OP) used by an End User to prove control over a cryptographically verifiable identifier such as a Decentralized Identifier.
Verifiable Credential (VC): A set of one or more Claims made by an Issuer that is tamper-evident and has authorship that can be cryptographically verified.
Verifiable Presentation (VP): A Presentation that is tamper-evident and has authorship that can be cryptographically verified.
Verifier: An entity that receives one or more Verifiable Credentials inside a Verifiable Presentation for processing. During presentation of Credentials, Verifier acts as an OAuth 2.0 Client towards the Wallet that is acting as an OAuth 2.0 Authorization Server. The Verifier is a specific case of OAuth 2.0 Client, just like Relying Party (RP) in OpenID Connect Core.
Wallet: An entity that receives, stores, presents, and manages credentials and key material of the End User. During presentation of VP(s) using OID4VP D20, the Wallet acts as an OAuth 2.0 Authorization Server towards the Verifier that is acting as an OAuth 2.0 Client. During user authentication using SIOPv2 D13, the Wallet acts as a Self Issued OpenID Provider towards the Verifier that is a specific case of the Relying Party in OpenID Connect Core.

§ Profile

In this section, we describe the interoperability profile.

The rationale behind the profile is to increase adoption through making the profile as easy to adopt as possible. DIIP allows for the implementation of simple Decentralized Identity use cases, with less effort to implement the profile as opposed to other profiles. This boils down to using technologies that are well-specified and already have wide adoption. In the sections below, we first give an overview of the standards included in the profile, then we describe the design choices.

§ Overview of the Open Standards

OID4VCI D12
OID4VP D20
SIOPv2 D13
Presentation Exchange v2.0.0
W3C Verifiable Credentials JWT (VC Data Model v1.1)
did-web and did-jwk
ES256
Status List 2021 (First public draft)

§ DID Methods

Implementers are required to support did:web and did:jwk. It does not require mandatory support for did:ion, unlike the JWT VC Presentation Profile which we use as a basis for the Presentation.

§ did:web Method

Support for the did-web as mentioned in the JWT VC Presentation Profile is required. did:web supports key rotation, but not key history.

§ Removal of did:ion Method

We decided to exclude blockchains from DIIP v1, as we wanted to keep the amount of requirements to a bare minimum. This means that DIIP v1 also does not include blockchain-based Decentralized Identifier methods. Hence, did-ion support is not required in this profile, contrary to the JWT VC Presentation Profile. Of course implementations are free to support the did-ion. One of the drawbacks of not using blockchain-based DID methods of course is that this means that key history as well as rotations are not really supported in an interoperable way. This is mostly a problem for organizations, since Natural Persons would never use ledger-based DID methods anyway.

§ Addition of did:jwk Method

DIIP requires the implementation of did-jwk, given this DID method is simply an encoding of a JSON Web Key. As such it also supports X.509 certificates. This is a very common way to encode keys and certificates in current systems, thus we believe it is important to support this method. A did:jwk can either have a Certificate Chain incorporated (x5c) in the DID Document or linked as a URL (x5u).

§ Signature Scheme

When working with JWTs, it is recommended to work with the following two signature algorithms: ES256 and RS256. The first is based on the elliptic curve discrete logarithm problem, whereas the latter is based on the integer factorization problem. Elliptic-curve cryptography can achieve the same security as RSA with much shorter keys. Therefore, DIIP supports ES256 (ECDSA using P-256 and SHA-256).

§ Credential Format

We wanted to work with the broadly known VC model. Proof formats that are actively being used to issue verifiable credentials according to the VC model are:

JWT-VC. External proof. JWT-VC has a high Technology Readiness Level (TRL) and are widely adopted in other existing standards. Compatible encoding schemes are JSON and JSON-LD. DIIP v1 requires JSON, in future versions JSON-LD will also be supported.
LDP-VC. Embedded proof, proof is included in the data.

For more information, see VC Data Model v1.1.

§ Revocation Algorithm

Status List 2021 (First public draft) is a bit string, where each credential has a position in the list. Based on the value of the bit, the credential is either revoked or not. The status list is highly-space efficient, while providing herd privacy.

§ Issuance

The issuance of credentials from the Issuer to the Holder's Wallet is done along the OID4VCI D12 specification. We follow the JWTC VC Issuance Profile, with the alterations mentioned above in Profile. In addition to the ‘base’ profile, we use OID4VCI.

§ OID4VCI

OpenID for Verifiable Credential Issuance OID4VCI allows for secure direct presentation of the credential from the Holder (End-User) to the Verifier (Relying Party), without involvement of the Issuer.

§ Presentation

The presentation of claims from the Holder's Wallet to the Verifier is done along the OID4VP D20 and Presentation Exchange v2.0.0 specifications. For DIIP we follow the JWT VC Presentation Profile, as this profile is supported by big-tech companies, but with some changes, as were described above in Profile. We now describe the presentation-specific standards included in DIIP.

§ SIOP

Using SIOPv2 D13, Holders can authenticate themselves with self-issued ID tokens and present self-attested claims directly to Verifiers (Relying Parties). The OpenID provider (OP) as specified in OpenID Connect Core are under the subject’s local control.

§ OID4VP

Using OID4VP, the Holders can also present cryptographically verifiable claims issued by third-party Issuers, such that the Verifier can place trust in those Issuers, instead of the subject (End-User).

§ Presentation Exchange

Presentation Exchange v2.0.0 defines two steps that have to be executed before the Holder can present a proof to the Verifier: the Verifier first has to describe proof requirements, then the Holder has to describe a submission of proof aligning with those requirements.

§ Linked Domain Verification is fully optional

Contrary to the JWT VC Presentation Profile, the use of Linked Domain Verification is fully optional. If not present for a party, the other party should not raise an error. Although we believe Linked Domains are a nice optional trust anchor, we also wanted to keep the DIIP v1 profile as Simple as possible at this point in time. Focusing on technical interoperability first and governance interoperability later.

§ Security Considerations

The same security consideration applies to DIIP as to the JWT-VC Presentation Profile. It is important to note that Cross-device SIOP is susceptible to a session phishing attack, where an attacker relays the request from a good Verifier to a victim and is able to sign in as a victim. Implementers MUST implement mitigations most suitable to the use-case. For more details and concrete mitigations, see section 15 Security Considerations in SIOPv2 D13.

§ Crypto Agility

JWT-VC provides crypto agility, which allows for replacing the signature scheme when desired. Crypto agility is important for the migration to post-quantum signature schemes.

§ Privacy Considerations

§ Selective Disclosure

JWT-VC does not allow for selective disclosure. Selective disclosure can however still be provided on a governance level.

§ Predicates

JWT-VC does not allow for generating predicates. Predicates can however still be provided on a governance level.

§ Verifier Unlinkability

Verifier unlinkability is not achieved, as the signature scheme ECDSA is not capable of creating unlinkable signatures such that colluding verifiers can link verification processes together.

§ Observability

The Verifier has the possibility to observe the revocation status beyond the presentation, because they know the position of the credential in the bitstring.

§ Use-Cases

TBD

§ Examples

§ Implementations

At time of writing, two wallets are compatible with DIIP v1, namely the Sphereon and Animo wallet.

§ Testing

TBD

§ Test Vectors

TBD

§ References

§ Normative References

DID Core: Decentralized Identifiers (DIDs) v1.0. Manu Sporny, Dave Longley, Markus Sabadello, Drummond Reed, Orie Steele, Christopher Allen. 2021.08. Status: W3C Proposed Recommendation.
OID4VCI D12: OpenID for Verifiable Credential Issuance (Draft 12). Torsten Lodderstedt, Kristina Yasuda, Tobias Looker. 2023.11.26
SIOPv2 D13: Self-Issued OpenID Provider v2 (Draft 13). Kristina Yasuda, Michael B. Jones, Torsten Lodderstedt. 2023.11.28 Status: Standards Track.
OID4VP D20: OpenID for Verifiable Presentations (Draft 20). Oliver Terbu, Torsten Lodderstedt, Kristina Yasuda, Adam Lemmon, Tobias Looker. 2023.11.29 Status: Standards Track.
VC Data Model v1.1: Verifiable Credentials Data Model v1.1. Manu Sporny, Dave Longley, David Chadwick. 2021.08. Status: W3C Proposed Recommendation.
JWT VC Presentation profile: JWT VC Presentation Profile. Daniel McGrogan, Kristina Yasuda, Jen Schreiber.
Presentation Exchange v2.0.0: Presentation Exchange v2.0.0. Daniel Buchner, Brent Zundel, Martin Riedel, Kim Hamilton Duffy.
did-web: did:web Method. Oliver Terbu, Mike Xu, Dmitri Zagidulin, Amy Guy. Status: Registered in DID Specification Registry.
did-jwk: did:jwk Method. Status: Registered in DID Specification Registry.
Status List 2021 (First public draft): Status List 2021 0.0.1 Predraft. Manu Sporny, Dave Longley, Orie Steele, Mike Prorock, Mahmoud Alkhraishi. 2022.04. Status: Draft Community Group Report.

§ Non-Normative References

OpenID Connect Core: OpenID Connect. Nat Sakimura, John Bradley, Michael B. Jones, Breno de Medeiros, Chuck Mortimore. 2014.11. Status: Approved Specification.
did-ion: did:ion Method.
JWP: JSON Web Proof. Jeremie Miller, David Waite, Michael B. Jones. Status: Internet-Draft.
JPA: JSON Proof Algorithms. Jeremie Miller, Michael B. Jones. Status: Internet-Draft.
OIDC Registration: OpenID Connect Dynamic Client Registration 1.0 incorporating errata set 1. Nat Sakimura, John Bradley, Michael B. Jones. 2014.11. Status: Approved Specification.
Well Known DID: Well Known DID Configuration. Daniel Buchner, Orie Steele, Tobias Looker. 2021.01. Status: DIF Working Group Approved Draft.
Linked Domain Verification: JWT-VC Presentation Profile Linked Domain Verification. Daniel McGrogan, Kristina Yasuda, Jen Schreiber.