Skip to main content

Telechat Review of draft-ietf-acme-acme-07
review-ietf-acme-acme-07-genart-telechat-worley-2017-10-24-00

Request Review of draft-ietf-acme-acme
Requested revision No specific revision (document currently at 18)
Type Telechat Review
Team General Area Review Team (Gen-ART) (genart)
Deadline 2017-10-24
Requested 2017-09-27
Authors Richard Barnes , Jacob Hoffman-Andrews , Daniel McCarney , James Kasten
I-D last updated 2017-10-24
Completed reviews Genart Telechat review of -07 by Dale R. Worley (diff)
Opsdir Telechat review of -07 by Éric Vyncke (diff)
Tsvart Telechat review of -08 by Martin Stiemerling (diff)
Genart Last Call review of -11 by Dale R. Worley (diff)
Genart Telechat review of -12 by Dale R. Worley (diff)
Secdir Telechat review of -12 by Scott G. Kelly (diff)
Genart Last Call review of -13 by Dale R. Worley (diff)
Assignment Reviewer Dale R. Worley
State Completed
Request Telechat review on draft-ietf-acme-acme by General Area Review Team (Gen-ART) Assigned
Reviewed revision 07 (document currently at 18)
Result On the Right Track
Completed 2017-10-24
review-ietf-acme-acme-07-genart-telechat-worley-2017-10-24-00
I am the assigned Gen-ART reviewer for this draft.  The General Area
Review Team (Gen-ART) reviews all IETF documents being processed by
the IESG for the IETF Chair.  Please wait for direction from your
document shepherd or AD before posting a new version of the draft.

For more information, please see the FAQ at
<https://wiki.tools.ietf.org/area/gen/wiki/GenArtfaq>.

Document:  draft-ietf-acme-acme-07
Reviewer:  Dale R. Worley
Review Date:  2017-10-24
IETF LC End Date:  2017-09-14
IESG Telechat date:  2017-10-26

Summary:

This draft is on the right track but has open issues, described in the
review.

My general impression is that this is a sound piece of work, and
apparently one that satisfies a serious practical need.  But this
draft has a large number of open issues, and really needs a careful,
thorough clean-up pass.  And until that's done, it's not clear what
genuine problems might be lurking.

I haven't put in the time I would have liked to, so some of the issues
I've detected might prove to be nonexistent.  A lot of these issues
are simply English usage.  The structure of the exposition needs to be
improved, including pulling the specialized vocabulary into a
glossary, providing overviews of processes whose multiple details are
discussed, etc.  Some issues are technical slips, like missing
required fields in HTTP messages.  Some seem to be more substantial
technical issues -- What is the versioning and extensibility system?
What are the requirements on POST operations that effectively carry no
more information than that the operation happens?  And one question --
the terms of service agreement -- seems to brush into legal
territory.  The number and variety of these minor problems suggests
that the whole work needs to be thought through more carefully before
being frozen.

Within that context, I will not attempt to sort these items into
categories or rate them on importance, but just list them in order by
parts of the text that they relate to.  And note that a number of
these items are mentioned relative to only one of several places in
the text they apply to.

----------------------------------------------------------------------

There's a lot of talk about accounts, but no overview of the lifecycle
of an account.  Compare to the presentation of the overview of the
lifecycle of a certificate request.

There should be blanket policies on whether and where non-standard
fields can be included by both client and server.

Also, there ought to be versioning of Acme itself.

Abstract

   Certificates in PKI using X.509 (PKIX) are used for a number of
   purposes, the most significant of which is the authentication of
   domain names.

I'm no expert here, but it seems to me that "the authentication of
domain names" is not correct -- only actors can be authenticated.  I
think the accurate phrasing is "the authentication of servers (TLS,
HTTPS, etc.) which act on behalf of domain names".  (This would be a
minor matter in the body, especially if this elision was universally
used in the field, but an abstract should require little context.)

Ditto for the first paragraph of section 1.

   DISCLAIMER: This is a work in progress draft of ACME and has not yet
   had a thorough security analysis.

I assume that this is going to be removed once this document is
published as an RFC.  If the RFC hadn't had a thorough security
analysis, there would be no value in publishing it as an RFC.  However
there is no attached statement indicating when this statement is to be
removed.  What is actually going on here?

Table of Contents

    6.4.  Replay protection
    6.4.2.  "nonce" (Nonce) JWS header parameter
    6.5.  Rate limits

These section titles aren't capitalized the same way as the other
section titles.

1.  Introduction

   Existing Web PKI certificate authorities tend to run on a set of ad
   hoc protocols for certificate issuance and identity verification.

