Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

refactor HAIP and add details for mdoc profile of OID4VP over the Browser API #122

Open
wants to merge 21 commits into
base: main
Choose a base branch
from
Open
Changes from 14 commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
094b35b
refactor and add details for mdoc profile over the oid4vp browser API
Nov 20, 2024
95bcf02
Apply suggestions from Brian's code review
Sakurann Nov 21, 2024
2f4b2ec
allow both signed and unsigned requests. mandate both for the wallet,…
Nov 28, 2024
77aa345
Apply editorial suggestions from Joseph's code review
Sakurann Nov 28, 2024
796886b
remove restrictions to KB JWT aud
Sakurann Nov 28, 2024
cb19041
clarify the unless otherwise stated requirements apply to all entities
Nov 28, 2024
85bef24
remove the requirement to support transaction data and put a placeholder
Nov 28, 2024
013c1fd
remove reference to 18013-7 and specific requirements for JWE with mdocs
Nov 28, 2024
c45eb79
Apply suggestions from code review
Sakurann Dec 3, 2024
1465f18
Attempt to fix pipeline
jogu Dec 3, 2024
02740b1
Apply suggestions from code review
Sakurann Dec 5, 2024
ed8a27f
Merge branch 'main' into mdoc-browser-api-profile
jogu Dec 5, 2024
4fe9fb3
Apply suggestions from code review
Sakurann Dec 7, 2024
aaf7d87
temporarily removing reference to the transaction data from HAIP
Sakurann Dec 7, 2024
79514e1
moving transaction data to a section that describes both sd-jwt and m…
Sakurann Dec 7, 2024
1e5abe7
remove encryption section from mdoc specific section
Sakurann Dec 7, 2024
71de98e
Apply suggestions from code review
Sakurann Dec 12, 2024
680abc2
removing (can be both remote and in-person)
Sakurann Dec 12, 2024
42aca21
Apply suggestions from code review
Sakurann Dec 12, 2024
803272d
Apply suggestions from code review
Sakurann Dec 12, 2024
58edeaf
Apply suggestions from code review
Sakurann Dec 12, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
140 changes: 116 additions & 24 deletions openid4vc-high-assurance-interoperability-profile-1_0.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ organization="SPRIND"

.# Abstract

This document defines a profile of OpenID for Verifiable Credentials in combination with the credential format SD-JWT VC. The aim is to select features and to define a set of requirements for the existing specifications to enable interoperability among Issuers, Wallets and Verifiers of Credentials where a high level of security and privacy is required. The profiled specifications include OpenID for Verifiable Credential Issuance [@!OIDF.OID4VCI], OpenID for Verifiable Presentations [@!OIDF.OID4VP], Self-Issued OpenID Provider v2 [@!OIDF.SIOPv2], and SD-JWT VC [@!I-D.ietf-oauth-sd-jwt-vc].
This document defines a profile of OpenID for Verifiable Credentials in combination with the credential formats IETF SD-JWT VC and ISO mdoc. The aim is to select features and to define a set of requirements for the existing specifications to enable interoperability among Issuers, Wallets and Verifiers of Credentials where a high level of security and privacy is required. The profiled specifications include OpenID for Verifiable Credential Issuance [@!OIDF.OID4VCI], OpenID for Verifiable Presentations [@!OIDF.OID4VP], Self-Issued OpenID Provider v2 [@!OIDF.SIOPv2], IETF SD-JWT VC [@!I-D.ietf-oauth-sd-jwt-vc], and ISO mdoc [@!ISO.18013-5].
Sakurann marked this conversation as resolved.
Show resolved Hide resolved
Sakurann marked this conversation as resolved.
Show resolved Hide resolved

{mainmatter}

Expand All @@ -40,7 +40,7 @@ This document defines a set of requirements for the existing specifications to e

This document is not a specification, but a profile. It refers to the specifications required for implementations to interoperate among each other and for the optionalities mentioned in the referenced specifications, defines the set of features to be mandatory to implement.

