Reviewer: Dale Worley Review result: On the Right Track 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]