DIIP v5

spec/federation-profile.md

@@ -0,0 +1,281 @@
+## Appendix B: OpenID Federation Digital Credentials Profile
+
+### Introduction
+
+This specification profiles [[ref: OpenID Federation]] for use with digital credentials, specifically focusing on credential issuance via OpenID for Verifiable Credential Issuance ([[ref: OID4VCI]]) and credential presentation via OpenID for Verifiable Presentations ([[ref: OID4VP]]).
+
+The profile simplifies federation usage by limiting scope to trust chain resolution and metadata discovery, while omitting more complex features such as federation policies and trust marks.
+
+#### Scope
+
+This profile applies to:
+
+- Credential issuers publishing OID4VCI metadata
+- Credential verifiers publishing verifier metadata
+- Wallets resolving trust chains to establish trust in issuers and verifiers
+
+This profile does not apply to and does not require conforming implementations to support:
+
+- Chapter 6 (Federation Policy)
+- Chapter 7 (Trust Marks)
+- Chapter 12 (OpenID Connect Client Registration)
+
+of [[ref: OpenID Federation]].
+
+### Terminology
+
+This specification uses the terms defined in [[ref: OpenID Federation]], [[ref: OID4VCI]],  [[ref: OID4VP]], and [[ref: SD-JWT VC]].
+
+**Entity Identifier**: As defined in [[ref: OpenID Federation]], a URL that uniquely identifies a federation entity.
+
+**Entity Configuration**: As defined in [[ref: OpenID Federation]], a signed JWT published at the Entity Identifier's `/.well-known/openid-federation` endpoint containing metadata and authority hints.
+
+**Trust Chain**: As defined in [[ref: OpenID Federation]], a sequence of Entity Statements from a Leaf Entity through intermediate entities to a Trust Anchor.
+
+**Issuer**: The role of the entity issuing credentials as defined in [[ref: W3C VCDM]]
+
+**Credential Issuer**: The technical service used to issue credentials as defined in [[ref: OID4VCI]]
+
+**Verifier**: The entity that requests, receives, and validates Presentations as defined in [[ref: OID4VCI]]. Note that this specification does not distinguish the role and the technical service of the verifier the same way it does for Issuer and Credential Issuer. For the purposes of this specification Verifier may refer to either the role or the technical service. (Thus, the reference to the definition in [[ref: OID4VCI]] and not the one in [[ref: OID4VP]].)
+
+### Credential Issuance
+
+#### Entity Identifier
+
+**Requirement: The Credential Issuer MUST use the value of the `credential_issuer` in its OID4VCI issuer metadata as its Entity Identifier.**
+
+The Credential Issuer's Entity Configuration can be found using the method described in the chapter 9 of [[ref: OpenID Federation]].
+
+#### Issuer Metadata Publication
+
+**Requirement: The Credential Issuer MUST place the OpenID4VCI issuer metadata into the Entity Configuration, in the `openid_credential_issuer` Entity Type Identifier.**
+
+**Requirement: If the `openid_credential_issuer` Entity Type Identifier is found in the Entity Configuration, the Wallet MUST use only this medatada and ignore the regular issuer metadata published in the well-known location defined in [[ref: OID4VCI]].**
+
+**Requirement: The Credential Issuer MUST place the public key material of the keys it uses to sign Digital Credentials in the `jwks` property of the `vc_issuer` Entity Type Identifier using the syntax specified in the chapter 5.2.1. of the [[ref: OpenID Federation]].**
+
+**Requirement: The Credential Issuer MUST include the `federation_entity` Entity Type Identifier with the `display_name` property in the Entity Configuration.**
+
+The Credential Issuer MAY place additional metadata into the `federation_entity` Entity Type Identifier.
+
+**Requirement: The Wallet MUST use the value of the `display_name` property in the `federation_entity` Entity Type Identifier when showing information about the Credential Issuer to the user of the Wallet.**
+
+#### Example: Credential Issuer Entity Configuration
+
+The following JSON document is a non-normative example of the decoded payload of a Credential Issuer's Entity Configuration.
+
+```json
+{
+  "iss": "https://credential-issuer.example",
+  "sub": "https://credential-issuer.example",
+  "iat": 1616239022,
+  "exp": 1616239322,
+  "metadata": {
+    "federation_entity": {
+      "display_name": "Example Issuer",
+      "logo_uri": "https://credential-issuer.example/logo.png",
+      "organization_name": "Example Credential Issuer",
+      "contacts": ["support@credential-issuer.example"]
+    },
+    "openid_credential_issuer": {
+      "issuer": "https://credential-issuer.example",
+      "display": [
+        {
+          "name": "Example Issuer",
+          "locale": "en-US",
+          "logo": {
+            "uri": "https://credential-issuer.example/logo.png",
+            "alt_text": "Example Logo"
+          }
+        }
+      ],
+      "credential_issuer": "https://credential-issuer.example",
+      "authorization_endpoint": "https://credential-issuer.example/authorize",
+      "authorization_servers": ["https://credential-issuer.example/authorize"],
+      "credential_endpoint": "https://credential-issuer.example/credential",
+      "credential_configurations_supported": {
+        "sd_jwt_vc_example": "..."
+      }
+    },
+    "vc_issuer": {
+      "jwks": [
+        {
+          "kty": "EC",
+          "kid": "MJ2BW-rNshp9sjh3SvwnBIkEsYsU92xVtC3-Fv_lcKc",
+          "alg": "ES256",
+          "crv": "P-256",
+          "x": "JTEE5QghmkA_-7_pZoKIluRzGNvQGtzmpNvb_nAswhE",
+          "y": "A_iBfIseHsdfE7CmI3lIYtKMdfyXXOIpPX_o6O0h0wY",
+          "use": "sig"
+        }
+      ]
+    }
+  },
+  "jwks": [
+    {
+      "kty": "EC",
+      "kid": "MJ2BW-rNshp9sjh3SvwnBIkEsYsU92xVtC3-Fv_lcKc",
+      "alg": "ES256",
+      "crv": "P-256",
+      "x": "JTEE5QghmkA_-7_pZoKIluRzGNvQGtzmpNvb_nAswhE",
+      "y": "A_iBfIseHsdfE7CmI3lIYtKMdfyXXOIpPX_o6O0h0wY",
+      "use": "sig"
+    }
+  ],
+  "authority_hints": [
+    "https://trustregistry.example"
+  ]
+}
+```
+
+The JWKS in the `vc_issuer` Entity Type Identifier contains information about the keys used to sign Digital Credentials. The JWKS on the root level of the Entity Configuration contains information about the key used to sign the Entity Configuration. In the example, the same key is used, but the keys MAY be different.
+
+#### SD-JWT VC Credentials
+
+**Requirement: When the Issuer issues credentials in the [[ref: SD-JWT VC]] format, the Issuer MUST place its Entity Identifier in the `fed` claim of the credential.**
+
+##### Example: SD-JWT VC with Federation Claim
+
+The following non-normative example shows a decoded payload of an [[ref: SD-JWT VC]] credential with the `fed` claim:
+
+```json
+{
+  "iss": "https://credential-issuer.example",
+  "fed": "https://credential-issuer.example",
+  "iat": 1683000000,
+  "exp": 1883000000,
+  "vct": "https://credentials.example.com/identity_credential",
+  "is_over_65": true,
+  "address": {
+    "street_address": "123 Main St",
+    "locality": "Anytown",
+    "region": "Anystate",
+    "country": "US"
+  }
+}
+```
+
+#### W3C VCDM Credentials
+
+**Requirement: When the Issuer issues credentials in the [[ref: W3C VCDM]] format, the Issuer MUST place a `termsOfUse` property into the credential. The `type` of this `termsOfUse` property MUST be the string `OpenIDFederation` and the `policyId` MUST be the Issuer's Entity Identifier.**
+
+##### Example: W3C VCDM Credential with termsOfUse
+
+The following non-normative example illustrates the use of the `termsOfUse` property:
+
+```json
+{
+  "@context": [
+    "https://www.w3.org/ns/credentials/v2"
+  ],
+  "id": "urn:uuid:c65d364e-2560-4e08-be03-9c3d944d609d",
+  "type": [
+    "VerifiableCredential"
+  ],
+  "issuer": "did:web:credential-issuer.example",
+  "validFrom": "2025-12-01T00:00:00Z",
+  "validUntil": "2028-12-31T23:59:59Z",
+  "credentialSubject": {
+  },
+  "termsOfUse": {
+    "type": "OpenIDFederation",
+    "trustFramework": "Example Federation",
+    "policyId": "https://credential-issuer.example"
+  }
+}
+```
+
+#### Note on Credential Issuer vs. Issuer
+
+The Issuer defined in the digital credential (the value of the `iss` claim in SD-JWT VC credentials or the value of the `id` of the `issuer` property in W3C VCDM credentials) is not necessarily the same entity as the Credential Issuer defined in the property `credential_issuer` in the OID4VCI metadata.
+
+For example, the [[ref: OpenID Federation]] Entity Identifier of the Issuer of the credential could be `https://university-of-utopia.example.edu` and the [[ref: OpenID Federation]] Entity Identifier of the Credential Issuer could be `https://credentials.ministryofeducation.example.edu`.
+
+If the Issuer chooses to make this kind of distinction between the entity issuing the credential and the technical service used for issuance, it is RECOMMENDED that the Entity Configuration of the technical service has an `authority_hints` value pointing to the Issuer's Entity Identifier and the Issuer publishes a Subordinate Statement about the technical service.
+
+### Credential Presentation and Verification
+
+#### Client Identifier Scheme
+
+**Requirement: The Verifier MUST use the `openid_federation:` prefix as defined in [[ref: OID4VP]] Section 5.9.3.**
+
+#### Verifier Metadata Publication
+
+**Requirement: The Verifier MUST place verifier metadata into the Entity Configuration, in the `openid_credential_verifier` Entity Type Identifier.**
+
+**Requirement: The Verifier MUST include the `federation_entity` Entity Type Identifier with the `display_name` property in the Entity Configuration.**
+
+The Verifier MAY place additional metadata into the `federation_entity` Entity Type Identifier.
+
+**Requirement: The Wallet MUST use the value of the `display_name` property in the `federation_entity` Entity Type Identifier when showing information about the Verifier to the user of the Wallet.**
+
+### Trust Establishment
+
+**Requirement: To establish trust with the Issuer (ensure that the Issuer can be trusted), the Verifier MUST resolve the Trust Chain from the Issuer's Entity Configuration until it finds a Federation Entity it trusts.**
+**Requirement: The Verifier MUST verify that the credential is signed with a key included in the `vc_issuer` metadata in the Entity Configuration of the Issuer. The `jwks` property in the `vc_issuer` must contain a key with the `kid` value equal to the `kid` header in the [[ref: SD-JWT VC]] credential.**
+
+#### Example: Verifier Entity Configuration
+
+The following JSON document is a non-normative example of the decoded payload of a Verifier's Entity Configuration.
+
+```json
+{
+  "iss": "https://credential-verifier.example",
+  "sub": "https://credential-verifier.example",
+  "iat": 1616239023,
+  "exp": 1616239323,
+  "metadata": {
+    "federation_entity": {
+      "display_name": "Example Credential Verifier",
+      "logo_uri": "https://credential-verifier.example/logo.png",
+      "organization_name": "Example Credential Verifier",
+      "contacts": ["support@credential-verifier.example"]
+    },
+    "openid_credential_verifier": {
+      "jwks": {
+        "keys": [
+          {
+            "kty": "EC",
+            "crv": "P-256",
+            "x": "f83OJ3D2xF4Z1s3QpLQe4qVb8K7q6y1v3z4Yb6k9J0",
+            "y": "x_FEzRu9q3u4bWz5n9X2L4q1U8T7c6v5s2d1a0b3C4",
+            "alg": "ES256",
+            "use": "enc",
+            "kid": "ec-key-1"
+          }
+        ]
+      },
+      "encrypted_response_enc_values_supported": [
+        "A128GCM",
+        "A192GCM",
+        "A256GCM"
+      ],
+      "vp_formats_supported": {
+        "dc+sd-jwt": {
+          "sd-jwt_alg_values": ["ES256"],
+          "kb-jwt_alg_values": ["ES256"]
+        }
+      }
+    }
+  },
+  "jwks": [
+    {
+      "kty": "EC",
+      "kid": "y4nC8uTvcM5uJxOIvUqFjXb2EA6xPGdnt8zvjW94m6U",
+      "alg": "ES256",
+      "crv": "P-256",
+      "x": "K6dA9ayt4P8xBN6SFiCZYOI2qeaFda7VV5wnmHWcl7w",
+      "y": "CdE30dUX0geK4NL8IMC9u-rRMOLC9WaScJIGK5rxtKI"
+    }
+  ],
+  "authority_hints": [
+    "https://trustregistry.example"
+  ]
+}
+```
+
+### Subordinate Statements
+
+Intermediaries and Trust Anchors MAY authorize their subordinates to issue or request certain credential types by placing metadata values like `openid_credential_issuer.credential_configurations_supported` or `openid_credential_verifier.dcql_query` in the Subordinate Statements.
+
+The meaning of such statements SHOULD be specified in ecosystem rulebooks and are out of the scope of this specification.