The profile uses OpenID for Verifiable Credential Issuance [@!OIDF.OID4VCI] and OpenID for Verifiable Presentations [@!OIDF.OID4VP] as the base protocols for issuance and presentation of Credentials, respectively. The credential format used is SD-JWT VC as specified in [@!I-D.ietf-oauth-sd-jwt-vc]. Additionally, considerations are given on how deployments can perform a combined issuance of credentials in both SD-JWT VC and ISO mdoc [@ISO.18013-5] formats.
The profile uses OpenID for Verifiable Credential Issuance [@!OIDF.OID4VCI] and OpenID for Verifiable Presentations [@!OIDF.OID4VP] as the base protocols for issuance and presentation of Credentials, respectively. The credential formats used are IETF SD-JWT VC as specified in [@!I-D.ietf-oauth-sd-jwt-vc] and ISO mdoc [@!ISO.18013-5]. Additionally, considerations are given on how deployments can perform a combined issuance of credentials in both IETF SD-JWT VC and ISO mdoc [@ISO.18013-5] formats.
Sakurann marked this conversation as resolved.
Show resolved Hide resolved

A full list of the open standards used in this profile can be found in Overview of the Open Standards Requirements (reference).

Expand All @@ -56,17 +56,22 @@ This specification uses the terms "Holder", "Issuer", "Verifier", and "Verifiabl

The following aspects are in scope of this interoperability profile:

* Protocol for issuance of the Verifiable Credentials (can be both remote and in-person) (OID4VCI)
* Protocol for online presentation of Verifiable Credentials (can be both remote and in-person) (OID4VP)
* Profile of OpenID4VCI to issue IETF SD-JWT VCs (can be both remote and in-person), including
Sakurann marked this conversation as resolved.
Show resolved Hide resolved
* Wallet Attestation
* Profile of OpenID4VP to present IETF SD-JWT VCs
* Profile of OpenID4VP over the W3C Digital Credentials API [@w3c.digital_credentials_api] to present
* IETF SD-JWT VCs
* ISO mdocs
* Protocol for User Authentication by the Wallet at a Verifier (SIOP v2)
paulbastian marked this conversation as resolved.
Show resolved Hide resolved
paulbastian marked this conversation as resolved.
Show resolved Hide resolved
* Wallet Attestation (during Credential issuance)
* Credential Format (SD-JWT VC)
* Status Management of the Credentials, including revocation
* Cryptographic Holder Binding
* Issuer key resolution
* Issuer identification (as prerequisite for trust management)
* Profile of IETF SD-JWT VC that includes the following aspects
* Status Management of the Credentials, including revocation
Sakurann marked this conversation as resolved.
Show resolved Hide resolved
* Cryptographic Holder Binding
Sakurann marked this conversation as resolved.
Show resolved Hide resolved
* Issuer key resolution
* Issuer identification (as prerequisite for trust management)
* Crypto Suites
Sakurann marked this conversation as resolved.
Show resolved Hide resolved

Note that when OpenID4VP is used, the Wallet and the Verifier can either be remote or in-person.

Assumptions made are the following:

* The issuers and verifiers cannot pre-discover wallet’s capability
Expand All @@ -79,6 +84,9 @@ The following items are out of scope for the current version of this document, b

* Trust Management, i.e. authorization of an issuer to issue certain types of credentials, authorization of the Wallet to be issued certain types of credentials, authorization of the Verifier to receive certain types of credentials.
* Protocol for presentation of Verifiable Credentials for offline use-cases, e.g. over BLE.
* Profile of OpenID4VCI to issue ISO mdocs is defined in ISO 23220-3.
Sakurann marked this conversation as resolved.
Show resolved Hide resolved
* Profile of OpenID4VP without using W3C Digital Credentials API to present ISO mdocs is
defined in [@ISO.18013-7]. For more details, also see Annex B.3 in [@!OIDF.OID4VP].

## Scenarios/Business Requirements

Expand All @@ -88,20 +96,20 @@ The following items are out of scope for the current version of this document, b

## Standards Requirements

Unless explicitly stated, all normative requirements apply to all participating entities: Issuers, Wallets and Verifiers.
This specification enables interoperable implementation of the following flows:
Sakurann marked this conversation as resolved.
Show resolved Hide resolved

* Issuance of IETF SD-JWT VC using OpenID4VCI
* Presentation of IETF SD-JWT VC using OpenID4VP without using W3C Digital Credentials API
Sakurann marked this conversation as resolved.
Show resolved Hide resolved
* Presentation of IETF SD-JWT VC using OpenID4VP over W3C Digital Credentials API
* Presentation of ISO mdocs using OpenID4VP over W3C Digital Credentials API