s/run on/use/?

   a typical user experience is something like:

I think you want to broaden this to "a typical protocol is".  That
doesn't change things much, because the user is one endpoint of the
protocol.  But you don't want to de-emphasize what the CA does,
either.  (I reflexively think of this as a protocol problem, whereas
the authors probably reflexively think of this as a user experience
problem.)

      *  Put a CA-provided challenge at a DNS location corresponding to
         the target domain.

What does "corresponding to" mean?  I think you want "in a DNS record
for the target domain".

      *  Receive CA challenge at a (hopefully) administrator-controlled
         email address corresponding to the domain and then respond to
         it on the CA's web page.

s/CA challenge/CA-provided challenge/ for parallelism.

s/corresponding to the domain/within the domain/?

It seems that there should be an item between the third and fourth
items:

    o  The CA makes the newly issued certificate accessible to the
    user (via the CA's web site?  via e-mail?)

--

   This document describes an extensible framework for automating the
   issuance and domain validation procedure, thereby allowing servers
   and infrastructural software to obtain certificates without user
   interaction.  Use of this protocol should radically simplify the
   deployment of HTTPS and the practicality of PKIX authentication for
   other protocols based on Transport Layer Security (TLS) [RFC5246].

I think you need some background on why this matters.  In the naive
default model, someone wants to set up a web server and needs to
obtain a certificate.  Yes, this will require 1 to 3 hours, but it's a
one-time cost over the life of the web site.  And I doubt that getting
one's self plugged into the Acme system of a CA will take *less* time.

Your model seems to be an operator that wants to set up many servers
that are authenticatable to many different identities, with each
identity being initially vouched for by the same operator.  But this
suggests that the multiple identities are third parties that are in
some way subordinate or derived identities to the operator's identity,
either "departments" within one entity, or customers of a vendor.

In particular, how does Acme work relative to the case where a service
provider claims it is setting up a web site for a third party?
[ruminations deleted] I think you need to underline that this only
handles the DV case, and not the OV and EV cases.  On the first
reading, I overlooked the bit about "automating the issuance and
domain validation procedure", and immediately started wondering how
Acme prevents a service provider from generating bogus web servers for
third parties, and thinking it doesn't.  But I reflexively think of
certificates in terms of OV rather than DV.  I suspect many readers
also make this assumption.

2.  Deployment Model and Operator Experience

   The guiding use case for ACME is obtaining certificates for websites
   (HTTPS [RFC2818]).

You probably want to emphasize "obtaining domain validation-type
certificates ".

   Prior to ACME, when deploying an HTTPS server, an operator typically

This is the first use of "operator", so you probably want to say "the
server operator".

   o  The ACME client prompts the operator for the intended domain
      name(s) that the web server is to stand for.

Probably want to say "The operator's ACME client" to make it clear
that the client is working for/controlled by/attached to/located at
the operator.

   o  In the background, the ACME client contacts the CA and requests
      that it issue a certificate for the intended domain name(s).

It seems that all of the remaining steps are "in the background", as
they can run to completion without operator intervention.  So I think
you want to emphasize "In the background" as an assertion about the
remaining steps as a group.

   o  The CA verifies that the client controls the requested domain
      name(s).

"here a miracle happens" -- I think you want to flesh this out or
provide a reference to the previous discussion, and especially
emphasize that the Internet operations are carried out by the Acme
client.  E.g., "The ACME client proves to the CA that the operator
controls the domain by one of the above-described methods."  But maybe
I'm being too fussy about the words "controls the requested domain
name(s)".

   o  Once the CA is satisfied, the certificate is issued 

There's no point using the passive when the subject has already been
used in the sentence:  "Once the CA is satisfied, it issues the
certificate".

   In this way, it would be nearly as easy to deploy with a CA-issued
   certificate as with a self-signed certificate.

As someone who detests setting up yet another account for yet another
web site, I would like you to modify this to, "once the operator has
an ACME relationship with one or more CAs, it would be nearly ...".

[Check how much work the operator needs to get his ACME client
connected to a CA.  If this is easy, emphasize it in the intro, as
it's a major virtue of ACME!]

3.  Terminology

   The two main roles in ACME are "client" and "server".  The ACME
   client uses the protocol to ...

   An ACME client is represented by an "account key pair".  The client
   uses the private key ...

These two paragraphs contain two sentences of terminology definition
and two paragraphs of setting up the structure of the ACME
client/server system.  That's not a bad thing, but it's more than
simply "Terminology".

Conversely, there's a lot of terminology in this draft that isn't
defined here.  Probably foremost is "operator", but there should also
be some explanation of the use of "response" when that is used to
describe an HTTP *request*.

One approach would be to move most of these two paragraphs into the
beginning of section 4, and then expanding section 3 to include
various terms that might not be familiar to people not fully involved
in certificate-issuance procedures.

   The server uses the public key to verify the
   authenticity and integrity of messages from the client.

What information is given to the server by authenticating the request
using the public key?  One possibility is that the server only needs
to know that two requests came from "the same" Acme client, in which
case all it needs to check is that both were signed by the same key.
But if the key conveys identity information to the server, how is that
managed?  That should be described (or referenced) at the very
beginning of the protocol description, as that is the first action of
the Acme protocol, setting up the client and connecting it to the CA.

   In many ways, ACME functions much like a traditional CA,

I think you mean, "In many ways, an ACME server functions ...".

   ACME allows a client to request certificate management actions using
   a set of JavaScript Object Notation (JSON) messages carried over
   HTTPS.  In many ways, ACME functions much like a traditional CA, in
   which a user creates an account, requests a certificate, and proves
   control of the domains in that certificate in order for the CA to
   sign the requested certificate.

The first sentence of this paragraph should go after the part about
setting up the client/server relationship.  The second sentence is
actually overview for all of section 4 and should stay at the
beginning of the section.

   The server then validates the challenges to check that the client
   has accomplished them.

You may want to say "validates the responses to the challenges".  (I'm
from an environment where the phrase "challenge/response" is used a
lot.)

   the server will issue the requested certificate and make it
   available to the client.

If the Acme protocol can actually carry the certificate to the client,
you probably want to make that clear in this sentence.  "and send it
to the client"?

         Order
         Signature                     ------->
                                                                Required
                                       <-------           Authorizations

I assume that messages from the server are also signed.  (How is the
client to authenticate that it is talking to the server it thinks it's
talking to?)  I'd say, "the server's signatures also ought to be
shown", but at this level of detail, I probably prefer that the
signatures not be shown, as they seem to cause me visual clutter.

This chart seems to leave out a lot of steps.  Perhaps:

         Order                         ------->         

                                       <-------  Required Authorizations

         [Perform response actions.]

         Response Notification         ------->

                                             [Verify response actions.]

                                       <-------             Certificate


6.2.  Request Authentication

      *  "jwk" (JSON Web Key, only for requests to new-account and
         revoke-cert resources)

   For new-account requests, and for revoke-cert requests authenticated
   by certificate key, there MUST be a "jwk" field.

These two requirements don't appear to be the same.

   If the client sends a JWS signed with an algorithm that the server
   does not support, then the server MUST return an error with status
   code 400 (Bad Request) and type
   "urn:ietf:params:acme:error:badSignatureAlgorithm".

This is hard to understand until the type field is introduced below.
(The type field doesn't seem to be a standard feature of JWS.)  Easier
wold be

   If the client sends a JWS signed with an algorithm that the server
   does not support, then the server MUST return an error document with status
   code 400 (Bad Request) and 
   "urn:ietf:params:acme:error:badSignatureAlgorithm" in the "type" field.

6.3.  Request URL Integrity

   As noted in Section 6.2 above, all ACME request objects carry a "url"
   header parameter in their protected header.

Actually, section 6.2 calls it a "field".  You should use consistent
terminology, particularly given that in the context of HTTP, the term
"header" has a special meaning.  (What is the general usage in JWS
discussions?)

   Except for the directory resource, all ACME resources are addressed
   with URLs provided to the client by the server.  For these resources,
   the client MUST set the "url" header parameter to the exact string
   provided by the server (rather than performing any re-encoding on the
   URL).  The server SHOULD perform the corresponding string equality
   check, configuring each resource with the URL string provided to
   clients and having the resource check that requests have the same
   string in their "url" header parameter.

This is awkwardly phrased.  Perhaps:

   Except for the directory resource, all ACME resources are addressed
   with URLs provided to the client by the server.  When addressing
   these resources, the client MUST set the "url" header parameter to
   the exact string provided by the server (rather than performing any
   re-encoding on the URL).  Conversely, the server MUST provide
   clients with the URLs by which the resources can be addressed
   through the server, and it SHOULD verify that the "url" header
   parameter the client provides when accessing a resource is the same
   string as the server provides clients for that resource.

6.3.1.  "url" (URL) JWS header parameter

Perhaps the last two paragraphs of section 6.3 should be moved into
this section.

This text is not as exact as I'd like.  What does "to which this JWS
object is directed" mean?  Do you mean "The request that contains this
object is not valid unless the HTTP request URL is exactly the same
string as the value of this header parameter."  And the phrase "be a
string representing the URL" is extremely dangerous.  Remember that a
URL *is* a string, and if you mess with character encodings or the
like, you get a *different* URL, albeit one that some process might
consider "equivalent" to the original URL for some purposes.

I'm not up to date on HTTP, but there are some complications regarding
what the "request URI" of a request is; it's not always just the value
of the "request-URI" field of the request-line.  There's probably a
set terminology for this concept; it would be wise to align with it.

6.4.  Replay protection

   In order to protect ACME resources from any possible replay attacks,

Could this be shortened to "In order to protect ACME resources from
replay attacks, ..."?

   Every JWS sent by an ACME client MUST include, in its protected
   header, 

It's vague here what "JWS" means as an unqualified noun.  I suspect,
"JWS object", but some other uses suggest that there is a larger JWS
construct within which the "object" is the "payload".  In any case,
the terminology should be brought into alignment with the JWS
standard(s).

It's not clear why the nonces are provided in the Replay-Nonce header
rather than being provided in the JWS response.  Compare when the
client sends the nonce, when it is provide inside the JWS object.
Indeed, this seems to be a layering violation -- the nonce is sent by
the server in a header, but sent by the client in the JWS.  It would
be cleaner to send the nonce in both directions in a header, or send
it in both directions in the JWS.  Perhaps the standard JWS
practice is to do it this way -- but the existence of section 6.4.1
suggests otherwise.

It might be worth noting that it is acceptable for the server to
"expire" unused nonces by not accepting nonces that were provided in
responses too far in the past.  (Assuming you want to allow it.)
Since a client is required to retry requests that are rejected due to
nonce failure, and that retry is expected to be done promptly, this
behavior does not cause protocol failure.  As written, this section
suggests that a server MUST NOT reject a request as long as the nonce
is valid, regardless of how long ago the nonce was issued.

6.4.1.  Replay-Nonce

This section reads very awkwardly.  I think the intention is to
provide a specification of the Reply-Nonce header field that stands
alone.  But it is a specification only in regard to the syntax of the
field, not the semantics.  OTOH, the first sentence of the section
seems to be trying to describe the semantics of the field, which is
confusing since it is nowhere near complete.  If you want to say
"generally, this field is to provide nonces that clients can use to
uniquely identify requests" you want to be careful to qualify it with
some statement that the exact usage is described in other
specifications.  Wording this correctly could get awkward.

The phrase "unique to each message" isn't clear with regard to scope.
Is it like SIP Call-Ids, which are unique over all space and time?  Or
just unique over the history of the server?

The language is not as clear as I'd like about where it appears.
Better to say "The server provides this header field in responses to
carry a server-generated nonce to the client..." and "The Replay-Nonce
header field MUST only be carried in HTTP response messages."

6.4.2.  "nonce" (Nonce) JWS header parameter

Again, this section hints at but does not specify the semantics of the
datum.

6.5.  Rate limits

   Creation of resources can be rate limited to ensure fair usage and
   prevent abuse.  Once the rate limit is exceeded, the server MUST
   respond with an error with the type
   "urn:ietf:params:acme:error:rateLimited".  Additionally, the server
   SHOULD send a "Retry-After" header indicating when the current
   request may succeed again.  If multiple rate limits are in place,
   that is the time where all rate limits allow access again for the
   current request with exactly the same parameters.

This is written as of rate limiting is some sort of global correctness
property -- which can't be reduced to any property observable by
either client or server.  The first sentence doesn't even state that
it's the *server* that can limit rates!  Better is to clarify the
intentions and roles of the various actors:

   A server MAY limit the rate at which it accepts various requests
   from various clients, e.g., to ensure fair usage and prevent abuse.
   If a server desires to postpone submission of a particular request,
   it MUST respond with an error with the type
   "urn:ietf:params:acme:error:rateLimited".  Additionally, the server
   SHOULD [I can't see a reason why this isn't MUST] include a
   "Retry-After" header indicating the time interval after which all
   limitations the server is currently applying to this request will
   permit processing of this request.  Different requests (even if from
   the same client) may be subject to different rate limits; the
   Retry-After value gives no information about other requests.

--

   In addition to the human readable "detail" field of the error
   response, the server MAY send one or multiple tokens in the "Link"
   header pointing to documentation about the specific hit rate limits
   using the "urn:ietf:params:acme:documentation" relation.

What does "token" mean here?  From context, I think you mean
"link-value" (after RFC 5988), or better, "URI".

Also, the value "urn:ietf:params:acme:documentation" doesn't seem to
be placed in the IANA registry described in section 9.6.

6.6.  Errors

   this document defines the
   following standard tokens for use in the "type" field (within the
   "urn:ietf:params:acme:error:" namespace):

This isn't correct terminology.  The namespace of these URNs is
"ietf".  Part of the problem is that there isn't a standardized term
for the parts of a URN that are separated by colons, despite that
almost all URN namespaces use colons as major separators.  I think
this version is both correct and readable:

   ... this document defines the following standard URIs for use in
   the "type" field (where each listed token is appended to
   "urn:ietf:params:acme:error:" to make the URI):

   +-----------------------+-------------------------------------------+
   | Token                 | Description                               |
   +-----------------------+-------------------------------------------+
   | badCSR                | The CSR is unacceptable (e.g., due to a   |
   |                       | short key)                                |

--

   This list is not exhaustive.  The server MAY return errors whose
   "type" field is set to a URI other than those defined above.  Servers
   MUST NOT use the ACME URN [RFC3553] namespace for errors other than
   the standard types.

"namespace" isn't really correct here, but I think "sub-namespace" is.

   Clients SHOULD display the "detail" field of all errors.

s/display/display to the user/

7.1.  Resources

   Each
   function is listed in a directory along with its corresponding URL,
   so clients only need to be configured with the directory URL.

s/a directory/the directory resource/

The "up" link relation from "cert" to the CA chain is not shown in the
figure.  The "index" link relation isn't shown at all, though that
couldn't be shown easily.  You might want to note that in some way in
the paragraph before the figure.

       | Submit an order      | POST new-order   | 201 -> order   |

When I first read this, I was unclear what an "order" is.  It turns
out that it is a request for a certificate.  E.g.,

   o  Order resources, representing an account's requests to issue
      certificates (Section 7.1.3)

You might want to either move toward the nomenclature "request a
certificate" or more heavily emphasize "order" in the text.  If you
enlarge section 2 to cover all the specialized terminology, putting an
entry in it for "order" would be helpful.

There are quite a number of example request responses that do not
contain the "index" link header.

The figure does not show the key-change resource.

7.1.1.  Directory

   whose fields names are drawn from the following table 

s/fields names/field names/

                   +-------------+--------------------+
                   | Field       | URL in value       |
                   +-------------+--------------------+
                   | new-nonce   | New nonce          |
                   |             |                    |
                   | new-account | New account        |
                   |             |                    |
                   | new-order   | New order          |
                   |             |                    |
                   | new-authz   | New authorization  |
                   |             |                    |
                   | revoke-cert | Revoke certificate |
                   |             |                    |
                   | key-change  | Key change         |
                   +-------------+--------------------+

In this table, one of the "URL in value" items is a predicate
(verb-object), which makes sense; one is a noun phrase naming an
action; and four are noun phrases (which are objects of an implied
"get" or "obtain").  I suggest rephrasing the items into predicates
directly telling what the URL does, e.g., "request new nonce", "change
key".

   There is no constraint on the actual URL of the directory except that

"actual" is probably superfluous here.

   The following metadata items are defined, all of which are OPTIONAL:

It would probably be wise to allow servers to include non-standard
metadata items.

   HTTP/1.1 200 OK
   Content-Type: application/json

This should be preceded by something like "An example response to a
directory GET is:".  I suggest providing some sort of direct
description of each example, and it would help to show requests and
responses together.  (But perhaps the RFC Editor thinks that unlabeled
examples are OK if the context makes their purpose clear enough.)

7.1.2.  Account Objects

   contact (optional, array of string):  An array of URLs that the
      server can use to contact the client for issues related to this
      account.  For example, the server may wish to notify the client
      about server-initiated revocation or certificate expiration.

Strictly, you want "URIs" here, as tel:, sip:, and mailto: URIs are
not URLs [RFC 6068].

7.1.2.1.  Orders List

How long does an order URL remain valid?  The particular URLs in the
example suggests that the order URLs are valid only as long as the set
of orders doesn't change.

A larger question is whether order objects are ever purged from the
orders list?

Indeed, these questions can be generalized -- Can the server ever
purge resources, invalidating the URLs that pointed to them?  What
sort of assurances can the client rely on?

7.1.3.  Order Objects

      For final
      orders, the authorizations that were completed.

What is a "final" order?  The term "final" is used in a number of
places, with possibly slightly different meanings, and needs to be
properly defined.

7.1.4.  Authorization Objects

   status (required, string):  The status of this authorization.
      Possible values are: "pending", "processing", "valid", "invalid"
      and "revoked".

It might be worth spelling out here what these states mean, as this is
the definition of this field of the authorization object.

      If this field is absent, then
      the CA MUST consider this authorization valid for all orders until
      the authorization expires.

There doesn't seem to be an "expired" status, so how can an
authorization expire?

      For final authorizations it contains the
      challenges that were successfully completed.

What is a "final" authorization?

   Section 8 describes a set of challenges for domain name validation.

Section 8 is about challenges generally; really the challenges for
domain name validation are sections 8.4 to 8.6.  Perhaps they should
be grouped into a subsection and this sentence should point to that?

7.3.  Account Creation

   If the server wishes to present the client with terms under which the
   ACME service is to be used, it MUST indicate the URL where such terms
   can be accessed in the "terms-of-service" subfield of the "meta"
   field in the directory object, and the server MUST reject new-account
   requests that do not have the "terms-of-service-agreed" set to
   "true".  Clients SHOULD NOT automatically agree to terms by default.
   Rather, they SHOULD require some user interaction for agreement to
   terms.

I note that there seems to be no recording of when the account was
created, i.e., *when* the terms of service was agreed to.  Since the
content behind the terms of service URL can change unpredictably,
noting that the terms of service were agreed to is meaningless unless
there is some fixation of the time of agreement.

   an error of type "invalidContact".

The wording of the text is inconsistent (or just unclear) whether
error types are give as full URNs or just the last component.

7.3.4.  Changes of Terms of Service

   The problem document returned with the error MUST also include an
   "instance" field, indicating a URL that the client should direct a
   human user to visit in order for instructions on how to agree to the
   terms.

This seems inconsistent with section 7.3, as the client can agree to
the terms of service when creating an account within Acme, but changes
in terms seem to require going out-of-band to agree to the new terms
of service.

Given that this could become a legal matter, it seems like a lot of
care and thought should be put in on this.  Ideally, a good lawyer
should be consulted on this.

 HTTP/1.1 403 Forbidden
 Replay-Nonce: IXVHDyxIRGcTE0VSblhPzw
 Link: <https://example.com/acme/terms/2017-6-02>;rel="terms-of-service"
 Content-Type: application/problem+json
 Content-Language: en

The various examples don't seem to be indented consistently.  Although
I expect the RFC Editor will clean that up.

7.3.5.  External Account Binding
 
   This can be used to an ACME account with an
   existing account in a non-ACME system, such as a CA customer
   database.

There's a word missing after "This can be used to".

   The server MAY require a value to be present for the "external-
   account-binding" field.

It would help the reader recover the context by starting this with,
"In an account creation request,".

   To enable ACME account binding, a CA needs to provision the ACME
   client with a MAC key and a key identifier.

You might want to annotate this, "by some means outside the scope of
this document", or "presumably as part of establishing the external
account".  And I would use "provide" rather than "provision" --
"provision" suggests to me that there is a specific provisioning
process that will be defined.

What is a "MAC key"?  I think you mean that any account binding must
be represented by a key pair for the external account, and the private
key of that pair is the "MAC key".

OTOH, this may be inconveniently heavy-weight for real-world use -- I
would expect the CA to simply provide a secret associated with the
external account.  (Or is that what a "MAC key" is?)

   The ACME client then computes a binding JWS to indicate the external
   account's approval of the ACME account key.

This isn't quite correct.  Perhaps

   The ACME client then computes a binding JWS to indicate that that
   the client, the owner of the external account, approves of the ACME
   account key.

Or is that "the client, on behalf of the owner of the external
account"?

--

   MUST reflect value of the "external-account-binding" field

s/reflect value/reflect the value/

7.3.6.  Account Key Roll-over

   The client then encapsulates the key-change object in a JWS, signed
   with the requested new account key (i.e., the key matching the
   "newKey" value).

   The outer JWS MUST meet the normal requirements for an ACME JWS (see
   Section 6.2).  The inner JWS MUST meet the normal requirements, with
   the following exceptions:

Some detail is being left out.  I think that the JWS described in the
first of these paragraphs becomes the "inner JWS" of the next
paragraph.  But exactly how that nesting is to be performed doesn't
seem to be described.

   3.  Check that the JWS protected header of the inner JWS has a "jwk"
       field.

Is the generation of the "jwk" field specified in the text anywhere?

7.4.  Applying for Certificate Issuance

   then the
   server MUST proactively issue the requested certificate and provide a
   URL for it in the "certificate" field of the order.

I'm not sure that "proactively" has a specific meaning.  I think you
can just s/proactively issue/issue/ and capture the desired meaning --
the server doesn't have to issue a certificate instantly, but it
cannot delay.

   The status of the order will indicate what action the
   client should take:

This list is part of the definition of the order object, and should be
put in section 7.1.3.

7.4.1.  Pre-Authorization

   In some cases, a CA running an ACME server might have a completely
   external, non-ACME process for authorizing a client to issue for an
   identifier.

I'm not sure that "client" is a proper subject for "issue".  Perhaps
you mean "for authorizing a client to be issued certificate(s) for an
identifier".

7.4.2.  Downloading the Certificate

   A certificate resource represents a single, immutable certificate.
   If the client wishes to obtain a renewed certificate, the client
   initiates a new order process to request one.

Though I think you want to add what you really mean, namely that the
new certificate will be fetched from a different URL.

7.5.  Identifier Authorization

   The server may declare
   that an authorization is only valid for a specific order by setting
   the "scope" field of the authorization to the URL for that order.

"scope" isn't shown in the figure in section 7.1.

7.5.1.  Responding to Challenges

   The server is said to "finalize" the authorization when it has

Despite the existence of a section titled "Terminology", very little
of the terminology created for this document is listed there.

8.  Identifier Validation Challenges

   Each challenge must describe:

This isn't right; a challenge doesn't describe anything.  But the
descriptions of the challenge types include various information, etc.

   status (required, string):  The status of this authorization.
      Possible values are: "pending", "valid", and "invalid".

I think you mean "the status of this challenge".  But you might mean
"the status of the authorization containing this challenge".

   validated (optional, string):  The time at which this challenge was
      completed by the server

I'm not sure in what sense you mean "completed by", since it's the
client that does the completing.  I think you mean "the time at which
the server recognized that the challenge was completed".

      The server can limit the size
      of this object by limiting the number of times it will retry a
      challenge.

Rather, "the number of times it will permit the client to retry a
challenge".  Actually, the semantics of this field probably depends on
the pattern of the actions by which the challenge is satisfied, and so
may be dependent on the challenge type.

   If the
   server sets a challenge's "status" to "invalid", it SHOULD also
   include the "error" field to help the client diagnose why the
   challenge failed.

Presumably, 'the "errors" field'.

Also, section 8.2, "The server MUST add an entry to the "errors" field
in the challenge after each failed validation query.", suggests that
the server MUST include the "errors" field, not just SHOULD include.

8.1.  Key Authorizations

   A key authorization is a string that expresses
   a domain holder's authorization for a specified key to satisfy a
   specified challenge, by concatenating the token for the challenge
   with a key fingerprint, separated by a "." character:

   key-authz = token || '.' || base64url(JWK_Thumbprint(accountKey))

In what way does a key authorization indicate something about a
"domain holder"?  The k.a. includes the token (presumably from the
challenge object) and a computation based on an account's (private)
key, so it includes information from the account holder.

Or do you mean that "in the challenge, a token will be sent by the
server that only the domain holder will be able to receive, and as
part of the account holder's response to the challenge, it composes a
key authorization string"?

Really, I doubt that this is understandable without first explaining
the general model of challenge/response that the challenge types
defined here use, and that model doesn't seem to be described
anywhere.  I think it would be very helpful if that model was
presented first, before the specific challenge types that use that
model.

Alternatively, you could just describe this as an abstract operation
on strings,

   key-authz(token, accountKey) =
       token || '.' || base64url(JWK_Thumbprint(accountKey))

and leave defining its semantics to where key-authz() is used.

   The "JWK_Thumbprint" step indicates the computation specified in
   [RFC7638], using the SHA-256 digest [FIPS180-4].  As noted in JWA
   [RFC7518] any prepended zero octets in the JWK object MUST be
   stripped before doing the computation.

The second sentence seems to be unclear.  Is the "JWK object" the
output of "JWK_Thumbprint(accountKey)"?  If so, why isn't it called
"the JWK_Thumbprint object"?  And the significance of "prepended zero
octets" is unclear; RFC 7518 does not include the word "prepend", so
presumably does not specify any prepending.  I suspect you mean that
some stage of the processing of RFC 7518 is modified by stripping
initial zero octets from some string, but such octets wouldn't be
described as "prepended".

8.2.  Retrying Challenges

   Clients can explicitly request a retry by re-sending their response
   to a challenge in a new POST request (with a new nonce, etc.).

Again, this makes sense only under the assumption that satisfying a
challenge has certain data-flow patterns, in that (apparently) the
client must send a "response" and then -- well, it's not entirely
clear what "a retry" is.  You really need to lay out this pattern --
and the names you use for the actions within it -- before you specify
the details of how clients and servers can perform it.

   In order to avoid
   denial-of-service attacks via client-initiated retries, servers
   SHOULD rate-limit such requests.

There are two uses of "request" in the preceding sentence -- which of
them is being rate-limited?

8.3.  HTTP Challenge

   With HTTP validation, the client in an ACME transaction proves its
   control over a domain name by proving that for that domain name it
   can provision resources to be returned by an HTTP server.

Better, "by proving that it can provision resources that are returned by
an HTTP server accessible using a URL whose host is that domain name".

   type (required, string):  The string "http-01"

You don't actually say that these two fields are part of HTTP
challenge objects.

      It MUST NOT contain any characters outside the base64url alphabet,
      including padding characters ("=").

This could be read two ways; are the padding characters part of "the
base64url alphabet", or are they part of "characters outside the
base64url alphabet"?  Perhaps:

      It MUST NOT contain any characters that are outside the
      base64url alphabet, or padding characters ("=").
   
or

      It MUST NOT contain any characters that are outside the
      base64url alphabet (including padding characters ("=")).

Maybe better would be "It must contain only characters in the
base64url alphabet including/excluding padding characters("=")."

Actually, this is just ugly to specify using English, because it's
really hard to say it without using two negatives in one sentence, and
making clear what the scope of each negative is.  I think the best
approach is to rely on the fact that RFC 7515 section 2 clearly
defines that "=" is *not* in the base64url alphabet:

      It MUST NOT contain any characters that are not in the base64url
      alphabet.

If someone complains this is unclear, add separate sentence saying
that following RFC 7515 section 2, "=" is not in the base64url
alphabet.

   The value of the resource MUST be the ASCII representation of the
   key authorization.

Given that the key authorization is an ASCII string, it's not clear
what its "ASCII representation" is.

   The client's response to this challenge indicates its agreement to
   this challenge by sending the server the key authorization covering
   the challenge's token and the client's account key.

I think you mean, "The client responds to this challenge by POSTing an
update to the challenge object, adding a "keyAuthorization" field
containing the key authorization derived from the challenge's token
and the client's account key."

   1.  Construct a URL by populating the URL template [RFC6570]
       "http://{domain}/.well-known/acme-challenge/{token}", where: *
       the domain field is set to the domain name being verified; and *
       the token field is set to the token in the challenge.

What do the "*" mean?

8.5.  DNS Challenge

   The record provisioned to the DNS is the base64url encoding of this
   digest.

This doesn't make sense, as a DNS record is not a string per se.
However, the next two sentences make clear what the DNS record should
be.

   _acme-challenge.example.org. 300 IN TXT "gfj9Xq...Rg85nM"

It's not clear where "gfj9Xq...Rg85nM" came from, as it's supposed to
be a SHA-256 digest.  Though the previous paragraph doesn't specify
how the digest is to be represented; in parallel to earlier
discussion, lower-case hexadecimal seems to be assumed.

8.6.  Out-of-Band Challenge

   the client indicates this by sending a simple
   acknowledgment response to the server.

The text doesn't describe what a "simple acknowledgements response"
is.

However, the other challenge types involve what seem to be parallel
acknowledgment responses that are required to contain copies of token
values, though in none of these cases does the POST carry any actual
information other than the fact that the POST was made to the
particular URL.  What is the reason for this inconsistency?  For that
matter, why does the payload of the response for this challenge
contain a "type" field?

Perhaps there is something I don't understand about these POSTs which
seem to convey no information other than triggering the server to take
some action with regard to the target resource.

9.1.  MIME Type: application/pem-certificate-chain

   The "Media Types" registry should be updated with the following
   additional value:

IMO it's better to phrase this, "The following entry should be added
to the "Media Types" registry:".  I like to use "update" only for
operations that modify existing entries.

   File should contain one or more certificates encoded as PEM according
   to RFC 7468 [RFC7468].

"should contain"?  I think you want to say "File contains".  Actually,
"File must consist of ...".

"encoded as PEM" seems to be undefined by RFC 7468.  Perhaps "encoded
using PEM textual encoding according to RFC 7468" is meant.

9.6.  URN Sub-namespace for ACME (urn:ietf:params:acme)

I don't see how this specifies that this registry is connected with
the the registry (ACME Error Types, section 9.7.3) which provides the
final component of "urn:ietf:params:acme:*" URNs.  I suspect you want
the "Repository" datum in this section to state that it points to the
registry created per section 9.7.3.

9.7.  New Registries

Is there a registry for fields in authorization objects?

9.7.4.  Resource Types

Are there entries for "new-nonce" and "new-authz"?

[END]