spec/future.md

@@ -1,32 +1,16 @@
 ## Appendix A: Future Directions
 
-### Credential Formats
-A future version of DIIP may require support for [SD-JWT VCLD](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html#name-sd-jwt-vcld) defined in the draft 27 of [[ref: OID4VP]].
-
 ### Identifiers
 
 A near-future version of DIIP will probably require support for [[ref: did:webvh]] instead of [[ref: did:web]].
 
 ### Trust Establishment
-A future version of the profile will likely refer to [[ref: OpenID Federation]].
-In [[ref: OpenID Federation]], [[ref: Issuer]]s and [[ref: Verifier]]s 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 [[ref: OIDF Wallet Architectures]] specification specifies how to use [[ref: OpenID Federation]] with Wallets.
-
-One way to use [[ref: OpenID Federation]] is described here as a guidance for implementers.
-
-- [[ref: Issuer]] [[ref: Agent]]s publish the [[ref: Issuer]]'s Entity Configurations as specified in [[ref: OIDF Wallet Architectures]]. (Simplified explanation: sign the [[ref: OID4VCI]] issuer metadata as a JWT and publish it in the `.well-known` path.)
-
-- [[ref: Verifier]] [[ref: Agent]]s publish the [[ref: Verifier]]'s Entity Configurations as specified in [[ref: OIDF Wallet Architectures]]. (Simplified explanation: sign the [[ref: OID4VP]] verifier metadata as a JWT and publish it in the `.well-known` path.)
-
-- If a [[ref: Digital Credential]] contains a [termsOfUse](https://www.w3.org/TR/vc-data-model-2.0/#terms-of-use) object with an attribute `federations`, a DIIP-compliant Wallet MUST warn the user before sharing [[ref: Digital Credential]]s or Verifiable Presentations with a [[ref: Verifier]] for which a trust chain cannot be resolved using the Trust Anchor in the value of the `federations` attribute.
-
-### Presentation
 
-Note that the next [[ref: OID4VP]] draft versions may require that the `did` *Client Identifier Scheme* be prefixed in the *presentation request*. See https://github.com/openid/OpenID4VP/pull/401.
-
-If a new version of DIIP uses [[ref: OpenID Federation]] as the trust infrastructure, it is natural to identify parties using the same protocol and require DIIP-compliant implementations to support the `https` *Client Identifier Scheme* in [[ref: OID4VP]].
+The next version of the DIIP profile will likely require also [[ref:Wallet]]s to support [[ref: OpenID Federation]].
 
 ### Digital Credentials API
-[[ref: DC API]] is a new W3C specification. The next versions of the DIIP protocol will most likely require compliant solutions to support [[ref: DC API]]. If DIIP v4 compliant implementations support [[ref: DC API]], they should try to use that for credential issuance and verification and fall back to custom URI schemes if required.
+
+[[ref: DC API]] is a new W3C specification. The next versions of the DIIP protocol will most likely require compliant solutions to support [[ref: DC API]].
 
 ### References
 
@@ -35,10 +19,3 @@ If a new version of DIIP uses [[ref: OpenID Federation]] as the trust infrastruc
 
 [[def: did:webvh]]
 ~ [The did:webvh DID Method v0.5](https://identity.foundation/didwebvh/). Status: CURRENT STABLE.
-
-[[def: OIDF Wallet Architectures]]
-~ [OpenID Federation Wallet Architectures 1.0 - draft 03](https://openid.net/specs/openid-federation-wallet-1_0-03.html). Status: Draft.
-
-[[def: OpenID Federation]]
-~ [OpenID Federation 1.0 - draft 42](https://openid.net/specs/openid-federation-1_0-42.html). Status: draft.
-