I approve the changes to Appendix A.3 Deb
On Tue, Nov 18, 2025 at 1:06 AM Sandy Ginoza <[email protected]> wrote: > Greetings Authors, Deb*, > > * Deb, please see the update related to Appendix A.3 below and let us know > if you approve. > > Thank you for your quick and thorough response to our questions! Please > see some notes below. Note that we have snipped the resolved items. > > > > - Section 4.2.3: “The bytes of the output of the hash function MUST be > base64url > > encoded” > > > > DF: Is it correct to not hyphenize “base64url encoded” and “hex encoded” > in this sentence? I do understand that (and why) “base64url encoding” is > correct, as well as “base64url-encode”, but I would expect > “base64url-encoded” to be correct as well. (There are other instances in > the document as well.) > > [rfced] Per the Hyphenation Guide in the Chicago Manual of Style (Section > 7.96), we believe no hyphen is correct. We believe it falls into the > category of noun + participle, which means it would be hyphenated when > appearing before then noun but otherwise open (for example, “a > base64url-encoded value" but "a value that is base64url encoded"). We have > not made any updates for this one; please let us know if you have concerns. > > > > > - Appendix A.3, first two sentences. > > > > DF: The PID Rulebook referenced in the first sentence has since been > updated and an up-to-date example of how to use it with SD-JWT is now > provided in the SD-JWT VC specification. Nonetheless, the example in the > text is useful. The reference to the PID Rulebook should therefore be > removed. Please replace the first paragraph by the following text: > > > > "This example shows how the artifacts defined in this specification > could be used in the context of SD-JWT-based Verifiable Credentials (SD-JWT > VC) [SD-JWT-VC] to represent a hypothetical identity credential with the > data of a fictional German citizen." > > [rfced] * Deb - We updated the text as requested and removed [EUDIW.ARF] > from the references. Please review and let us know if this update is > approved. > > > > > 1) <!-- [rfced] Document title: We expanded "JWT" in the document > title. > > Please let us know if you have any concerns. > > > > Original: > > Selective Disclosure for JWTs (SD-JWT) > > > > Currently: > > Selective Disclosure for JSON Web Tokens (SD-JWTs) --> > > > > DF: Works for me, but I don’t think we should use the plural for the > short form. (I see that in the edited document, plural forms were used for > JWT and JWS in the intro. My personal feeling is that this is not required, > but I can live with either.) > > > > BC: I agree with not using plural for the short form. The title could be > “Selective Disclosure for JSON Web Token (SD-JWT)” or even “Selective > Disclosure for JSON Web Tokens (SD-JWT)” but the s on SD-JWTs doesn’t work > very well at all in my opinion. In the content of the document I’d also > generally prefer non-plural short forms like JWS and JWT as referring to > the conceptual thing. > > > > KY: I’m ok with Selective Disclosure for JSON Web Token (SD-JWT) > > [rfced] We removed the s. However, related to this discussion: > > > a) The following terms appear to be used inconsistently in this > > document. Please let us know which form is preferred. > > > > Selective Disclosure for JWTs (SD-JWT) / > > Selectively Disclosable JWT (SD-JWT) > > > [rfced] We suggest removing the abbreviation from the document title. > Perhaps the title could be: > > Selective Disclosure for JSON Web Tokens > > That way, there will be one expansion and future documents will expand > "SD-JWT” correctly as Selectively Disclosable JWT. > > We could add SD-JWT as a keyword in the database, so this document appears > in RFC-Editor search results. > > > > > 2) <!-- [rfced] Regarding <artwork> and <sourcecode> settings in this > > document: > > > > a) Section 4.2.6: We see that the first entry with > > '"family_name": "Möbius"' is labeled as '<sourcecode type="json">' > > but the next two entries in this section are labeled as > > '<sourcecode>' (no type included). May we change '<sourcecode>' to > > '<sourcecode type="json">' for these other two entries? > > > > b) We see several entries with '<sourcecode type="txt">'. Please > > note that "txt" is not listed as an approved type on > > <https://www.rfc-editor.org/rpc/wiki/doku.php?id=sourcecode-types>. > > Would "test-vectors" be more appropriate? RFC 9879 provides an > > example of using the "test-vectors" type; please see > > <https://www.rfc-editor.org/info/rfc9879> for access to its XML file. > > > > If not, do you suggest that "txt" be added as an > > additional sourcecode type? > > > > c) Please review the items labeled as <artwork> in > > Appendices A.5 and B, and let us know if we may label them as > > <sourcecode> with type="json" instead. For example, should the JSON > > object shown under the text "a JSON object such as this" be set to > > <sourcecode> with type="json"? --> > > > > DF: a) yes > > [rfced] This is complete. > > > > DF: b) The ‘txt’ seems to be an artifact of our tool chain. While our > examples can serve as test vectors, I have doubts whether marking them with > the type ‘test-vectors’ provides any useful formatting hints. I’m fine with > either test-vectors or no type. > > [rfced] We left type=“” (empty). > > > > DF: c) Yes for A.5. For Appendix B, the examples are not correct JSON > due to their abbreviated nature. If that is not a hard requirement, I’d be > fine with using sourcecode and labelling them as type json. > > [rfced] It is not a requirement, so we added type=“json". > > > > 3) <!-- [rfced] Sections 4 and 4.2.4.2: The following lines are too > > long for the text output. We get the following warnings from > > xml2rfc: > > > > (252): Warning: Too long line found (L423), 5 characters longer than 72 > characters: > > <Issuer-signed JWT>~<Disclosure 1>~<Disclosure 2>~...~<Disclosure > N>~<KB-JWT> > > > > (512): Warning: Too long line found (L786), 2 characters longer than 72 > characters: > > ["DE", {"...":"w0I8EKcdCtUPkGCNUrfwVp2xEgNjtoIDlOxc9-PlOhs"}, "US"] > > > > Would the suggested line breaks be acceptable? If not, please let us > > know where these lines should be broken. > > > > Perhaps: > > <Issuer-signed JWT>~<Disclosure 1>~<Disclosure 2>~... > > ~<Disclosure N>~<KB-JWT> > > ... > > ["DE", {"...":"w0I8EKcdCtUPkGCNUrfwVp2xEgNjtoIDlOxc9-PlOhs"}, > > "US"] --> > > > > DF: In Section 4, a line break might confuse readers. I would suggest > instead to abbreviate “Disclosure” to “D.” and explain in the text: > > “The compact serialized format for the SD-JWT is the concatenation of > each part delineated with a single tilde ('~') character as follows, where > “D.1” to “D.N” represent the respective disclosures: > > > > <Issuer-signed JWT>~<D.1>~<D.2>~...~<D.N>~” > > > > — and the same for the following example. > > [rfced] We have updated as noted. Please review and let us know if the > updates are as expected. > > > > For Section 4.2.4.2, the proposed line break works. > > > > KY: +1 to Daniel’s suggestion! Any other place in the spec we should be > using this abbreviation..? > > > > DF: Not needed as far as I can see. > > [rfced] Unfortunately, it looks like I missed one previously. Please let > us know how this line should be broken: > > Warning: Too long line found (L4759), 1 characters longer than 72 > characters: > "address": {"locality":"Schulpforta", "street_address":"Schulstr. 12"} > > > > > 4) <!-- [rfced] Regarding the use of font styling (i.e., <tt> and > <strong>), > > please review the questions below. > > > > Note: For <tt>-related items, view the list here: > > https://www.rfc-editor.org/authors/rfc9901tt.txt > > > > a) May we update instances of <tt>none</tt> to "none" for increased > clarity > > in the text file, and for consistency with RFCs 8725 and 9781? > > > > It MUST NOT use the none algorithm. > > > > - alg: REQUIRED. A digital signature algorithm identifier such > > as per IANA "JSON Web Signature and Encryption Algorithms" > > registry. It MUST NOT be none. > > > > The none algorithm MUST NOT be accepted. (2x) > > > > b) In general, please review the use of <tt> and note that there are no > > visual marks in the text file. Is the goal of <tt> to indicate > fixed-width > > font or to call attention to the various items? > > > > Some similar text seems to be marked as both <sourcecode> and <tt>. > > Please review and consider updating the XML file for consistency as > needed. > > > > For example, we see the following, which seem similar. Was <tt> used in > > running text? > > > > <sourcecode type=“json”><![CDATA[ > > [“_26bc4LT-ac6q2KI6cBW5es”, “family_name”, “Möbius”] > > ]]> > > </sourcecode> > > > > > > <tt>["2GLC42sKQveCfGfryNRN9w", "given_name", "Erika"]</tt> > > > > > > c) May we reformat the bulleted items that use <strong> as shown below? > Note > > that we reformatted the entry for "Claim given_name:" in Section 5.1 so > you > > can see the update in context. We believe this will make the groupings > > more clear and allow us to avoid the use of bold, which displays as > > asterisks in the text (which looks awkward because the *claim name* > (with asterisks) is followed by a list with asterisks as bullets). > > > > Original: > > *Claim given_name*: > > > > * SHA-256 Hash: jsu9yVulwQQlhFlM_3JlzMaSFzglhQG0DpfayQwLUK4 > > * Disclosure: > > WyIyR0xDNDJzS1F2ZUNmR2ZyeU5STjl3IiwgImdpdmVuX25hbWUiLCAiSm9o > > biJd > > * Contents: ["2GLC42sKQveCfGfryNRN9w", "given_name", "John"] > > > > *Claim family_name*: > > > > Perhaps: > > * Claim given_name: > > > > - SHA-256 Hash: > > > > jsu9yVulwQQlhFlM_3JlzMaSFzglhQG0DpfayQwLUK4 > > > > - Disclosure: > > > > WyIyR0xDNDJzS1F2ZUNmR2ZyeU5STjl3IiwgImdpdmVuX25hbWUiLCAiSm9obiJ > > d > > > > - Contents: > > > > ["2GLC42sKQveCfGfryNRN9w", "given_name", "John"] > > > > *Claim family_name*: > > --> > > > > DF: a) yes. > > [rfced] All instances of <tt>none</tt> have been updated to “none”. > > > > > DF: b) We use tt to represent strings used literally in the > format/protocols (usually in running text), sourcecode for more or less > complete examples, usually as separate blocks and multiline. I *think* the > current usage is fine, but happy to change if that is not the correct usage > of tt/sourcecode. > > [rfced] We have not made any adjustments to the use of <tt> or > <sourcecode>. > > > > DF: c) looks fine to me. > > [rfced] Ok - we have updated the lists using <strong> throughout. Please > let us know if any updates are needed. > > Looking at where <strong> remains, we wonder whether the first 2 terms in > section 1.2 should be updated as follows to be similar to the rest of the > definition list appearing there. > > Current (Selective Disclosure included for context): > *Base64url* denotes the URL-safe base64 encoding without padding > defined in Section 2 of [RFC7515]. > > Throughout this document, the term "claims" refers generally to > object properties (name/value pairs) as well as array elements. > > Selective Disclosure: > Process of a Holder disclosing to a Verifier a subset of claims > contained in a JWT issued by an Issuer. > > > Perhaps: > Base64url: Denotes the URL-safe base64 encoding without padding > defined in Section 2 of [RFC7515]. > > Claims: In this document, refers generally to object properties > (name/value pairs) as well as array elements. > > Selective Disclosure: > Process of a Holder disclosing to a Verifier a subset of claims > contained in a JWT issued by an Issuer. > > > > > 6) <!-- [rfced] May we change "taken" to "chosen" or "preferred" for > clarity? > > > > Section 4.2.3: > > In an SD-JWT+KB, kb_jwt MUST be present when using the JWS JSON > > Serialization, and the digest in the sd_hash claim MUST be taken over > > the SD-JWT as described in Section 4.3.1. > > > > Section 4.3.1: > > The sd_hash value MUST be taken over the US-ASCII bytes of > > the encoded SD-JWT, i.e., the Issuer-signed JWT, a tilde character, > > and zero or more Disclosures selected for presentation to the > > Verifier, each followed by a tilde character: > > > > Section 8.1: > > In an SD-JWT+KB, kb_jwt MUST be present when using the JWS JSON > > Serialization, and the digest in the sd_hash claim MUST be taken over > > the SD-JWT as described in Section 4.3.1. > > --> > > > > DF: “taken” here is used in the sense of “computed”, which we could use > if “taken” is not clear. “chosen” and “preferred” do not convey the right > meaning. > > [rfced] Thank you for the explanation - we have updated to use “computed”. > > > > > 13) <!-- [rfced] We updated the format of the media type registrations > to better > > align with the format used by IANA. We also created subsections for > each of the > > registrations. Please review Section 11.2 carefully and let us know if > a) any > > changes are desired for the section titles or b) if you object to the > updated > > format. > > --> > > > > DF: Looks good to me, but I’d leave the final verdict to Brian. > > > > BC: I’d avoided distinct subsections for each one in both media types > and claims because I felt like it would clutter the Table of Contents > unnecessarily. But I don’t feel strongly about it. > > [rfced] Thank you for the explanation - we have updated the XML so those > sections don’t appear in the table of contents. > > > > > 17) <!-- [rfced] Please let us know if any changes are needed for the > > following: > > > > a) The following terms appear to be used inconsistently in this > > document. Please let us know which form is preferred. > > > > Selective Disclosure for JWTs (SD-JWT) / > > Selectively Disclosable JWT (SD-JWT) > > > > b) holder (4 instances) / Holder > > > > also allowing the holder to reveal each of those nationalities > > With this set of disclosures, the holder could include the disclosure > > the holder would also need to include the disclosure with hash > > holder is a military member or may have a substance use disorder. > > > > c) key binding (2 instances) / Key Binding > > > > 206: cryptographic key binding that can be presented to and > verified > > 2437: Verifier or even for each session with a Verifier. New key > binding > > > > > > d) disclosure (35 instances) / Disclosure (251 instances) > > --> > > > > DF: a) I think we’re fine as-is. The first is the title of the > specification, the second the artifact, and I don’t think we’re creating > confusion here by referring to both as SD-JWT. > > [rfced] Our suggested handling is noted above in item 1). > > > > > DF: d) Disclosure(s) should be upper-cased everywhere, except where > preceded by “selective”, “minimal”, or “unauthorized” as these instances > refer to the act of disclosing something instead of the data structure. (Of > course, where ‘disclosures’ refers to the property in the data structure, > it should not be upper-cased. These instances are all formatted with <tt> > or <sourcecode>.) > > [rfced] We have reviewed instances of “disclosure” throughout and made > some updates based on the guidance above. Please review closely and let us > know any corrections. > > For example, we used Disclosure for "optional disclosure”, “disclosure > data”, “disclosure object”, and “respective disclosures”. > > Should “recursive disclosures” be “recursive Disclosures” as well? > > > [rfced] New: > e) Note that we added a period to <tt>nP5GYjw..</tt> (so it appears as > <tt>nP5GYjw...</tt>) - please let us know if this is incorrect. > > > Thank you again for your thorough review! > > Sandy Ginoza > RFC Production Center > > > > > On Nov 15, 2025, at 5:41 PM, [email protected] wrote: > > > > *****IMPORTANT***** > > > > Updated 2025/11/15 > > > > RFC Author(s): > > -------------- > > > > Instructions for Completing AUTH48 > > > > Your document has now entered AUTH48. Once it has been reviewed and > > approved by you and all coauthors, it will be published as an RFC. > > If an author is no longer available, there are several remedies > > available as listed in the FAQ (https://www.rfc-editor.org/faq/). > > > > You and you coauthors are responsible for engaging other parties > > (e.g., Contributors or Working Group) as necessary before providing > > your approval. > > > > Planning your review > > --------------------- > > > > Please review the following aspects of your document: > > > > * RFC Editor questions > > > > Please review and resolve any questions raised by the RFC Editor > > that have been included in the XML file as comments marked as > > follows: > > > > <!-- [rfced] ... --> > > > > These questions will also be sent in a subsequent email. > > > > * Changes submitted by coauthors > > > > Please ensure that you review any changes submitted by your > > coauthors. We assume that if you do not speak up that you > > agree to changes submitted by your coauthors. > > > > * Content > > > > Please review the full content of the document, as this cannot > > change once the RFC is published. Please pay particular attention to: > > - IANA considerations updates (if applicable) > > - contact information > > - references > > > > * Copyright notices and legends > > > > Please review the copyright notice and legends as defined in > > RFC 5378 and the Trust Legal Provisions > > (TLP – https://trustee.ietf.org/license-info). > > > > * Semantic markup > > > > Please review the markup in the XML file to ensure that elements of > > content are correctly tagged. For example, ensure that <sourcecode> > > and <artwork> are set correctly. See details at > > <https://authors.ietf.org/rfcxml-vocabulary>. > > > > * Formatted output > > > > Please review the PDF, HTML, and TXT files to ensure that the > > formatted output, as generated from the markup in the XML file, is > > reasonable. Please note that the TXT will have formatting > > limitations compared to the PDF and HTML. > > > > > > Submitting changes > > ------------------ > > > > To submit changes, please reply to this email using ‘REPLY ALL’ as all > > the parties CCed on this message need to see your changes. The parties > > include: > > > > * your coauthors > > * [email protected] (the RPC team) > > > > * other document participants, depending on the stream (e.g., > > IETF Stream participants are your working group chairs, the > > responsible ADs, and the document shepherd). > > * [email protected], which is a new archival > mailing list > > to preserve AUTH48 conversations; it is not an active discussion > > list: > > * More info: > > > https://mailarchive.ietf.org/arch/msg/ietf-announce/yb6lpIGh-4Q9l2USxIAe6P8O4Zc > > * The archive itself: > > https://mailarchive.ietf.org/arch/browse/auth48archive/ > > > > * Note: If only absolutely necessary, you may temporarily opt out > > of the archiving of messages (e.g., to discuss a sensitive > matter). > > If needed, please add a note at the top of the message that you > > have dropped the address. When the discussion is concluded, > > [email protected] will be re-added to the CC list > and > > its addition will be noted at the top of the message. > > > > You may submit your changes in one of two ways: > > > > An update to the provided XML file > > — OR — > > An explicit list of changes in this format > > > > Section # (or indicate Global) > > > > OLD: > > old text > > > > NEW: > > new text > > > > You do not need to reply with both an updated XML file and an explicit > > list of changes, as either form is sufficient. > > > > We will ask a stream manager to review and approve any changes that seem > > beyond editorial in nature, e.g., addition of new text, deletion of > text, > > and technical changes. Information about stream managers can be found > in > > the FAQ. Editorial changes do not require approval from a stream > manager. > > > > > > Approving for publication > > -------------------------- > > > > To approve your RFC for publication, please reply to this email stating > > that you approve this RFC for publication. Please use ‘REPLY ALL’, > > as all the parties CCed on this message need to see your approval. > > > > > > Files > > ----- > > > > The files are available here: > > https://www.rfc-editor.org/authors/rfc9901.xml > > https://www.rfc-editor.org/authors/rfc9901.html > > https://www.rfc-editor.org/authors/rfc9901.pdf > > https://www.rfc-editor.org/authors/rfc9901.txt > > > > Diff file of the text: > > https://www.rfc-editor.org/authors/rfc9901-diff.html > > https://www.rfc-editor.org/authors/rfc9901-rfcdiff.html (side by > side) > > > > Diff of the XML: > > https://www.rfc-editor.org/authors/rfc9901-xmldiff1.html > > > > > > Tracking progress > > ----------------- > > > > The details of the AUTH48 status of your document are here: > > https://www.rfc-editor.org/auth48/rfc9901 > > > > Please let us know if you have any questions. > > > > Thank you for your cooperation, > > > > RFC Editor > > > > -------------------------------------- > > RFC 9901 (draft-ietf-oauth-selective-disclosure-jwt-22) > > > > Title : Selective Disclosure for JWTs (SD-JWT) > > Author(s) : D. Fett, K. Yasuda, B. Campbell > > WG Chair(s) : Hannes Tschofenig, Rifaat Shekh-Yusef > > Area Director(s) : Deb Cooley, Paul Wouters > >
-- auth48archive mailing list -- [email protected] To unsubscribe send an email to [email protected]
