Reviewer: Carsten Bormann Review result: Ready with Issues Thank you for an easy-to-read document that is accessible even to readers who are not ACME experts. # Minor technical ## "default value" subdomainAuthAllowed is said to have a default value (value assumed if not included) of false, i.e., absence of the field implies the value to be false (except in metadata, which is a separate inconsistency that might surprise implementers). However, in several places, the text seems to instruct the server to specifically include subdomainAuthAllowed with a value of false in certain cases, apparently turning this into a three-valued field (true, false, absent). Which one is it? (This could easily become an interoperability problem.) ## security considerations The security considerations do not discuss the actual security considerations of enabling operations on subdomains, in particular in case where a subdomain is delegated in DNS. # Major editorial ## restatement vs. new normative content Providing a specification of a new feature added to ACME, the text explains a number basic ACME mechanisms that are relevant to this specification. One pervasive problem is that these restatements of RFC 8555 content are not always easy to distinguish from new, normative statements made by this document. E.g., 4.2 contains a statement about "is defined" that is part of a paragraph restating RFC 8555 -- this one, however, appears to be new normative content. (Languagetool diagnoses overuse of passive voice, which exacerbates this problem.) (The first paragraph of section 4 repeats the last paragraph of section 3. But that is not a problem; redundancy can be good if it improves the flow, and this is clearly labeled as a restatement.) The introduction of section 4 is a summary/restatement of RFC 8555; section 4.1 introduces new normative content without warning (and leads the reader astray by actually referencing RFC 8555). ## terminology ### parent The term "parent" is usually reserved for the direct ancestor (single edge in the graph). What is defined here really is an "ancestor domain". (Given the definition of subdomain that explicitly includes self, each domain also is its own parent domain; I'm not clear whether this is intended here.) Unfortunately, this unusual terminology is now hard-coded in the names of fields added by this specification, so it is not a purely editorial decision to adjust the terminology to common usage. ### subdomain The definition of subdomain (of a domain given) appears to include the domain given. This fine point might be lost on the reader; it can be surprising (subalpine definitely does not include alpine). Several pieces of text sound like setting subdomainAuthAllowed to true only allows subdomains, which actually does not make a difference due to the subtlety of the meaning of subdomain. ### POST-as-GET request Term should probably be explicitly imported from Section 6.3 of RFC 8555. ### "standard" Section 4.2 discusses a "standard ACME workflow". Please do not use "standard" as a synonym of "basic", "regular", ... # Minor editorial ## abbrev ACME ACME is not currently marked as "well-known" (no expansion needed) on the abbreviations list (https://www.rfc-editor.org/materials/abbrev.expansion.txt). Both the title and the abstract should be reviewed as to how they will look like when ACME is expanded by the RFC editor. (RFC 8555 should probably be mentioned in the abstract.) ## recognizing restatements The abstract reads as if the statement about certification authority policy were always true. But this is just stating the precondition for the mechanism described here to be authorized? ## References The "CAB Browser Forum" reference is stated as undated, but does link to a specific edition 1.7.1 dated 2022-08-20. Is this intended to be a "latest version" reference? RFC 8555 clearly is a normative reference. (Other RFCs listed under informative are actually normative through this reference as well.) Compounding the restatement anti-pattern, some restatements are missing the necessary reference, e.g., the start of Section 3. # Nits (editorial: inconsistent use of periods at the end of bullet items) More nits are fixed in: https://github.com/upros/acme-subdomains/pull/14 -- last-call mailing list last-call@xxxxxxxx https://www.ietf.org/mailman/listinfo/last-call
