diff --git a/openid-federation-wallet-1_0.md b/openid-federation-wallet-1_0.md index 0f1184f..79bbc57 100644 --- a/openid-federation-wallet-1_0.md +++ b/openid-federation-wallet-1_0.md @@ -62,7 +62,10 @@ This specification defines how to use OpenID Federation 1.0 [@!OpenID.Federation security and interoperability of wallet ecosystems, facilitating trust establishment among the parties and enabling secure metadata exchange and policy application across large scale deployments. -It outlines the general architecture of a federated trust +OpenID Federation is a building block for applying Trust Frameworks. +It can help ensure that all participants in a system understand and adhere to the +same principles and practices, making interactions predictable and secure. +This specification outlines the general architecture of a federated trust infrastructure for wallet ecosystems, identifying participant roles and describing the use of those roles. @@ -131,23 +134,11 @@ This specification also defines the following terms: **Credential Verifier Instance**: : A software application that allows an individual to request to an Holder and receive from that Holder a Digital Credential, sometimes in a proximity flow, and then verify the received Digital Credential. -## Trust Models and Trust Frameworks +**Trust Model**: +: The relationships and mechanisms through which trust is established and maintained between Entities, including how they interact, the basis on which they can trust each other, and the roles they play. -The terms "trust model" and "trust framework" are often used in the context of security, identity management, and federation systems. - -The Trust Model defines the relationships and mechanisms through which trust is established and maintained between entities in a system. It outlines how entities interact, the basis on which they can trust each other, and the roles they play within the system. Trust Models can be simple or complex, depending on the number of parties involved and the nature of their interactions. Common examples include: - -- **Direct Trust**: Trust is established directly between two parties without intermediaries. -- **Trusted Third Party**: Trust is facilitated by a trusted third party. -- **Web of Trust**: Each participant makes individual decisions about whom to trust, using Direct Trust or potentially multiple Third-Parties. - -**Trusted Third-Party** is the focus of this specification, although the **Web of Trust** model is not excluded if multiple trusted third parties (Trust Anchors) are supported by the participants. - -A Trust Framework is a comprehensive structure that includes policies, standards, and guidelines that govern the implementation of a Trust Model. It provides detailed rules for how trust should be managed, including the legal, technical, and procedural aspects. To allow for a scalable approach, as many aspects of the framework as possible should be presented in a machine discoverable and machine-readable way. - -In the scope of this specification, only the technical and procedural aspects are considered and fully covered. - -OpenID Federation [@!OpenID.Federation] is a building block for assembling and using trust frameworks. It can help ensure that all participants in a system understand and adhere to the same principles and practices, making interactions predictable and secure. +**Trust Framework**: +: A structure of policies, standards, and guidelines that governs the implementation of a Trust Model, including legal, technical, and procedural rules. This specification covers only the technical and procedural aspects. To allow for a scalable approach, as many aspects of a Trust Framework as possible should be presented in a machine-discoverable and machine-readable way. # The Four-Party Model @@ -156,6 +147,8 @@ the Holder, the Credential Issuer, the Credential Verifier, and an Entity trusted by the other Entities called the Trust Anchor. This is an extension of the three-party Issuer-Holder-Verifier Model described in [@!OpenID4VCI] and [@!OpenID4VP] that adds a fourth party: the Trust Anchor. +Trust among those Entities is established through the Trust Anchor acting as a +trusted third party. Participants MAY configure multiple Trust Anchors. The four Entities interact with each other as described below: @@ -210,11 +203,17 @@ Consequently, the End-User obtains and holds the Digital Credentials without dis The Figure above illustrates at the center the Holder, who interacts directly with both the Credential Issuer and the Credential Verifier. The Credential Issuer provides Digital Credentials to the Holder, while the Credential Verifier relies on these Credentials to verify the Holder's claims. Above the Holder is the Wallet Provider, which facilitates the registration and the attestation of the security and integrity of the Holder. All entities, including the Credential Issuer, Credential Verifier, Wallet Provider and therefore Holders, and are underpinned by a Trust Anchor, ensuring that all interactions and transactions are anchored in a trusted third party. -# Wallet Instance Types +# Wallet Instances + +This section describes deployment forms of Wallet Instances and how trust is established with the Holder. + +The Wallet Instance types below are informative and non-exhaustive. This specification does not define type-specific federation processing. Credential Issuers, Credential Verifiers, and other Entities evaluate trust with the Holder using the Wallet Provider and Wallet Attestation, regardless of Wallet Instance type. -There are many ways to technically implement Wallet Instances to manage Digital Credentials. There are typically two types of Wallet End-Users: one is a natural person and another is an Organizational Entity. These two types of End-Users may have different usage and functional requirements. +Wallet Instances may be used by a natural person or by an Organizational Entity. These two cases may have different usage and functional requirements; those differences do not change the federation mechanisms defined in this specification. -Below a non-exhaustive list of the different Wallet Instance types. +## Wallet Instance Types + +There are many ways to technically implement Wallet Instances to manage Digital Credentials. **Mobile Wallet Native Application** : Also known as Mobile Wallet only, is an application that runs natively on a Personal Device under the sole control of an End-User and provided through a platform vendor specific app-store, on behalf of the Wallet Solution. In some cases the End-User as natural person uses the Mobile Wallet representing a legal person. @@ -229,7 +228,7 @@ Below a non-exhaustive list of the different Wallet Instance types. ## Establishing Trust with the Holder -Since the Holder may not be an Organizational Entity and cannot be registered as an Organization through registration services, it is not represented within a Trust Chain and does not qualify as a Federation Entity. This context sets the stage for understanding the unique position of the Holder in relation to the Trust Chain and Federation Entities. +Since the Holder may not be an Organizational Entity and cannot be registered as an Organization through registration services, it is not represented within a Trust Chain and does not qualify as a Federation Entity. This applies regardless of Wallet Instance type. This context sets the stage for understanding the unique position of the Holder in relation to the Trust Chain and Federation Entities. ~~~ ascii-art +----------------------------+ @@ -439,10 +438,10 @@ metadata: #### Rationale for Extending the Set of `openid_credential_verifier` Metadata Parameters The rationale for extending the set of `openid_credential_verifier` metadata -parameters is to align OpenID4VP Verifiers with the Trusted Third-Party trust -model employed by this specification. Cryptographic material, protocol endpoints -and default or constrained DCQL queries are published in federation-managed metadata, -constrained DCQL queries in federation-managed metadata. This practice aims to: +parameters is to align OpenID4VP Verifiers with the Trust Anchor-based Trust +Model employed by this specification. Cryptographic material, protocol endpoints, +and default or constrained DCQL queries are published in federation-managed metadata. +This practice aims to: - enforce common technical and policy requirements on all participating Credential Verifiers, @@ -479,9 +478,51 @@ These modifications allow a federation authority, such as a Trust Anchor, to app "exp": 1616239322, "metadata": { "federation_entity": { - "organization_name": "Example Credential Verifier", + "organization_name": "Example Credential Verifier" }, - "openid_credential_verifier": { ... as defined in the OpenID4VP specs ... } + "openid_credential_verifier": { + "jwks": { + "keys": [ + { + "kty": "EC", + "crv": "P-256", + "use": "sig", + "kid": "verifier-key-1", + "x": "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4", + "y": "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM" + } + ] + }, + "request_uris": [ + "https://credential-verifier.example.it/request" + ], + "response_uris": [ + "https://credential-verifier.example.it/response" + ], + "redirect_uris": [ + "https://credential-verifier.example.it/cb" + ], + "dcql_queries": [ + { + "credentials": [ + { + "id": "pid", + "format": "dc+sd-jwt", + "meta": { + "vct_values": [ + "urn:eudi:pid:1" + ] + }, + "claims": [ + {"path": ["given_name"]}, + {"path": ["family_name"]}, + {"path": ["birth_date"]} + ] + } + ] + } + ] + } }, "jwks": { "keys": [ @@ -496,7 +537,7 @@ These modifications allow a federation authority, such as a Trust Anchor, to app } } ``` -**Example 1**: Example demonstrating how a Federation Authority can issue a Subordinate Statement about a Credential Verifier, specifying certain metadata parameters such as the endpoints to use and the allowed Digital Credentials to be requested. +**Example 1**: Non-normative example of a Subordinate Statement issued by a Federation Authority about a Credential Verifier. The `openid_credential_verifier` metadata sets the protocol keys, the registered `request_uri` / `response_uri` / `redirect_uri` endpoints, and the DCQL query the Verifier is allowed to use when requesting Digital Credentials. ### OpenID Credential Verifier Presentation Metadata in Subordinate Statements @@ -553,9 +594,10 @@ In particular: applied to any `dcql_queries` present in the Credential Verifier metadata, if available, or otherwise to the `dcql_query` contained in `client_metadata` in the Authorization Request. - Profiles MAY additionally convey `dcql_queries`-related policies using - Trust Marks bound to the Credential Verifier; see the section on - Trust Marks and policy expression for further guidance. + When `metadata` or `metadata_policy` contains + `openid_credential_verifier.dcql_queries`, the DCQL queries a + Credential Verifier is permitted to use MUST be determined only from + that `metadata` and `metadata_policy`. This mechanism allows superior entities to centrally define and enforce policy on Credential Verifiers’ OpenID4VP behaviour (including cryptographic @@ -574,14 +616,24 @@ Differently from `metadata`, `metadata_policy` ensures that specific settings ca ## Using Trust Marks -Trust Marks are issued by authorized entities (Trust Mark Issuers) within the federation, typically after an entity has demonstrated compliance with certain standards, this might happen through auditing or certification processes. - -Trust Marks are typically implemented as signed assertions that can be verified by other entities. +Trust Marks are used as defined in [@!OpenID.Federation]. This specification +does not change Trust Mark issuance, signature verification, or status checks. -This verification process involves checking the digital signature against the public key of the Trust Mark Issuer to ensure the Trust Mark has not been forged, and its check to the Trust Mark Status endpoint to check it against any revocation. +This profile uses Trust Marks for qualitative and authorization properties of +wallet Entities that are not expressed, or not fully expressed, in `metadata` +and `metadata_policy`. Typical uses in wallet ecosystems include: -Trust Marks SHOULD be defined within the trust framework. Trust Marks are asserted about a subject through a registration service or compliance evaluation mechanism and therefore included in subject's Entity Configurations. This allows other entities to quickly assess the compliance status of a subject by examining the Entity Configuration of a subject. +- Credential Issuer entitlement to issue a given Digital Credential type; +- Credential Verifier authorization to request particular credentials or to + interact with particular populations (for example, under-age End-Users); +- Wallet Provider assurance that a Wallet Solution meets a security or + compliance profile required by the Trust Framework; +- Credential Verifier attributes that a Wallet verifies and presents to the + End-User (for example, an assurance that the verifier is an ethical data user). +The DCQL queries a Credential Verifier is permitted to use are determined +as defined in OpenID Credential Verifier Presentation Metadata in +Subordinate Statements. Trust Marks SHOULD NOT be used to carry `dcql_queries`. ```json= { @@ -593,7 +645,7 @@ Trust Marks SHOULD be defined within the trust framework. Trust Marks are assert "tos_uri": "https://vavuso.example.com/tos" } ``` -**Example 2**: Trust Mark to be included in a Leaf Entity Configuration, which payload states Leaf's compliance in interacting with under-age End-User. +**Example 2**: Non-normative Trust Mark included in a Credential Verifier's Entity Configuration, asserting authorization to interact with under-age End-Users. # Federation Trust Discovery Use Cases @@ -1159,6 +1211,24 @@ The technology described in this specification was made available from contribut -06 + * Filled Example 1 `openid_credential_verifier` metadata with protocol + keys, registered endpoints, and an authorized DCQL query + (federation-wallet issue #65). + * Clarified that Wallet Instance types are informative and that + federation processing does not vary by type (federation-wallet + issue #64). Trust with the Holder is established through the + Wallet Provider and Wallet Attestation for all instance types. + * Removed unused Terminology subsection on Direct Trust, Web of Trust, + and Trusted Third-Party (federation-wallet issue #62). Defined Trust + Model and Trust Framework as terms used in the specification, restated + that trust is established through Trust Anchors (participants MAY + configure more than one) in the Four-Party Model, and aligned the + Credential Verifier metadata rationale with that language. + * Profiled Trust Marks for wallet ecosystems instead of restating + OpenID Federation (federation-wallet issue #66): issuance + entitlement, verifier authorization, Wallet Provider assurance, + and verifier attributes presented to the End-User. DCQL query + authorization remains in `metadata` and `metadata_policy`. * Added Federation Trust Discovery use case "Credential Verifiers Establishing Trust in Credential Issuers" to resolve federation-wallet issue #48: map https Issuer Identifiers in