§ Decentralized Identity Interop Profile v4

Profile Status: Draft

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

Editors:: Eelco Klaver (Credenco); Harmen van der Kooij (FIDES Labs); Niels Klomp (Sphereon); Niels van Dijk (SURF); Samuel Rinnetmäki (Findynet)
Contributors and previous editors:: Adam Eunson (Auvo); Jelle Millenaar (Impierce Technonologies); Maaike van Leuken (TNO); Timo Glastra (Animo Solutions); Thierry Thevenet (Talao)

Special Thanks:

This profile is based on a lot of work done by the Decentralized Identity community. Given that this profile is largely based on and uses sections of the DIF JWT VC Presentation Profile, we would like to give 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 requirements against existing specifications to enable the interoperable issuance and presentation of Digital Credentials between Issuers, Wallets, and Verifiers.

Purpose	Specification
Credential format	W3C Verifiable Credentials Data Model (W3C VCDM)
Signature scheme	SD-JWT as specified in VC-JOSE-COSE
Signature algorithm	ES256
Identifying Issuers, Holders, and Verifiers**	`JWK`
Identifying Issuers and Verifiers**	did:web
Issuance protocol	OpenID for Verifiable Credentials Issuance (OID4VCI)
Presentation protocol	OpenID for Verifiable Presentations (OID4VP)
Revocation mechanism	IETF Token Status List
Trust establishment	OpenID Federation

The Normative References section links to the versions of specifications that DIIP-compliant implementations must support.

To be discussed:

Do we want to show standard/draft versions more prominently here? Pros: One can immediately see which versions are supported. Cons: Versions are specified in multiple places in the spec, and they need to be synced whenever a new version is drafted or published. The version information is already visible in tooltips. The table here doesn't contain all the DIIP requirements. One should read the Profile and Normative References sections to understand what's required.

This document is not a specification but a profile. It outlines existing specifications required for implementations to interoperate with each other. It also clarifies mandatory features for the options mentioned in the referenced specifications.

The main objective of this profile is to allow for easy adoption and use the minimum amount of functionality for a working Digital Credential ecosystem.

§ Status of This Document

The Decentralized Identity Interop Profile v4 is a DRAFT specification under development.

The latest published DIIP profile can be found at https://FIDEScommunity.github.io/DIIP/latest

§ Audience

The audience of this document includes organisations aiming to issue or verify Digital Credentials, as well as the implementers of Digital Credential solutions (Wallets and Agents).

§ Structure of this Document

The Goals section explains the design of the DIIP profile.

The Profile section defines the requirements for compliant solutions and explains the choices.

The References section defines the specifications and their versions.

The Terminology section explains the key terms used in this profile.

§ Goals

The W3C VCDM specification defines a data model for Digital Credentials but does not prescribe standards for transport protocol, key management, authentication, query language, etc.

The (OID4VCI) and (OID4VP) protocols define the interaction between Wallets and Agents but don’t specify a data model or a credential format.

This interoperability profile makes selections by combining a set of specifications. It chooses standards for credential format, signature algorithm, identifying actors, and issuance and presentation protocols. Instead of saying, “We use W3C VCDM credentials signed with VC-JOSE-COSE using ES256 as the signature algorithm, OID4VCI as the issuance protocol, and OID4VP as the presentation protocol, and OpenID Federation for trust establishment,” you can just say, “We use DIIP.”

In addition, the DIIP profile makes selections within the specifications. When a standard allows multiple ways of implementing something, DIIP makes one of those ways mandatory. As an implementer, you don’t need to fully support all specifications to be DIIP-compliant. DIIP makes these choices to accelerate adoption and interoperability – defining the minimum required functionality.

DIIP does not exclude anything. For example, when DIIP says that compliant implementations MUST support JWK as an identifier of the Issuers, Holders, and Verifiers, it doesn’t say that other identifiers cannot be used. The Wallets and Agents can support other identifiers as well and still be DIIP-compliant.

