Hi Oliver, hi Daniel, hi Brian!
Hi all,
as a document shepherd I have reviewed the specification and here are a
few comments.
The draft currently repeats the idea that an SD-JWT VC can exist without
selectively disclosable claims several times. The normative statement in
Section 3.2.2.4 seems sufficient. The earlier mentions could likely be
shortened or removed to avoid repetition.
Section 2: I suggest either moving the current Scope text into the
Introduction or expanding it. As written, Section 2 contains only two
bullets and does not describe the document very precisely.
In particular, the abstract says that the specification describes "data
formats" and "validation and processing rules", which seems broadly
consistent with the document. By contrast, Section 2 says that the
document defines "a data model and media types", which feels imprecise
and incomplete.
The document appears to do at least the following:
- define an application-specific SD-JWT profile for verifiable digital
credentials (Section 3),
- define the application/dc+sd-jwt media type (Section 3.1),
- define JWT VC Issuer Metadata (Section 4),
- define SD-JWT VC Type Metadata, with separate sections for Display
Metadata and Claim Metadata (Sections 5, 7, and 8),
- define document integrity metadata for referenced documents (Section 6).
I think the Scope section should either be merged into the Introduction
or rewritten so that the claimed scope better matches what the draft
actually specifies. I personally would prefer an expanded text in the
introduction section.
The document currently explains the "digital credential" / "verifiable
credential" terminology transition in three places: Section 1.4, Section
3.1, and Section 3.2.1. I think one substantive explanation is enough.
Repeating the background several times adds text without helping
readers. I suggest keeping the main explanation in one place, for
example in Section 1.4, and shortening the later occurrences to brief
forward references or removing the historical detail altogether.
The three explanations are in
- Section 1.4, which explains why the document uses "Verifiable Digital
Credential" and mentions alignment with newer terminology.
- Section 3.1, which explains that dc stands for "digital credential"
described as a conceptual synonym for "verifiable credential".
- Section 3.2.1, which explains the history of changing typ from
vc+sd-jwt to dc+sd-jwt.
Section 3.2.2.2 appears to restate material that is already covered
generically in RFC 9901 Section 9.7. My understanding is that the
purpose here is to define the application-specific profile for SD-JWT
VC, which RFC 9901 explicitly anticipates. If so, it may be clearer to
reference RFC 9901 for the general rule and keep only the
SD-JWT-VC-specific profiling decisions in this section, rather than
repeating the generic guidance for claims such as iss, nbf, exp, and
cnf. This would make it easier for readers to distinguish what is
inherited from SD-JWT from what is newly specified by the VC profile.
Section 3.5: I suggest reconsidering the title "Issuer Signature
Mechanisms".
As written, this section does not really define signature mechanisms in
the cryptographic sense. The signature mechanism is handled by JOSE/JWS
and the alg value. Rather, this section defines how the recipient
determines the issuer's public verification key and validates that the
key belongs to the issuer identified by the SD-JWT VC.
That is also how RFC 9901 frames the relevant check: the recipient must
validate the Issuer and that the signing key belongs to that Issuer. In
that sense, Section 3.5 appears to be about verification-key resolution
/ validation, or more generally issuer-to-key binding, rather than about
signature mechanisms.
I therefore suggest renaming the section to something like "Issuer
Verification Key Discovery and Validation" or "Issuer Verification Key
Binding Mechanisms". I think this would better reflect what the section
actually specifies.
I also suggest making the trust model distinction between the two
defined cases more explicit. The "JWT VC Issuer Metadata" case uses
HTTPS-based metadata retrieval and obtains keys from issuer metadata,
whereas the x5c case uses an X.509 certificate chain carried in the
SD-JWT header and validates that chain directly. Those are different
ways of establishing trust in the issuer-key binding, not different
signature mechanisms. Both mechanisms rely on the use of X.509
certificates. In former case indirectly through TLS usage in HTTPS and
in the latter case throught the x5c parameter.
Section 3.2.2.1: The examples urn:eudi:pid:aendgard:1 and
urn:eudi:pid:aendgard:2 do not seem appropriate as generic example URNs.
Since this text is illustrative, I suggest either using the RFC 6963
example namespace (e.g., urn:example:eudi:pid:aendgard:1).
Section structuring - Sections 5 to 8:
I think Sections 7 and 8 would fit better as subsections of Section 5.
Section 5.2 defines display and claims as Type Metadata properties and
then points to Sections 7 and 8 for their detailed syntax and
processing. In particular, "Claim Metadata" does not appear to be a
separate kind of metadata document. Instead, it is the detailed
definition of the claims property within Type Metadata. Section 6,
however, seems top-level because it applies to the SD-JWT VC itself
(vct#integrity) and to Type Metadata.
Section 6 might benefit from a more precise title. "Document Integrity"
sounds broader than the actual scope of the section, which is integrity
verification of referenced documents retrieved via vct, extends, and uri
using #integrity values. Something like "Integrity of Referenced
Documents" seems closer to what the section actually specifies.
Additionally, Section 6 would benefit from a short introductory
paragraph explaining the purpose of the integrity mechanism at a high
level. The current text immediately defines the #integrity rule, but it
does not first explain that the mechanism is meant to protect externally
retrieved metadata or rendering assets against substitution or
unexpected change. A brief overview up front would make the section
easier to follow. For example, something like the following could help:
"This section defines how integrity can be asserted for documents
referenced by an SD-JWT VC and its Type Metadata. For references such as
vct, extends, and uri, a corresponding #integrity value can be used to
identify the expected content of the retrieved document. If such an
integrity value is present, the Consumer verifies that the retrieved
document matches it before processing that document."
The draft uses examples in an inconsistent way. Some are explicitly
labeled "non-normative" (e.g., Figure 2), some are covered by a
section-wide statement (Section 5.1), some by an appendix-wide statement
(Appendix B), and others are introduced simply as "an example" without
saying whether they are normative or not (e.g., Figure 13). I suggest
using one consistent convention throughout the draft, for example either
labeling every example explicitly as non-normative or adding a single
clear statement that all examples and figures containing sample data are
non-normative unless stated otherwise. Intuitively, examples are not
not-normative and hence stating that they are not-normative appears
redundant to me.
There are formatting problems with Figure 29 "Example Type Metadata
Document". Add line breaks.
For convenience I filed small nits as PRs, see
https://github.com/oauth-wg/oauth-sd-jwt-vc/pulls
Ciao
Hannes
_______________________________________________
OAuth mailing list -- [email protected]
To unsubscribe send an email to [email protected]
