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.

Sign up for GitHub

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

Merged
merged 21 commits into from
Dec 17, 2024
Merged

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

Changes from 2 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
125 changes: 103 additions & 22 deletions openid4vc-high-assurance-interoperability-profile-sd-jwt-vc-1_0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
%%%
title = "OpenID4VC High Assurance Interoperability Profile with SD-JWT VC - draft 01"
abbrev = "openid4vc-high-assurance-interoperability-profile-sd-jwt-vc"
title = "OpenID4VC High Assurance Interoperability Profile - draft 01"
abbrev = "openid4vc-high-assurance-interoperability-profile"
ipr = "none"
workgroup = "Digital Credentials Protocols"
keyword = ["security", "openid4vc", "sd-jwt", "sd-jwt-vc"]
keyword = ["security", "openid4vc", "sd-jwt", "sd-jwt-vc", "mdoc"]

[seriesInfo]
name = "Internet-Draft"
value = "openid4vc-high-assurance-interoperability-profile-sd-jwt-vc-1_0-01"
value = "openid4vc-high-assurance-interoperability-profile-1_0-01"
status = "standard"

[[author]]
Expand All @@ -30,7 +30,7 @@ organization="sprind.org"

.# 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 format SD-JWT VC and 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].

{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 format used is 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 SD-JWT VC and ISO mdoc [@ISO.18013-5] formats.

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 OID4VCI to issue IETF SD-JWT VCs (can be both remote and in-person), including
* Wallet Attestation
* Profile of OID4VP to present IETF SD-JWT VCs
* Profile of OID4VP 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)
* 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
* Cryptographic Holder Binding
* Issuer key resolution
* Issuer identification (as prerequisite for trust management)
* Crypto Suites

Note that when OID4VP 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 OID4VCI to issue ISO mdocs is defined in [@!ISO.23220-3].
Sakurann marked this conversation as resolved.
Show resolved Hide resolved
* Profile of OID4VP 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].
tlodderstedt marked this conversation as resolved.
Show resolved Hide resolved
Sakurann marked this conversation as resolved.
Show resolved Hide resolved

## Scenarios/Business Requirements

Expand All @@ -88,14 +96,14 @@ 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 enable interoperable implementation of the following four 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
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 four flows, but they MUST be compliant to all of the requirements for a particular flow they chose to implement.

# OpenID for Verifiable Credential Issuance

Expand Down Expand Up @@ -198,7 +206,7 @@ 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.

# OpenID for Verifiable Presentations
# OpenID for Verifiable Presentations without using W3C Digital Credentials API
Sakurann marked this conversation as resolved.
Show resolved Hide resolved
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).
* 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.
Expand All @@ -215,6 +223,57 @@ 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
Sakurann marked this conversation as resolved.
Show resolved Hide resolved

* MUST support Annex A in [@!OIDF.OID4VP] that defines how to use OID4VP over the W3C Digital Credentials API.
* Annex A.3.1. in [@!OIDF.OID4VP] MUST NOT be used. OID4VP requests over the W3C Digital Credentials API MUST be signed.
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.
* Response Mode MUST be `w3c_dc_api.jwt`. Encryption of the response is mandatory.
Sakurann marked this conversation as resolved.
Show resolved Hide resolved
* MUST support Transaction Data defined in Sections 5.4 and 7.4 of [@!OIDF.OID4VP].
Sakurann marked this conversation as resolved.
Show resolved Hide resolved
* The DQCL 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 DQCL query and response that MUST be supported:
* tbd

## ISO mdoc specific requirements for OpenID for Verifiable Presentations over W3C Digital Credentials API

* The Credential format identifier MUST be `mso_mdoc`.
* mdoc Credential Format specific DCQL parameters as defined in Section 6.4.2. of [@!OIDF.OID4VP] MUST be used.
* Verifier MAY request more than one credential in the same request.
* DeviceResponse in the VP Token MUST contain only one mdoc. Therefore, when multiple mdocs are being returned, each mdoc should be returned in a separate DeviceResponse, each matching to a respective DCQL query.
Copy link

Choose a reason for hiding this comment

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

I'm not sure if this is a good limitation, see also the issue with binding a single response to a single DCQL query in openid/OpenID4VP#336

Copy link
Contributor

Choose a reason for hiding this comment

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

I think this restriction makes sense given the constraints we currently have it doesn't make sense to have more than one mdoc in a single VP Token.

(I also agree we should look into that issue you raised.)

Copy link
Contributor

Choose a reason for hiding this comment

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

Why shouldn't it be possible to return multiple mdoc device responses in a single vp token?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

yes, made a suggestion here: https://github.com/openid/oid4vc-haip-sd-jwt-vc/pull/122/files#r1870520704

Copy link
Contributor Author

Choose a reason for hiding this comment

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

opened openid/OpenID4VP#397 to continue this discussion

Sakurann marked this conversation as resolved.
Show resolved Hide resolved
* Response encryption MUST be done as defined in Section B.4.3.3.2 in [@!ISO.18013-7].
Sakurann marked this conversation as resolved.
Show resolved Hide resolved
Sakurann marked this conversation as resolved.
Show resolved Hide resolved

### Session Transcript

The SessionTranscript as defined in [@ISO.18013-5] shall be used with the following changes:

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

The Handover element is defined as following:

```
Handover = OID4VPDCAPIHandover
OID4VPDCAPIHandover = [
"OID4VPDCAPIHandover"
clientId
Copy link

Choose a reason for hiding this comment

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

From a security perspective, what kind of attacks are mitigated by inclusion of the clientID in the sessiontranscript?
Inclusion of the clientId also has other issues, like which value is used if there are multiple signatures, or if the wallet ignores RP authentication.

Copy link
Contributor

Choose a reason for hiding this comment

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

Isn't that an audience restriction of the device response?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

yes, we need clientId as audience restriction.

Copy link
Contributor

Choose a reason for hiding this comment

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

Inclusion of the clientId also has other issues, like which value is used if there are multiple signatures, or if the wallet ignores RP authentication.

I think the multiple signature case is probably okay, the clientId applicable to the signature/ecosystem the Wallet/user chose to return a credential from is the one used.

If the wallet is ignoring RP authentication it should probably use the origin as the client id in the same way it would for an unsigned request - which means the origin is then included twice in the handover.

I'm not sure what additional audience restriction clientId is giving us when we already have the origin?

I've opened #135 so we can discuss further.

Copy link
Contributor

@tlodderstedt tlodderstedt Dec 3, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

The wallet must decide which audience a certain credential presentation is intended for, even in case of multiple signatures. It's a selection 1 out of n in case of multiple signatures. I can add text to openid/OpenID4VP#308.

origin
nonce
]

clientId = tstr
origin = tstr
nonce = tstr
Sakurann marked this conversation as resolved.
Show resolved Hide resolved
```

* `clientId` and `nonce` parameters in the Handover MUST be the `client_id` and `nonce` parameters included in the Request from the Verifier.
* `origin` in the Handover is the origin of the Verifer, obtained from the Web-platform and/or app platform.

## 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`.
* IETF SD-JWT VC Credential Format specific DCQL parameters as defined in Section 6.4.1. of [@!OIDF.OID4VP] MUST be used.
* When Key Binding JWT is used, `aud` value in it MUST be the origin of the Verifer, obtained from the Web-platform and/or app platform, and not `client_id` received in the Request.
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 Down Expand Up @@ -384,6 +443,28 @@ Note: When using this profile with other cryptosuites, it is recommended to be e
</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>

Sakurann marked this conversation as resolved.
Show resolved Hide resolved
<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>
</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