Trust ecosystems can also easily extend DIIP by saying, “We use the DIIP profile and allow mDocs as an additional credential format.” They can also switch requirements by saying, “We use the DIIP profile but use VC-DATA-INTEGRITY as an embedded proof mechanism.”

The design goal for DIIP is to ensure interoperability between Agents and Wallets in cases where device binding of Digital Credentials is not required and the Wallet doesn’t need to be trusted. Issuing, holding, and presenting certifications, diplomas, licenses, permits, etc., fit into the scope of DIIP. Using a Wallet for strong customer authentication or for sharing Person Identification Data (PID) is out of DIIP’s scope, and you should look into HAIP instead.

§ Relationship to eIDAS regulation and HAIP profile

In the context of the European eIDAS regulation (eIDAS) and its Architecture and Reference Framework (ARF), the DIIP profile is a profile for “regular” digital credentials, “non-qualified electronic attestations of attributes”. The OpenID4VC High Assurance Interoperability Profile (HAIP) is targeted for high-assurance use cases where it is important to bind the credentials to the Holder's private key (device binding). DIIP is the profile for other use cases.

The standards used in the DIIP profile are the same ones that the ARF uses, but the DIIP profile makes different choices to HAIP in many areas where OID4VCI and OID4VP provide optionality. DIIP aims to keep the selected OpenID4VCI and OpenID4VP Draft versions in sync with HAIP to lower implementation overhead.

To be discussed:

Should we explicitly state that DIIP does not focus on proximity use cases?

§ Future Work

DIIP describes technologies that are relatively easy to implement. DIIP makes choices within those standards, attempting to set the minimum functionality required for interoperability in the use cases in DIIP’s scope.

When standards mature and more and more solutions have full support for all the optional functionality in the standards, there may no longer be a need for DIIP. The authors believe that this development will take years and that there is a need for DIIP now.

§ Profile

In this section, we describe the interoperability profile.

§ Credential Format

The W3C Verifiable Credential Data Model (W3C VCDM) defines structure and vocabulary well suited for Digital Credentials in DIIP’s scope. For example, the Open Badges 3 credentials use W3C VCDM as the data format.

W3C VCDM recommends using Securing Verifiable Credentials using JOSE and COSE (VC-JOSE-COSE) as an enveloping proof mechanism and Verifiable Credential Data Integrity 1.0 (VC-DATA-INTEGRITY) as an embedded proof mechanism. Many Agents and Wallets already support SD-JWT as a way to encode Digital Credentials. Using SD-JWT to secure W3C VCDM Digital Credentials should be relatively easy to implement, even though there are differences with the SD-JWT-VC mechanism required by HAIP.

Requirement: DIIP-compliant implementations MUST support Securing JSON-LD Verifiable Credentials with SD-JWT as specified in (VC-JOSE-COSE).

To be discussed:

Do we want to mandate support for SD-JWT-VC 0.8 and mDocs credential formats? Pros: You can use DIIP for authentication use cases. Cons: You should use HAIP for those use cases. There is nothing that prevents a wallet or an agent from supporting both HAIP and DIIP if the use case requires both. If DIIP requires support for 3 credential formats, every ecosystem owner must make their own choice of the format.
Should DIIP focus on open and freely available standards instead of those behind paywalls and restricted participation?

§ Signature Algorithm

When working with JWTs, it is recommended to support multiple encryption keys, supporting several signature algorithms. The table below shows the mandatory keys and signature algorithms that DIIP-compliant parties must implement:

Key types	Signature Method
Ed25519	ECDSA
(x25519)
Secp256r1	ES256
Secp256k1	ES256K
RSA	RSA256

Requirement: DIIP-compliant implementations MUST support the key types and signature methods in the table above.

To be discussed:

Can we link to specifications?
Could we stick to one or at most two key types and signature methods?

§ Identifiers

In its previous versions, DIIP used DIDs for all identifiers. An entity identified by a DID publishes a DID Document, which can contain useful metadata about the entity, e.g., various endpoints. Following the rationale of keeping things as simple as possible, this version of DIIP only requires compliant implementations to support one DID method, did:web. Issuers and Verifiers can choose to use plain JWKs as their identifiers. They are not mandated to use did:web even if the compliant solutions are required to support it.