| (as defined in this profile) | Issuer | Wallet | Verifier |
|:--- |:--- |:--- |:--- |
|OID4VP| N/A |MUST|MUST|
|OID4VCI| MUST|MUST|N/A|
|SIOPv2|N/A|MUST|SHOULD|
|SD-JWT VC profile as defined in (#sd-jwt-vc) |MUST|MUST|MUST|
Implementations of this specification do not have to implement all of the flows listed above, but they MUST be compliant to all of the requirements for a particular flow they chose to implement.

# OpenID for Verifiable Credential Issuance

Implementations of this profile:
The requirements for the Wallet and the Credential Issuer, unless specified otherwise:
Sakurann marked this conversation as resolved.
Show resolved Hide resolved
Sakurann marked this conversation as resolved.
Show resolved Hide resolved

* MUST support both pre-auth code flow and authorization code flow.
* MUST support both pre-authorized code flow and authorization code flow.
* MUST support protocol extensions for the SD-JWT VC credential format profile as defined in (#vc_sd_jwt_profile).
* MUST support sender-constrained tokens using the mechanism defined in [@!RFC9449].
* MUST support [@!RFC7636] with `S256` as the code challenge method.
Expand Down Expand Up @@ -198,9 +206,11 @@ This is an example of a Wallet Instance Attestation:

* The Credential Issuer MUST publish a mapping of every Credential Type it supports to a scope value.
Sakurann marked this conversation as resolved.
Show resolved Hide resolved

# OpenID for Verifiable Presentations
# OpenID for Verifiable Presentations profile for IETF SD-JWT VC over HTTPS
Sakurann marked this conversation as resolved.
Show resolved Hide resolved

The requirements for the Wallet and the Verifier, unless specified otherwise:
Sakurann marked this conversation as resolved.
Show resolved Hide resolved

* MUST support protocol extensions for SD-JWT VC credential format profile as defined in this specification (#vc_sd_jwt_profile).
* MUST support protocol extensions for IETF SD-JWT VC credential format profile as defined in this specification (#vc_sd_jwt_profile).
Sakurann marked this conversation as resolved.
Show resolved Hide resolved
* As a way to invoke the Wallet, at least a custom URL scheme `haip://` MUST be supported. Implementations MAY support other ways to invoke the wallets as agreed by trust frameworks/ecosystems/jurisdictions, not limited to using other custom URL schemes.
* Response type MUST be `vp_token`.
* Response mode MUST be `direct_post.jwt`. The Verifier MUST return `redirect_uri` in response to the HTTP POST request from the Wallet, where the Wallet redirects the User to, as defined in Section 7.2 of [@!OIDF.OID4VP]. Implementation considerations for the response mode `direct_post.jwt` are given in Section 12.4 of [@!OIDF.OID4VP].
Expand All @@ -214,6 +224,58 @@ This is an example of a Wallet Instance Attestation:
* In the `input-descriptors` object, `id`, `name`, `purpose`, `group`, `format`, and `constraints` properties MUST be supported. In the `constraints` object, `limit_disclosure`, and `fields` properties MUST be supported. In the `fields` object, `path` and `filter` properties MUST be supported. A `path` MUST contain exactly one entry with a static path to a certain claim. A `filter` MUST only contain `type` elements of value `string` and `const` elements.
* In the `submission_requirements` object, `name`, `rule (`pick` only)`, `count`, `from` properties MUST be supported.

# OpenID for Verifiable Presentations over W3C Digital Credentials API

The requirements for the Wallet and the Verifier, unless specified otherwise:
Sakurann marked this conversation as resolved.
Show resolved Hide resolved

* MUST support Annex A in [@!OIDF.OID4VP] that defines how to use OpenID4VP over the W3C Digital Credentials API.
* The Wallet MUST support both signed and unsigned requests defined in Annex A.3.1 and A.3.2 of [@!OIDF.OID4VP]. The Verifier MUST support signed requests, unsigned requests, or both.
Sakurann marked this conversation as resolved.
Show resolved Hide resolved
Sakurann marked this conversation as resolved.
Show resolved Hide resolved
* Wallet Invocation is done via the W3C Digital Credentials API or an equivalent platform API. Custom URL schemes MUST NOT be used.
Sakurann marked this conversation as resolved.
Show resolved Hide resolved
* Response Mode MUST be `dc_api.jwt`. The response MUST be encrypted.
* The DCQL query and response as defined in Section 6 of [@!OIDF.OID4VP] MUST be used. Presentation Exchange as defined in Sections 5.4 and 5.5 of [@!OIDF.OID4VP] MUST NOT be used. Below is the list of features in the DCQL query and response that MUST be supported:
Sakurann marked this conversation as resolved.
Show resolved Hide resolved
* tbd
Sakurann marked this conversation as resolved.
Show resolved Hide resolved
Sakurann marked this conversation as resolved.
Show resolved Hide resolved

## ISO mdoc specific requirements for OpenID for Verifiable Presentations over W3C Digital Credentials API
Sakurann marked this conversation as resolved.
Show resolved Hide resolved

Sakurann marked this conversation as resolved.
Show resolved Hide resolved
* The Credential Format Identifier MUST be `mso_mdoc`.
* ISO mdoc Credential Format specific DCQL parameters as defined in Annex B.3.1. of [@!OIDF.OID4VP] MUST be used.
Sakurann marked this conversation as resolved.
Show resolved Hide resolved
* Verifier MAY request more than one Credential in the same request.
* When multiple ISO mdocs are being returned, each ISO mdoc MUST be returned in a separate DeviceResponse (as defined in 8.3.2.1.2.2 of [@!ISO.18013-5]), each matching to a respective DCQL query. Therefore, the resulting `vp_token` contains multiple DeviceResponses.
Sakurann marked this conversation as resolved.
Show resolved Hide resolved
* Specific requirements for the response encryption are tbd.
Sakurann marked this conversation as resolved.
Show resolved Hide resolved

### Session Transcript

The SessionTranscript as defined in Section 9.1.5.1 in [@ISO.18013-5] MUST be used with the following changes:
Sakurann marked this conversation as resolved.
Show resolved Hide resolved

* DeviceEngagementBytes MUST be null.
Sakurann marked this conversation as resolved.
Show resolved Hide resolved
* EReaderKeyBytes MUST be null
Sakurann marked this conversation as resolved.
Show resolved Hide resolved

The Handover element is defined as following:
Sakurann marked this conversation as resolved.
Show resolved Hide resolved

```
Handover = OID4VPDCAPIHandover
OID4VPDCAPIHandover = [
"OID4VPDCAPIHandover"
Sakurann marked this conversation as resolved.
Show resolved Hide resolved
clientId
origin
nonce
]

clientId = tstr ; using UTF-8
origin = tstr ; using UTF-8
nonce = tstr ; using UTF-8
```

Sakurann marked this conversation as resolved.
Show resolved Hide resolved
* "OID4VPDCAPIHandover" is a string that identifies the type of handover structure as a security measure to prevent confusion of handovers.
* `clientId` and `nonce` parameters in the Handover MUST be the `client_id` and `nonce` parameters included in the Authorization Request from the Verifier.
* `origin` in the Handover is the origin of the Verifer, obtained from the Web-platform and/or app platform.
Comment on lines +266 to +280
Copy link

@awoie awoie Dec 12, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should use the hash instead of the raw values to enable remote signature architectures to prevent the remote service to learn more than necessary about the transaction details, i.e., origin, client etc.

Suggested change
OID4VPDCAPIHandover = [
"OID4VPDCAPIHandover"
clientId
origin
nonce
]
clientId = tstr ; using UTF-8
origin = tstr ; using UTF-8
nonce = tstr ; using UTF-8
```
* "OID4VPDCAPIHandover" is a string that identifies the type of handover structure as a security measure to prevent confusion of handovers.
* `clientId` and `nonce` parameters in the Handover MUST be the `client_id` and `nonce` parameters included in the Authorization Request from the Verifier.
* `origin` in the Handover is the origin of the Verifer, obtained from the Web-platform and/or app platform.
```cddl
OID4VPDCAPIHandover = [
"OID4VPDCAPIHandover", ; A fixed identifier for this handover type
OID4VPDCAPIHandoverInfoHash ; Integrity hash of OID4VPDCAPIHandoverInfo
]
clientId = tstr ; UTF-8 encoded string representing the client ID
origin = tstr ; UTF-8 encoded string representing the origin
nonce = tstr ; UTF-8 encoded string representing the nonce
OID4VPDCAPIHandoverInfo = [ clientId, origin, nonce ] ; Array containing handover parameters
OID4VPDCAPIHandoverInfoHash = tstr ; UTF-8 encoded string for the integrity hash of OID4VPDCAPIHandoverInfo
```
`OID4VPDCAPIHandover` parameters:
- The first element MUST be the fixed UTF-8 encoded string `"OID4VPDCAPIHandover"`. This serves as a unique identifier for the handover structure to prevent misinterpretation or confusion.
- The second element MUST be the `OID4VPDCAPIHandoverInfoHash` encoded as a UTF-8 string representing the integrity hash of the `OID4VPDCAPIHandoverInfo` array. The value of `OID4VPDCAPIHandoverInfoHash` MUST comply with the W3C Subresource integrity format as defined in [!W3C.SRI], e.g., `sha256-H8BRh8j48O9oYatfu5AZzq6A9RINhZO5H16dQZngK7T62em8MUt1FLm52t+eX6xO`.
- `client_id` and `nonce` values are UTF-8 encoded strings provided in the Authorization Request from the Verifier.
- `origin` is a UTF-8 encoded string representing the origin of the Verifier. The value for `origin` MUST be obtained from the web platform or app platform being used.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One thing that is potentially missing in OID4VPDCAPIHandoverInfo is the public key of the verifier.


## IETF SD-JWT VC specific requirements for OpenID for Verifiable Presentations over W3C Digital Credentials API

* The Credential format identifier MUST be `dc+sd-jwt`.
Sakurann marked this conversation as resolved.
Show resolved Hide resolved
* IETF SD-JWT VC Credential Format specific DCQL parameters as defined in Section 6.4.1. of [@!OIDF.OID4VP] MUST be used.
Sakurann marked this conversation as resolved.
Show resolved Hide resolved


# Self-Issued OP v2

To authenticate the user, subject identifier in a Self-Issued ID Token MUST be used as defined in [@!OIDF.SIOPv2].
Expand All @@ -223,9 +285,7 @@ To authenticate the user, subject identifier in a Self-Issued ID Token MUST be u

# SD-JWT VCs {#sd-jwt-vc}

As credential format, SD-JWT VCs as defined in [@!I-D.ietf-oauth-sd-jwt-vc] MUST be used.

In addition, this profile defines the following additional requirements.
This profile defines the following additional requirements for SD-JWT VCs as defined in [@!I-D.ietf-oauth-sd-jwt-vc].
Sakurann marked this conversation as resolved.
Show resolved Hide resolved

* Compact serialization MUST be supported as defined in [@!I-D.ietf-oauth-selective-disclosure-jwt]. JSON serialization MAY be supported.
* The following JWT Claims MUST be supported Content (differentiate issuance & presentation)
Expand Down Expand Up @@ -383,6 +443,38 @@ Note: When using this profile with other cryptosuites, it is recommended to be e
</front>
</reference>

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<reference anchor="W3C.SRI" target="https://www.w3.org/TR/SRI/">
<front>
<author initials="D." surname="Akhawe" fullname="Devdatta Akhawe">
<organization>
<organizationName>Dropbox, Inc.</organizationName>
</organization>
</author>
<author initials="F." surname="Braun" fullname="Frederik Braun">
<organization>
<organizationName>Mozilla</organizationName>
</organization>
</author>
<author initials="F." surname="Marier" fullname="François Marier">
<organization>
<organizationName>Mozilla</organizationName>
</organization>
</author>
<author initials="J." surname="Weinberger" fullname="Joel Weinberger">
<organization>
<organizationName>Google, Inc.</organizationName>
</organization>
</author>
<title>Subresource Integrity</title>
<date day="23" month="June" year="2016"/>
</front>
</reference>

<reference anchor="ISO.18013-7" target="https://www.iso.org/standard/82772.html">
<front>
<title>ISO/IEC DTS 18013-7 Personal identification — ISO-compliant driving license — Part 7: Mobile driving license (mDL) add-on functions</title>
<author>
<organization> ISO/IEC JTC 1/SC 17 Cards and security devices for personal identification</organization>
</author>
<date year="2024"/>
</front>
</reference>

<reference anchor="ISO.23220-3" target="https://www.iso.org/standard/79125.html">
<front>
<title>ISO/IEC DTS 23220-3 Cards and security devices for personal identification — Building blocks for identity management via mobile devices</title>
<author>
<organization> ISO/IEC JTC 1/SC 17 Cards and security devices for personal identification</organization>
</author>
<date year="2023"/>
</front>
</reference>

<reference anchor="w3c.digital_credentials_api" target="https://wicg.github.io/digital-credentials/">
<front>
<title>Digital Credentials API</title>
<author fullname="Marcos Caceres">
<organization>Apple Inc.</organization>
</author>
<author fullname="Sam Goto">
<organization>Google</organization>
</author>
Sakurann marked this conversation as resolved.
Show resolved Hide resolved
</front>
</reference>

<reference anchor="VC-DATA" target="https://www.w3.org/TR/vc-data-model-2.0/">
<front>
<title>Verifiable Credentials Data Model v2.0</title>
Expand Down
Loading