Requirement: DIIP-compliant implementations MUST support JWK as an identifier of the Issuers, Holders, and Verifiers

Requirement: DIIP-compliant implementations MUST support did:web as an identifier of the Issuers and Verifiers

Note: A near-future version of DIIP will probably require support for did:webvh instead of did:web.

Note: We should make sure that it’s OK to identify Issuers and Verifiers with only JWK while using OpenID Federation!

To be discussed:

Should DIIP say that organizations are identified by different means than natural persons? Pros: Legal requirements (GDPR) are different. In some cases, organizational wallets need to be continuously online and reachable. Cons: It's more complex. Digital credential ecosystems function with 3 basic roles: issuer, holder, and verifier. When you bring in the distinction between natural and legal persons, you end up with 6 roles (natural person issuer, legal person issuer, natural person holder, legal person holder, natural person verifier, legal person verifier). It is possible to state that DIIP doesn't need to support natural person issuers and verifiers, but all this is just extra noise.
Should DIIP require did:jwk instead of just JWK? Pros: Strong focus on DIDs. DID documents have beneficial traits like the capability to publish the DID holder's endpoints. Cons: More work, little added value. DID document functionality is not heavily used anywhere.
Should it be forbidden that organizations use JWK or did:jwk?

§ Trust Establishment

Signatures in Digital Credentials can be used to verify that the content of a credential has not been tampered with. But anyone can sign a credential and put anything in the issuer field. Digital Credential ecosystems require that there is a way for a Verifier to check who the Issuer or a Digital Credential is. Equally, a user might want to be informed about the trustworthiness of a Verifier before choosing to release credentials.

DIIP uses OpenID Federation as the trust infrastructure protocol. Issuers and Verifiers publish their own Entity Configurations, which include pointers to Trust Anchors. These Trust Anchors are trusted third parties that publish Entity Statements that allow for verification of the identity and the roles of the organizations. The OIDF Wallet Architectures specification specifies how to use OpenID Federation with Wallets.

Requirement: DIIP-compliant Issuer Agents MUST support publishing the Issuer's Entity Configurations as specified in OIDF Wallet Architectures.

(Simplifying explanation: sign the OID4VCI issuer metadata as a JWT and publish it in the .well-known path.)

Requirement: DIIP-compliant Verifier Agents MUST support publishing the Verifier's Entity Configurations as specified in OIDF Wallet Architectures.

(Simplifying explanation: sign the OID4VP verifier metadata as a JWT and publish it in the .well-known path.)

Requirement: If a Digital Credential contains a termsOfUse object with an attribute federations, a DIIP-compliant Wallet MUST warn the user before sharing Digital Credentials or Verifiable Presentations with a Verifier for which a trust chain cannot be resolved using the Trust Anchor in the value of the federations attribute.

To be discussed:

Should DIIP require even this basic support for OpenID Federation? Pros: Any credential ecosystem needs some way to etablish trust between the verifier and the issuer. Often also between the verifier and the holder. Making a choice and sticking to one way to do that creates a simpler profile. Cons: Sometimes static trust lists are just a simpler option. There already exists some documentation on how to use the eIDAS lists of trusted lists. (?)
Should we have a note saying that a future version may refer to the ToIP Trust Registry Query Protocol or TRAIN? (Both attempt to create an overlay on top of multiple trust frameworks.)

§ Digital Credentials API

DC API is a new W3C specification. The next versions of the DIIP protocol will most likely require compliant solutions to support DC API. If DIIP v4 compliant implementations support DC API, they should try to use that for credential issuance and verification and fall back to custom URI schemes if required.

To be discussed:

Should these kinds of optional features and future-proofing be collected into a separate Optional Features section? Pros: Clear separation between optional and mandatory features. Cons: The document structure gets complex if you repeat the same subheadings (credential format, signature algorithm, identifiers, etc.) in the Optional Features section. It is harder to read and process if you don't have subheadings in the Optional Features section.

§ Issuance

The issuance of Digital Credentials from the Issuer to the Holder's Wallet is done along the OID4VCI specification. Other protocols exist, but OID4VCI is very broadly supported and also required by HAIP.

§ OID4VCI

OpenID for Verifiable Credential Issuance (OID4VCI) defines an API for the issuance of Digital Credentials. OID4VCI issuance flow variations leave room for optionality.

In many situations, Digital Credentials are issued on the Issuer's online service (website). This online service may have already authenticated and authorized the user before displaying the credential offer. Another authentication or authorization is not needed in those situations. To keep things as simple as possible, DIIP uses Pre-Authorized Code Flow.

It should be noted that various Security Considerations have been described in the OID4VCI specification with respect to implementing Pre-Authorized Code Flow. Parties implementing DIIP are strongly suggested to implement mitigating measures, like the use of a Transaction Code.

Requirement: DIIP-compliant implementations MUST support the Pre-Authorized Code Flow.

Requirement: DIIP-compliant implementations SHOULD support the Transaction Code when using Pre-Authorized Code Flow.

Requirement: DIIP-compliant implementations supporting a Transaction Code MUST support a string of length between 4 to 6 text characters (any characters).

Requirement: DIIP-compliant implementations MUST support the trust_chain claim when using Pre-Authorized Code Flow.

To be discussed:

Why not just make the Transaction Code a MUST feature?
Is this more guidance to the ecosystems than requirement for wallets and agents?

Authorization Code Flow provides a more advanced way of implementing credential issuance. DIIP-compliant implementations MUST implement Authorization Code Flow. Depending on the setup, the authorization server (AS) may be different from the Issuer.

Requirement: DIIP-compliant implementations MUST support the Authorization Code Flow.

Requirement: DIIP-compliant implementations SHOULD NOT assume the Authorization Server is on the same FQDN as the Issuer when supporting the Authorization Code Flow.

To be discussed:

MUST NOT assume instead of SHOULD NOT assume?

OID4VCI defines Wallet-initiated and Issuer-initiated flows. Wallet-initiated means that the Wallet can start the flow without any activity from the Issuer. The Issuer-initiated flow seems to be more common in many use cases and seems to be supported more widely. It also aligns better with the use cases where the Holder is authenticated and authorized in an online service before the credential offer is created and shown.

Requirement: DIIP-compliant implementations MUST support the Issuer-initiated flow.

OID4VCI defines Same-device and Cross-device Credential Offer. People should be able to use both their desktop browser and their mobile device’s browser when interacting with the Issuer's online service.

Requirement: DIIP-compliant implementations MUST support both Same-device and Cross-device Credential Offer.

OID4VCI defines Immediate and Deferred flows. Deferred is more complex to implement and not required in most use cases.

Requirement: DIIP-compliant implementations MUST support the Immediate flow.

§ Presentation

The presentation of claims from the Holder's Wallet to the Verifier is done along the OID4VP. Other protocols exist, but OID4VP is very broadly supported and also required by HAIP.

§ 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 (Holder).

There are two query languages defined in OID4VP: Presentation Exchange (PE) and Digital Credentials Query Language (dcql). The support for PE has already been dropped from the next OID4VP draft version and can be considered deprecated.

Requirement: DIIP-compliant implementations MUST support the dcql_query in the Authorization Request.

OID4VP defines many Client Identifier Schemes. One way to identify Verifiers is through OpenID Federation. Since DIIP uses OpenID Federation as the trust infrastructure, it is natural to identify parties using the same protocol.

Requirement: DIIP-compliant implementations MUST support the https Client Identifier Scheme.

Note: The next OID4VP draft versions may require that the https Client Identifier Scheme be prefixed in some way in the presentation request. See https://github.com/openid/OpenID4VP/pull/401.

§ Validity and Revocation Algorithm

Expiration algorithms using validFrom and validUntil are a powerful mechanism to establish the validity of credentials. Evaluating the expiration of a credential is much more efficient than using revocation mechanisms. While the absence of validFrom and validUntil would suggest a credential is considered valid indefinitely, it is recommended that all implementations set validity expiration whenever possible to allow for clear communication to Holders and Verifiers.

Requirement: DIIP-compliant implementations SHOULD implement exiration using validFrom and validUntil whenever possible.

To be discussed:

Is this more guidance to the ecosystems than requirement for wallets and agents?

The IETF Token Status List defines a mechanism, data structures, and processing rules for representing the status of Digital Credentials (and other “Tokens”). The statuses of Tokens are conveyed via a bit array in the Status List. The Status List is embedded in a Status List Token.

The Bitstring Status List is based on the same idea as the IETF Token Status List and is simpler to implement since it doesn’t require signing of the status list. The IETF Token Status List may gain more support since it is recommended by HAIP.

Requirement: DIIP-compliant implementations MUST support IETF Token Status Lists embedded in JWT tokens.

§ 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 the text within each of the specifications listed in References.

Agent: A software application or component that an Issuer uses to issue Digital Credentials or that a Verifier uses to request and verify them.
Holder: An entity that possesses or holds Digital Credentials and can present them to Verifiers.
DID: Decentralized Identifier as defined in DID Core.
Issuer: A role an entity can perform by asserting claims about one or more subjects, creating a Digital Credential from these claims, and transmitting the Digital Credential to a Holder, as defined in W3C VCDM.
Digital Credential: A set of one or more Claims made by an Issuer that is tamper-evident and has authorship that can be cryptographically verified.

Verifier: An entity that requests and receives one or more Digital Credentials for processing.
Wallet: A software application or component that receives, stores, presents, and manages credentials and key material of an entity.

§ References

§ Normative References

DC API: Digital Credentials. Status: Draft Community Group Report.
did:web: did:web Method Specification. Status: Unofficial working group draft.
ES256: ECDSA using P-256 and SHA-256 as specified in RFC 7518 JSON Web Algorithms (JWA). Status: RFC - Proposed Standard.
IETF Token Status List: Token Status List - draft 10. Status: Internet-Draft.
OID4VCI: OpenID for Verifiable Credential Issuance - draft 15. Status: Second Implementer’s Draft.
OID4VP: OpenID for Verifiable Presentations - draft 23. Status: Third Implementer’s Draft.
OIDF Wallet Architectures: OpenID Federation Wallet Architectures 1.0 - draft 03. Status: Draft.
OpenID Federation: OpenID Federation 1.0 - draft 42. Status: draft.

To be discussed:

Link to the latest Implementer's Draft instead (ID4, draft 36)?

W3C VCDM: Verifiable Credentials Data Model v2.0. Status: W3C Proposed Recommendation.
VC-JOSE-COSE: Securing Verifiable Credentials using JOSE and COSE. Status: W3C Proposed Recommendation.

To be discussed:

Should the specs be grouped by the SDOs? Pros: More emphasis on the standard development organizations. More structure. Cons: Assumes that the reader knows under which heading to look for a reference. It's a short list and the benefits of grouping would be limited.

§ Non-Normative References

ARF: Architecture and Reference Framework. Status: Draft.
Bitstring Status List: Bitstring Status List v1.0. Status: W3C Proposed Recommendation.
DID Core: Decentralized Identifiers (DIDs) v1.0. Status: W3C Recommendation.
did:webvh: The did:webvh DID Method v0.5. Status: CURRENT STABLE.
eIDAS: Regulation (EU) No 910/2014 of the European Parliament and of the Council of 23 July 2014 on electronic identification and trust services for electronic transactions in the internal market and repealing Directive 1999/93/EC. Status: In force.
HAIP: OpenID4VC High Assurance Interoperability Profile. Status: Draft.
Open Badges 3: Open Badges Specification, Spec Version 3.0, Document Version 1.2. Status: This document is made available for adoption by the public community at large.
VC-DATA-INTEGRITY: Verifiable Credential Data Integrity 1.0. Status: W3C Proposed Recommendation.