Verify that the contents of one of the TXT records matches the digest value <del> It is RECOMMENDED that the server perform multiple DNS queries from various network perspectives, in order to make MitM attacks harder. </del> If all of the above verifications succeed, then the validation is successful.  If no DNS record is found, or DNS record and response payload do not pass these checks, then the validation fails. validation response for his own account key.  The risks due to hosting providers noted above are a particular case.  10.3. As a protocol run over HTTPS, standard considerations for TCP-based

Previously these were spread among the various challenges. We can simplify by putting them in one place. Replaces .

Verify that the contents of one of the TXT records matches the digest value  If all of the above verifications succeed, then the validation is successful.  If no DNS record is found, or DNS record and response payload do not pass these checks, then the validation fails. validation response for his own account key.  The risks due to hosting providers noted above are a particular case. <ins> It is RECOMMENDED that the server perform DNS queries and make HTTP and TLS connections from various network perspectives, in order to make MitM attacks harder. </ins> 10.3. As a protocol run over HTTPS, standard considerations for TCP-based


In order to help clients configure themselves with the right URIs for each ACME operation, ACME servers provide a directory object.  This should be the only URL needed to configure clients.  It is a JSON <del> dictionary, whose keys are drawn from the following table and whose </del>  values are the corresponding URLs. There is no constraint on the actual URI of the directory except that a host which only functions as an ACME server could place the directory under path "/". <del> The dictionary MAY additionally contain a key "meta".  If present, it MUST be a JSON dictionary; each item in the dictionary is an item of </del>  metadata relating to the service provided by the ACME server. The following metadata items are defined, all of which are OPTIONAL: The challenges that the client can fulfill in order to prove possession of the identifier (for pending authorizations).  For final authorizations, the challenges that were used.  Each array <del> entry is a dictionary with parameters required to validate the </del>  challenge.  A client should attempt to fulfill at most one of these challenges, and a server should consider any one of the challenges sufficient to make the authorization valid. client needs to respond with information to complete the challenges. To do this, the client updates the authorization object received from the server by filling in any required information in the elements of <del> the "challenges" dictionary.  (This is also the stage where the client should perform any actions required by the challenge.) </del>  The client sends these updates back to the server in the form of a JSON object with the response fields required by the challenge type, Template: <del> Field name: The string to be used as a key in the JSON dictionary </del>  Field type: The type of value to be provided, e.g., string, boolean, array of string Template: <del> Key: The value to be used as a dictionary key in the directory object </del>  Resource type: The type of resource labeled by the key

Follow-up to , catches a few more references I initially missed.
I think 'field name' makes more sense... but I'm not really wed to either.

In order to help clients configure themselves with the right URIs for each ACME operation, ACME servers provide a directory object.  This should be the only URL needed to configure clients.  It is a JSON  <ins> object, whose keys are drawn from the following table and whose </ins> values are the corresponding URLs. There is no constraint on the actual URI of the directory except that a host which only functions as an ACME server could place the directory under path "/".  <ins> The object MAY additionally contain a key "meta".  If present, it MUST be a JSON object; each field in the object is an item of </ins> metadata relating to the service provided by the ACME server. The following metadata items are defined, all of which are OPTIONAL: The challenges that the client can fulfill in order to prove possession of the identifier (for pending authorizations).  For final authorizations, the challenges that were used.  Each array  <ins> entry is an object with parameters required to validate the </ins> challenge.  A client should attempt to fulfill at most one of these challenges, and a server should consider any one of the challenges sufficient to make the authorization valid. client needs to respond with information to complete the challenges. To do this, the client updates the authorization object received from the server by filling in any required information in the elements of  <ins> the "challenges" object.  (This is also the stage where the client should perform any actions required by the challenge.) </ins> The client sends these updates back to the server in the form of a JSON object with the response fields required by the challenge type, Template:  <ins> Field name: The string to be used as a key in the JSON object </ins> Field type: The type of value to be provided, e.g., string, boolean, array of string Template:  <ins> Key: The value to be used as a field name in the directory object </ins> Resource type: The type of resource labeled by the key


When a server rejects a request because its nonce value was unacceptable (or not present), it MUST provide HTTP status code 400 <del> (Bad Request), and indicate the ACME error code </del>  "urn:ietf:params:acme:error:badNonce".  An error response with the <del> "badNonce" error code MUST include a Replay-Nonce header with a fresh </del>  nonce.  On receiving such a response, a client SHOULD retry the request using the new nonce. specified, and MUST NOT issue a certificate with contents other than those requested.  If the server requires the request to be modified in a certain way, it should indicate the required changes using an <del> appropriate error code and description. </del>  If the server is willing to issue the requested certificate, it responds with a 201 (Created) response.  The body of this response is ACME Order Object Fields (iana-order) <del> ACME Error Codes (iana-error) </del>  ACME Resource Types (iana-resource) Template: <del> Code: The label to be included in the URN for this error, </del>  following "urn:ietf:params:acme:" Description: A human-readable description of the error Reference: Where the error is defined <del> Initial contents: The codes and descriptions in the table in errors </del>  above, with the Reference field set to point to this specification. 8.6.4.

Usage of is slightly confusing when we are not using int-enumerated error codes. RFC 7807 also refers to the problem document error types as and the field is called so this seems to make the most sense.

When a server rejects a request because its nonce value was unacceptable (or not present), it MUST provide HTTP status code 400  <ins> (Bad Request), and indicate the ACME error type </ins> "urn:ietf:params:acme:error:badNonce".  An error response with the  <ins> "badNonce" error type MUST include a Replay-Nonce header with a fresh </ins> nonce.  On receiving such a response, a client SHOULD retry the request using the new nonce. specified, and MUST NOT issue a certificate with contents other than those requested.  If the server requires the request to be modified in a certain way, it should indicate the required changes using an  <ins> appropriate error type and description. </ins> If the server is willing to issue the requested certificate, it responds with a 201 (Created) response.  The body of this response is ACME Order Object Fields (iana-order)  <ins> ACME Error Types (iana-error) </ins> ACME Resource Types (iana-resource) Template:  <ins> Type: The label to be included in the URN for this error, </ins> following "urn:ietf:params:acme:" Description: A human-readable description of the error Reference: Where the error is defined  <ins> Initial contents: The types and descriptions in the table in errors </ins> above, with the Reference field set to point to this specification. 8.6.4.


6.3. <del> At some points in the protocol, it is necessary for the server to determine whether two JSON Web Key (JWK) RFC7517 objects represent the same key.  In performing these checks, the server MUST consider two JWKs to match if and only if they have the identical values in all fields included in the computation of a JWK thumbprint for that key.  That is, the keys must have the same "kty" value and contain identical values in the fields used in the computation of a JWK thumbprint for that key type: "RSA": "n", "e" "EC": "crv", "x", "y" Note that this comparison is equivalent to computing the JWK thumbprints of the two keys and comparing thumbprints.  The only difference is that there is no requirement for a hash computation (and thus it is independent of the choice of hash function) and no risk of hash collision. 6.4. </del> It is common in deployment for the entity terminating TLS for HTTPS to be different from the entity operating the logical HTTPS server, with a "request routing" layer in the middle.  For example, an ACME having the resource check that requests have the same string in their "url" fields. <del> 6.4.1. </del>  The "url" header parameter specifies the URL RFC3986 to which this JWS object is directed.  The "url" parameter MUST be carried in the protected header of the JWS.  The value of the "url" header MUST be a string representing the URL. <del> 6.5. </del>  In order to protect ACME resources from any possible replay attacks, ACME requests have a mandatory anti-replay mechanism.  This mechanism value for each response, keep a list of issued nonces, and strike nonces from this list as they are used. <del> 6.5.1. </del>  The "Replay-Nonce" header field includes a server-generated value that the server can use to detect unauthorized replay in future The Replay-Nonce header field SHOULD NOT be included in HTTP request messages. <del> 6.5.2. </del>  The "nonce" header parameter provides a unique value that enables the verifier of a JWS to recognize when replay has occurred.  The "nonce" according to this encoding, then the verifier MUST reject the JWS as malformed. <del> 6.6. </del>  Creation of resources can be rate limited to ensure fair usage and prevent abuse.  Once the rate limit is exceeded, the server MUST header pointing to documentation about the specific hit rate limits using the "urn:ietf:params:acme:documentation" relation. <del> 6.7. </del>  Errors can be reported in ACME both at the HTTP layer and within challenge objects as defined in identifier-validation-challenges. the same. Check that the "account" field of the key-change object contains <del> the URL for the account matching the old key. </del>  <del> Check that the "newKey" field of the key-change object contains the key used to sign the inner JWS. </del>  If all of these checks pass, then the server updates the corresponding account by replacing the old account key with the new

Instead of defining a whole new key equivalence method just check the JWK verifies the inner JWS.

6.3.  It is common in deployment for the entity terminating TLS for HTTPS to be different from the entity operating the logical HTTPS server, with a "request routing" layer in the middle.  For example, an ACME having the resource check that requests have the same string in their "url" fields.  <ins> 6.3.1. </ins> The "url" header parameter specifies the URL RFC3986 to which this JWS object is directed.  The "url" parameter MUST be carried in the protected header of the JWS.  The value of the "url" header MUST be a string representing the URL.  <ins> 6.4. </ins> In order to protect ACME resources from any possible replay attacks, ACME requests have a mandatory anti-replay mechanism.  This mechanism value for each response, keep a list of issued nonces, and strike nonces from this list as they are used.  <ins> 6.4.1. </ins> The "Replay-Nonce" header field includes a server-generated value that the server can use to detect unauthorized replay in future The Replay-Nonce header field SHOULD NOT be included in HTTP request messages.  <ins> 6.4.2. </ins> The "nonce" header parameter provides a unique value that enables the verifier of a JWS to recognize when replay has occurred.  The "nonce" according to this encoding, then the verifier MUST reject the JWS as malformed.  <ins> 6.5. </ins> Creation of resources can be rate limited to ensure fair usage and prevent abuse.  Once the rate limit is exceeded, the server MUST header pointing to documentation about the specific hit rate limits using the "urn:ietf:params:acme:documentation" relation.  <ins> 6.6. </ins> Errors can be reported in ACME both at the HTTP layer and within challenge objects as defined in identifier-validation-challenges. the same. Check that the "account" field of the key-change object contains  <ins> the URL for the account matching the old key </ins>  <ins> Check that the "newKey" field of the key-change object also verifies the inner JWS. </ins> If all of these checks pass, then the server updates the corresponding account by replacing the old account key with the new


The requested value of the notAfter field in the certificate, in the date format defined in RFC3339.  For pending orders, the authorizations that the client needs to complete before the requested certificate can be issued (see identifier-authorization).  For final orders, the authorizations

Removes dnssec error type for a broader "dns" error type. It's very hard to split out dnssec errors from regular dns problems, because recursive resolvers can only return SERVFAIL. The new dns error type also subsumes "unknownHost." Introduces a new "incorrectResponse" error type for cases where connection and request were both successful, but the content didn't match. This also puts the validation-related errors at the bottom of the table so they can be viewed in context with each other. Introduces an error field for orders. Orders can fail independent of authorizations because of last-minute CAA checking, failure to submit to CT logs, timeouts, etc.

The requested value of the notAfter field in the certificate, in the date format defined in RFC3339. <ins> The error that occurred while processing the order, if any.  This field is structured as a problem document RFC7807. </ins> For pending orders, the authorizations that the client needs to complete before the requested certificate can be issued (see identifier-authorization).  For final orders, the authorizations


An ACME account resource represents a set of metadata associated with an account.  Account resources have the following structure: <del> The public key of the account's key pair, encoded as a JSON Web Key object RFC7517.  The client may not directly update this field, but must use the key-change resource instead. </del> The status of this account.  Possible values are: "valid", "deactivated", and "revoked".  The value "deactivated" should be used to indicate user initiated deactivation whereas "revoked" a stub account object containing the "contact" field and optionally the "terms-of-service-agreed" field. <del> The server MUST ignore any values provided in the "key", and "orders" fields in account bodies sent by the client, as well as any other fields that it does not recognize.  If new fields are specified in the future, the specification of those fields MUST describe whether they can be provided by the client. </del>  In general, the server MUST ignore any fields in the request object that it does not recognize.  In particular, it MUST NOT reflect description describing the error and what types of contact URL the server considers acceptable. <del> The server creates an account and populates the account object with the "key" field containing the JWK public key used to verify the JWS. The server returns this account object in a response with a 201 (Created) status code, with the account URI in a Location header field. </del>  If the server already has an account registered with the provided account key, then it MUST return a response with a 200 (OK) status If the client wishes to update this information in the future, it sends a POST request with updated information to the account URI. <del> The server MUST ignore any updates to the "key", or "order" fields or any other fields it does not recognize.  The server MUST verify that the request is signed with the private key corresponding to the "key" field of the request before updating the account object. </del>  For example, to update the contact information in the above account, the client could send the following request:

The client knows what its public key is, because it has to have access to the private key in order to sign new-account requests or updates to the account resource. So this field serves no purpose.
Has this been discussed on list? I'm concerned that we're removing information that could be valuable for debugging client issues. There's no harm in keeping this; the server has to store this information anyway.
Yep, this was discussed on-list. I can say that as a client developer, I've never found this field useful. Clients need to be able to successfully serialize a jwk in order to speak the protocol. Also, I have no objection to servers including this as an extra field, but it seems wrong to normatively require it when it serves no purpose.
For the record where it was available for discussion. For me, the observation that you need the private key to get an account object is dispositive. There's not even debugging utility here. So I'm OK to merge. Right now, account objects echo back the public key associated with the account, in the "key" field. However, this is redundant since the only request types that can return an account object are signed by the corresponding private key, so the client necessarily knows what its public key is. Removing this simplifies the spec somewhat. URL Thoughts?

An ACME account resource represents a set of metadata associated with an account.  Account resources have the following structure:  The status of this account.  Possible values are: "valid", "deactivated", and "revoked".  The value "deactivated" should be used to indicate user initiated deactivation whereas "revoked" a stub account object containing the "contact" field and optionally the "terms-of-service-agreed" field.  <ins> The server MUST ignore any values provided in the "orders" fields in account bodies sent by the client, as well as any other fields that it does not recognize.  If new fields are specified in the future, the specification of those fields MUST describe whether they can be provided by the client. </ins> In general, the server MUST ignore any fields in the request object that it does not recognize.  In particular, it MUST NOT reflect description describing the error and what types of contact URL the server considers acceptable.  <ins> The server creates an account and stores the public key used to verify the JWS (i.e., the "jwk" element of the JWS header) to authenticate future requests from the account.  The server returns this account object in a 201 (Created) response, with the account URI in a Location header field. </ins> If the server already has an account registered with the provided account key, then it MUST return a response with a 200 (OK) status If the client wishes to update this information in the future, it sends a POST request with updated information to the account URI.  <ins> The server MUST ignore any updates to "order" fields or any other fields it does not recognize. </ins> For example, to update the contact information in the above account, the client could send the following request:


The guiding use case for ACME is obtaining certificates for Web sites (HTTPS RFC2818).  In this case, the user's web server is intended to speak for one or more domains, and the process of certificate <del> issuance is intended to verify that this server actually speaks for the domain(s). </del>  DV certificate validation commonly checks claims about properties related to control of a domain name - properties that can be observed The ACME client periodically contacts the CA to get updated certificates, stapled OCSP responses, or whatever else would be <del> required to keep the server functional and its credentials up-to- date. </del>  In this way, it would be nearly as easy to deploy with a CA-issued certificate as with a self-signed certificate.  Furthermore, the an identifier proactively, outside of the context of a specific issuance.  For example, a client hosting virtual servers for a collection of names might wish to obtain authorization before any <del> servers are created, and only create a certificate when a server starts up. </del>  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 Verify that the resulting URI is well-formed. Dereference the URI using an HTTP GET request.  This request MUST <del> be sent to TCP port 80 on the server. </del>  Verify that the body of the response is well-formed key authorization.  The server SHOULD ignore whitespace characters at the end of the body. <del> Verify that key authorization provided by the server matches the token for this challenge and the client's account key. </del>  If all of the above verifications succeed, then the validation is successful.  If the request fails, or the body does not pass these records under the domain name to respond to specific connection attempts utilizing the Server Name Indication extension RFC6066.  The server verifies the client's challenge by accessing the reconfigured <del> server and verifying a particular challenge certificate is presented. </del>  The string "tls-sni-02" Open a TLS connection to the domain name being validated, presenting SAN A in the SNI field.  This connection MUST be sent <del> to TCP port 443 on the server.  In the ClientHello initiating the TLS handshake, the server MUST include a server_name extension </del>  (i.e., SNI) containing SAN A.  The server SHOULD ensure that it does not reveal SAN B in any way when making the TLS connection, such that the presentation of SAN B in the returned certificate There are several ways that these assumptions can be violated, both by misconfiguration and by attack.  For example, on a web server that allows non-administrative users to write to .well-known, any user can <del> claim to own the server's hostname by responding to an HTTP </del>  challenge, and likewise for TLS configuration and TLS SNI. The use of hosting providers is a particular risk for ACME challenges.  An entity that can provision false DNS records for a domain can attack the DNS challenge directly, and can provision false A/AAAA records to direct the ACME server to send its TLS SNI or HTTP <del> validation query to a server of the attacker's choosing.  There are a few different mitigations that ACME servers can apply: </del>  Always querying the DNS using a DNSSEC-validating resolver (enhancing security for zones that are DNSSEC-enabled) process, by performing normal ACME transactions and providing a validation response for his own account key.  The risks due to hosting providers noted above are a particular case.  For identifiers <del> where the server already has some public key associated with the </del>  domain this attack can be prevented by requiring the client to prove control of the corresponding private key.

As pointed out by NAME on the ACME mailing list there are a few places where there was some potential ambiguity about what "server" meant. This PR is the result of a once-through pass looking for places where we could be more specific when saying "server". In most cases the default definition of "server" from the Terminology section applied and no change was made. I attempted to clarify any usage of "server" that wasn't qualified sufficiently to differentiate from the ACME server.

The guiding use case for ACME is obtaining certificates for Web sites (HTTPS RFC2818).  In this case, the user's web server is intended to speak for one or more domains, and the process of certificate  <ins> issuance is intended to verify that this web server actually speaks for the domain(s). </ins> DV certificate validation commonly checks claims about properties related to control of a domain name - properties that can be observed The ACME client periodically contacts the CA to get updated certificates, stapled OCSP responses, or whatever else would be  <ins> required to keep the web server functional and its credentials up- to-date. </ins> In this way, it would be nearly as easy to deploy with a CA-issued certificate as with a self-signed certificate.  Furthermore, the an identifier proactively, outside of the context of a specific issuance.  For example, a client hosting virtual servers for a collection of names might wish to obtain authorization before any  <ins> virtual servers are created, and only create a certificate when a virtual server starts up. </ins> 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 Verify that the resulting URI is well-formed. Dereference the URI using an HTTP GET request.  This request MUST  <ins> be sent to TCP port 80 on the HTTP server. </ins> Verify that the body of the response is well-formed key authorization.  The server SHOULD ignore whitespace characters at the end of the body.  <ins> Verify that key authorization provided by the HTTP server matches the token for this challenge and the client's account key. </ins> If all of the above verifications succeed, then the validation is successful.  If the request fails, or the body does not pass these records under the domain name to respond to specific connection attempts utilizing the Server Name Indication extension RFC6066.  The server verifies the client's challenge by accessing the reconfigured  <ins> TLS server and verifying a particular challenge certificate is presented. </ins> The string "tls-sni-02" Open a TLS connection to the domain name being validated, presenting SAN A in the SNI field.  This connection MUST be sent  <ins> to TCP port 443 on the TLS server.  In the ClientHello initiating the TLS handshake, the server MUST include a server_name extension </ins> (i.e., SNI) containing SAN A.  The server SHOULD ensure that it does not reveal SAN B in any way when making the TLS connection, such that the presentation of SAN B in the returned certificate There are several ways that these assumptions can be violated, both by misconfiguration and by attack.  For example, on a web server that allows non-administrative users to write to .well-known, any user can  <ins> claim to own the web server's hostname by responding to an HTTP </ins> challenge, and likewise for TLS configuration and TLS SNI. The use of hosting providers is a particular risk for ACME challenges.  An entity that can provision false DNS records for a domain can attack the DNS challenge directly, and can provision false A/AAAA records to direct the ACME server to send its TLS SNI or HTTP  <ins> validation query to a remote server of the attacker's choosing. There are a few different mitigations that ACME servers can apply: </ins> Always querying the DNS using a DNSSEC-validating resolver (enhancing security for zones that are DNSSEC-enabled) process, by performing normal ACME transactions and providing a validation response for his own account key.  The risks due to hosting providers noted above are a particular case.  For identifiers  <ins> where a web server already has some public key associated with the </ins> domain this attack can be prevented by requiring the client to prove control of the corresponding private key.


new challenge types, and they will need to specify which types of identifier they apply to. <del> [[ Editor's Note: In pre-RFC versions of this specification, challenges are labeled by type, and with the version of the draft in which they were introduced.  For example, if an HTTP challenge were introduced in version -03 and a breaking change made in version -05, then there would be a challenge labeled "http-03" and one labeled "http-05" - but not one labeled "http-04", since challenge in version -04 was compatible with one in version -03. ]] </del> 8.1. Several of the challenges in this document make use of a key

This is worth discussion on the list. Do we consider the current, numbered, names a draft-only thing? Do we want the final RFC to use non-numbered challenge names?
If we are going to do this, we need to update the following paragraph: Personally, I would prefer dropping the version number (i.e., not merging this PR), since if all goes well, future client development can be based on the RFC vs. the drafts. Clients will need to change which token they use, but that's hardly the biggest change between what's deployed today and what's in this spec.
Will update to remove the editor's note.
Could possibly use some additional language about the name + version scheme we are using but I couldn't come up with anything that really worked.

new challenge types, and they will need to specify which types of identifier they apply to.  8.1. Several of the challenges in this document make use of a key


The identifier itself. <del> How an existing authorization should be handled.  Possible values are "accept" and "require". </del> Before processing the authorization request, the server SHOULD determine whether it is willing to issue certificates for the identifier.  For example, the server should check that the identifier (Forbidden) error, with a problem document describing the reason for the rejection. <del> If the authorization request specifies "existing" with a value of "accept" or "require", before proceeding, the server SHOULD determine whether there are any existing, valid authorization resources for the account and given identifier.  If one or more such authorizations exists, a response SHOULD be returned with status code 303 (See Other) and a Location header pointing to the existing resource URL; processing of the request then stops.  If there are multiple such authorizations, the authorization with the latest expiry date SHOULD be returned.  If no existing authorizations were found and the value for "existing" was "require", then the server MUST return status code 404 (Not Found); if it was "accept" or was any other value or was absent, processing continues as follows. </del> If the server is willing to proceed, it builds a pending authorization object from the inputs submitted by the client.

I believe they are unnecessary. The server can set its own policy on whether to give back an existing or a new authz, and the client can choose to accept or reject that. Hugo also pointed out on-list that the status codes for these are inconsistent with the status codes for new-account. If we keep these, we'd want to fix that. But simpler to delete, I think.
Let's Encrypt tell me that they have had a few reports of buggy clients creating enough pending authorizations to saturate their rate limits, so they need a way for clients to clear these out. These clients are also not keeping around authorization URLs, so they can't just go them. My proposed solution would be to re-add the "authorizations" field to the account object, which got lost in the refactor in or so. Together with deactivation, enabling clients to enumerate authorization URLs would solve this problem. You could also envision a more direct solution, offering an endpoint that just deletes all pending authorizations for a client or client+identifier.
This is definitely too specific to these buggy clients. For the flow, the list of orders is sufficient. It's true that technically you can create authorizations through a separate, optional, flow. But Let's Encrypt has no plans to implement that flow, because other CAs have said they cannot / would not implement it, so Let's Encrypt implementing it would split the market. I'm inclined to say let's not complicate the protocol, and hypothetical clients that want to do the flow with some hypothetical server need to keep proper track of their authzs. Also, I think the particular issue with hitting limits for pending authzs can be solved in several ways without modifying the protocol.
If is merged, I would expect that a reasonable ACME server supporting new-authz would return an exiting authz, instead of giving a rate limit error. Or return existing authz from the beginning.
Closing as a result of WG decision at IETF 98

The identifier itself.  Before processing the authorization request, the server SHOULD determine whether it is willing to issue certificates for the identifier.  For example, the server should check that the identifier (Forbidden) error, with a problem document describing the reason for the rejection.  If the server is willing to proceed, it builds a pending authorization object from the inputs submitted by the client.


other certificate management functions, such as certificate revocation. <del> DANGER: Do not implement this specification.  It has a known signature reuse vulnerability.  For details, see the following discussion: </del>  <del> https://mailarchive.ietf.org/arch/msg/acme/F71iz6qq1o_QPVhJCV4dqWf- 4Yc </del>  1. CAs that use ACME to automate issuance will need to ensure that their servers perform all necessary checks before issuing.

It's no longer at a "do not implement" stage, but some caution is still merited. Also, it's good to have a pointer in the draft to this repo. (Cribbed from the TLS 1.3 spec.)

other certificate management functions, such as certificate revocation.  <ins> DISCLAIMER: This is a WIP draft of ACME and has not yet had a thorough security analysis. </ins>  <ins> RFC EDITOR: PLEASE REMOVE THE FOLLOWING PARAGRAPH: The source for this draft is maintained in GitHub.  Suggested changes should be submitted as pull requests at https://github.com/ietf-wg-acme/acme [1].  Instructions are on that page as well.  Editorial changes can be managed in GitHub, but any substantive change should be discussed on the ACME mailing list (acme@ietf.org). </ins> 1. CAs that use ACME to automate issuance will need to ensure that their servers perform all necessary checks before issuing. <ins> 10.  References 10.1.  URIs [1] https://github.com/ietf-wg-acme/acme </ins>


A "new-order" resource (applying-for-certificate-issuance) <del> A "revoke-certificate" resource (certificate-revocation) </del>  A "key-change" resource (account-key-roll-over)

Fixes per feedback . Section 6.1 referenced "revoke-certificate" where elsewhere using "revoke-cert", this commit replaces it with "revoke-cert". Section 7.1 has a resource diagram that previously labelled the termination of the "new-account" flow as "acct", this commit replaces that label with "account". Elsewhere the use of "acct" is limited to URLs and not referencing specific resources/spec content. I'm resending this message as there were no responses and nothing changed. ---------- Forwarded message ---------- Morning, the current draft contains a few inconsistencies in the resource naming. 1) https://ietf-wg-URL mentions "revoke-certificate", while it's called "revoke-cert" in the rest of the document. 2) There's "new-account", but the account resource is called "acct", I think it should be "account" everywhere. We don't gain anything by saving a few keystrokes / bytes there. Maybe we should then also rename "authz" to "authorization" and "cert" to "certificate" everywhere. Regards, Niklas

A "new-order" resource (applying-for-certificate-issuance)  <ins> A "revoke-cert" resource (certificate-revocation) </ins> A "key-change" resource (account-key-roll-over)


The string "http-01" A random value that uniquely identifies the challenge.  This value <del> MUST have at least 128 bits of entropy, in order to prevent an attacker from guessing it.  It MUST NOT contain any characters outside the base64url alphabet, including padding characters ("="). </del>  A client responds to this challenge by constructing a key authorization from the "token" value provided in the challenge and The string "tls-sni-02" A random value that uniquely identifies the challenge.  This value <del> MUST have at least 128 bits of entropy, in order to prevent an attacker from guessing it.  It MUST NOT contain any characters outside the base64url alphabet, including padding characters ("="). </del>  A client responds to this challenge by constructing a self-signed certificate which the client MUST provision at the domain name The string "dns-01" A random value that uniquely identifies the challenge.  This value <del> MUST have at least 128 bits of entropy, in order to prevent an attacker from guessing it.  It MUST NOT contain any characters outside the base64url alphabet, including padding characters ("="). </del>  A client responds to this challenge by constructing a key authorization from the "token" value provided in the challenge and unrecognized_name alert, then this is an indication that the server is not in a default virtual host configuration.  12.  References 12.1.  URIs

Per feedback from Zach Shepherd[0] on the mailing list the justification for the 128 bits of required token entropy from section 8.2 is at odds with the actual rationale (as I understand it). This commit updates the justification for the entropy requirement to not mention being secret from an attacker, but instead not predictable by a naive challenge response server that would complete challenges without having been a party to the authz/chal creation.
It seems like whatever change is made should be applied to sections 8.2, 8.3, and 8.4.
Based on zjs' feedback, I think it makes more sense for the individual token fields to just say "MUST have 128 bits", and explain why in one place in the Security Considerations section.
NAME NAME Updated. Thanks for the feedback!

The string "http-01" A random value that uniquely identifies the challenge.  This value  <ins> MUST have at least 128 bits of entropy.  It MUST NOT contain any characters outside the base64url alphabet, including padding characters ("="). </ins> A client responds to this challenge by constructing a key authorization from the "token" value provided in the challenge and The string "tls-sni-02" A random value that uniquely identifies the challenge.  This value  <ins> MUST have at least 128 bits of entropy.  It MUST NOT contain any characters outside the base64url alphabet, including padding characters ("="). </ins> A client responds to this challenge by constructing a self-signed certificate which the client MUST provision at the domain name The string "dns-01" A random value that uniquely identifies the challenge.  This value  <ins> MUST have at least 128 bits of entropy.  It MUST NOT contain any characters outside the base64url alphabet, including padding characters ("="). </ins> A client responds to this challenge by constructing a key authorization from the "token" value provided in the challenge and unrecognized_name alert, then this is an indication that the server is not in a default virtual host configuration. <ins> 11.3. The http-01, tls-sni-02 and dns-01 validation methods mandate the usage of a random token value to uniquely identify the challenge. The value of the token is required to contain at least 128 bits of entropy for the following security properties.  First, the ACME client should not be able to influence the ACME server's choice of token as this may allow an attacker to reuse a domain owner's previous challenge responses for a new validation request.  Secondly, the entropy requirement prevents ACME clients from implementing a "naive" validation server that automatically replies to challenges without participating in the creation of the intial authorization request. </ins> 12.  References 12.1.  URIs


against an intermediary changing the request URL to another ACME URL. As noted in request-authentication above, all ACME request objects <del> carry a "url" parameter in their protected header.  This header parameter encodes the URL to which the client is directing the </del>  request.  On receiving such an object in an HTTP request, the server <del> MUST compare the "url" parameter to the request URL.  If the two do not match, then the server MUST reject the request as unauthorized. </del>  Except for the directory resource, all ACME resources are addressed with URLs provided to the client by the server.  For these resources, <del> the client MUST set the "url" field 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" fields. </del>  6.3.1. The "url" header parameter specifies the URL RFC3986 to which this <del> JWS object is directed.  The "url" parameter MUST be carried in the protected header of the JWS.  The value of the "url" header MUST be a string representing the URL. </del>  6.4. The status of this account.  Possible values are: "valid", "deactivated", and "revoked".  The value "deactivated" should be <del> used to indicate user initiated deactivation whereas "revoked" should be used to indicate administratively initiated deactivation. </del>  An array of URIs that the server can use to contact the client for issues related to this account.  For example, the server may wish authorization valid for all orders until the authorization expires. <del> The challenges that the client can fulfill in order to prove possession of the identifier (for pending authorizations).  For final authorizations, the challenges that were used.  Each array entry is an object with parameters required to validate the challenge.  A client should attempt to fulfill one of these challenges, and a server should consider any one of the challenges sufficient to make the authorization valid.  For final authorizations it contains the challenges that were completed. </del>  The only type of identifier defined by this specification is a fully- qualified domain name (type: "dns").  If a domain name contains non- request-authentication).  The inner JWS MUST meet the normal requirements, with the following exceptions: <del> The inner JWS MUST have the same "url" parameter as the outer JWS. </del>  <del> The inner JWS is NOT REQUIRED to have a "nonce" parameter.  The server MUST ignore any value provided for the "nonce" header </del>  parameter. This transaction has signatures from both the old and new keys so

This pull request includes changes to: Consistently use "header parameter" when referring to JWS header parameters. Insert a missing right curly bracket in a section reference. Use "server-initiated" instead of "administratively initiated" for clarity. Use parallel sentence structure for clarity/readability.

against an intermediary changing the request URL to another ACME URL. As noted in request-authentication above, all ACME request objects  <ins> carry a "url" header parameter in their protected header.  This header parameter encodes the URL to which the client is directing the </ins> request.  On receiving such an object in an HTTP request, the server  <ins> MUST compare the "url" header parameter to the request URL.  If the two do not match, then the server MUST reject the request as unauthorized. </ins> Except for the directory resource, all ACME resources are addressed with URLs provided to the client by the server.  For these resources,  <ins> 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. </ins> 6.3.1. The "url" header parameter specifies the URL RFC3986 to which this  <ins> JWS object is directed.  The "url" header parameter MUST be carried in the protected header of the JWS.  The value of the "url" header parameter MUST be a string representing the URL. </ins> 6.4. The status of this account.  Possible values are: "valid", "deactivated", and "revoked".  The value "deactivated" should be  <ins> used to indicate client-initiated deactivation whereas "revoked" should be used to indicate server-initiated deactivation. </ins> An array of URIs that the server can use to contact the client for issues related to this account.  For example, the server may wish authorization valid for all orders until the authorization expires.  <ins> For pending authorizations, the challenges that the client can fulfill in order to prove possession of the identifier.  For final authorizations, the challenges that were used.  Each array entry is an object with parameters required to validate the challenge. A client should attempt to fulfill one of these challenges, and a server should consider any one of the challenges sufficient to make the authorization valid.  For final authorizations it contains the challenges that were completed. </ins> The only type of identifier defined by this specification is a fully- qualified domain name (type: "dns").  If a domain name contains non- request-authentication).  The inner JWS MUST meet the normal requirements, with the following exceptions:  <ins> The inner JWS MUST have the same "url" header parameter as the outer JWS. </ins>  <ins> The inner JWS is NOT REQUIRED to have a "nonce" header parameter. The server MUST ignore any value provided for the "nonce" header </ins> parameter. This transaction has signatures from both the old and new keys so


The "Replay-Nonce" header field includes a server-generated value that the server can use to detect unauthorized replay in future <del> client requests.  The server should generate the value provided in </del>  Replay-Nonce in such a way that they are unique to each message, with <del> high probability. </del>  The value of the Replay-Nonce field MUST be an octet string encoded according to the base64url encoding described in Section 2 of

And clarify "high probability."
While we're clarifying, I might add an encrypted counter another option that is guaranteed unique.
I don't think we need to get into that level of prescribing implementation detail; once you mention it at all it immediately sounds half-specified. As a reader, I would want to know "what algorithm? shared across how many frontends? how does key management and rotation work?" Better to just say it should be unique (with high probability) and leave it to the implementer.

The "Replay-Nonce" header field includes a server-generated value that the server can use to detect unauthorized replay in future  <ins> client requests.  The server MUST generate the value provided in </ins> Replay-Nonce in such a way that they are unique to each message, with  <ins> high probability.  For instance, it is acceptable to generate Replay- Nonces randomly. </ins> The value of the Replay-Nonce field MUST be an octet string encoded according to the base64url encoding described in Section 2 of


unrecognized fields in the resulting account object.  This allows clients to detect when servers do not support an extension field. <del> The server SHOULD validate that the contact URLs in the "contact" field are valid and supported by the server.  If the client provides the server with an invalid or unsupported contact URL, then the server MUST return an error of type "invalidContact", with a description describing the error and what types of contact URL the server considers acceptable. </del>  The server creates an account and stores the public key used to verify the JWS (i.e., the "jwk" element of the JWS header) to

Firstly, this PR updates the table of errors in Section 6.6 "Errors" to add an "unsupportedContact" error type in addition to "invalidContact". The former is returned when the contact URI protocol is unsupported and the latter when the protocol is supported but the provided contact is invalid. Secondly, this PR updates Section 7.3 "Account Creation" to both mention the new "unsupportedContact" error type and to make support of the "mailto:" protocol a MUST.
Thanks for the feedback NAME - updated.
Should the "unsupportedContact" error include a separate machine-readable field with the types of contacts acceptable?
NAME Let's discuss that in a follow-on issue / PR.

unrecognized fields in the resulting account object.  This allows clients to detect when servers do not support an extension field.  <ins> The server SHOULD validate that the contact URIs in the "contact" field are valid and supported by the server.  If the server validates contact URIs it MUST support the "mailto" scheme.  If the server rejects a contact URI for using an unsupported scheme it MUST return an error of type "unsupportedContact", with a description describing the error and what types of contact URIs the server considers acceptable.  If the server rejects a contact URI for using a supported scheme but an invalid value then the server MUST return an error of type "invalidContact". </ins> The server creates an account and stores the public key used to verify the JWS (i.e., the "jwk" element of the JWS header) to


Same meaning as the corresponding server field defined in  The server MUST ignore any values provided in the "orders" fields in account bodies sent by the client, as well as any other fields that it does not recognize.  If new fields are specified in the future, field.  This allows a client that has an account key but not the corresponding account URL to recover the account URL. <del> If a client wishes to recover an existing account and does not want a non existing account to be created, then it SHOULD do so by sending a POST request with an empty update.  That is, it should send a JWS whose payload is an empty object ({}). </del>  7.3.2.

Depends on
This allows us to address the account URL recovery use case in without having special handling for empty payloads.

Same meaning as the corresponding server field defined in <ins> If this field is present with the value "true", then the server MUST NOT create a new account if one does not already exist.  This allows a client to look up an account URL based on an account key (see finding-an-account-url-given-a-key). </ins> The server MUST ignore any values provided in the "orders" fields in account bodies sent by the client, as well as any other fields that it does not recognize.  If new fields are specified in the future, field.  This allows a client that has an account key but not the corresponding account URL to recover the account URL.  <ins> If a client wishes to find the URL for an existing account and does not want an account to be created if one does not already exist, then it SHOULD do so by sending a POST request to the new-account URL with a JWS whose payload has an "only-return-existing" field set to "true" ({"only-return-existing": true}). </ins> 7.3.2.


encoded in the format specified in RFC 3339 RFC3339.  This field is REQUIRED if the "status" field is "valid". <del> The error that occurred while the server was validating the challenge, if any.  This field is structured as a problem document RFC7807. </del>  All additional fields are specified by the challenge type.  If the server sets a challenge's "status" to "invalid", it SHOULD also 8.2.  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.  The ACME successful.  If the request fails, or the body does not pass these checks, then it has failed. <del> 8.3. </del>  The TLS with Server Name Indication (TLS SNI) validation method proves control over a domain name by requiring the client to If all of the above verifications succeed, then the validation is successful.  Otherwise, the validation fails. <del> 8.4. </del>  When the identifier being validated is a domain name, the client can prove control of that domain by provisioning a TXT resource record successful.  If no DNS record is found, or DNS record and response payload do not pass these checks, then the validation fails. <del> 8.5. </del>  There may be cases where a server cannot perform automated validation of an identifier, for example, if validation requires some manual

A refinement on Servers reflect their state in and Clients can request a retry by re-ing

encoded in the format specified in RFC 3339 RFC3339.  This field is REQUIRED if the "status" field is "valid".  <ins> Errors that occurred while the server was validating the challenge, if any, structured as problem documents RFC7807.  The server MUST NOT modify the array except by appending entries onto the end.  The server can limit the size of this object by limiting the number of times it will retry a challenge. </ins> All additional fields are specified by the challenge type.  If the server sets a challenge's "status" to "invalid", it SHOULD also 8.2. <ins> ACME challenges typically require the client to set up some network- accessible resource that the server can query in order to validate that the client controls an identifier.  In practice it is not uncommon for the server's queries to fail while a resource is being set up, e.g., due to information propagating across a cluster or firewall rules not being in place. Clients SHOULD NOT respond to challenges until they believe that the server's queries will succeed.  If a server's initial validation query fails, the server SHOULD retry the query after some time. While the server is still trying, the status of the challenge remains "pending"; it is only marked "invalid" once the server has given up. The server MUST provide information about its retry state to the client via the "errors" field in the challenge and the Retry-After HTTP header field in response to requests to the challenge resource. The server MUST add an entry to the "errors" field in the challenge after each failed validation query.  The server SHOULD set the Retry- After header field to a time after the server's next validation query, since the status of the challenge will not change until that time. Clients can explicitly request a retry by re-sending their response to a challenge in a new POST request (with a new nonce, etc.).  This allows clients to request a retry when state has changed (e.g., after firewall rules have been updated).  Servers SHOULD retry a request immediately on receiving such a POST request.  In order to avoid denial-of-service attacks via client-initiated retries, servers SHOULD rate-limit such requests. 8.3. </ins> 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.  The ACME successful.  If the request fails, or the body does not pass these checks, then it has failed.  <ins> 8.4. </ins> The TLS with Server Name Indication (TLS SNI) validation method proves control over a domain name by requiring the client to If all of the above verifications succeed, then the validation is successful.  Otherwise, the validation fails.  <ins> 8.5. </ins> When the identifier being validated is a domain name, the client can prove control of that domain by provisioning a TXT resource record successful.  If no DNS record is found, or DNS record and response payload do not pass these checks, then the validation fails.  <ins> 8.6. </ins> There may be cases where a server cannot perform automated validation of an identifier, for example, if validation requires some manual


9.7.5. <del> This registry lists the types of identifiers in certificates that ACME clients may request authorization to issue. </del>  Template:

Currently says This registry lists the types of identifiers that ACME clients may request authorization to issue in certificates. But ACME clients no longer directly request authorization; instead this section lists identifiers that the servers may create authorizations for based on new-order.

9.7.5.  <ins> This registry lists the types of identifiers that can be present in ACME authorization objects. </ins> Template:


In order to help clients configure themselves with the right URLs for each ACME operation, ACME servers provide a directory object.  This should be the only URL needed to configure clients.  It is a JSON <del> object, whose keys are drawn from the following table and whose values are the corresponding URLs. </del>  There is no constraint on the actual URL of the directory except that it should be different from the other ACME server resources' URLs, a host which only functions as an ACME server could place the directory under the path "/". <del> The object MAY additionally contain a key "meta".  If present, it </del>  MUST be a JSON object; each field in the object is an item of metadata relating to the service provided by the ACME server. reflect them as already valid in any orders submitted by the client. If a CA wishes to allow pre-authorization within ACME, it can offer a <del> "new authorization" resource in its directory by adding the key "new- authz" with a URL for the new authorization resource. </del>  To request authorization for an identifier, the client sends a POST request to the new-authorization resource specifying the identifier Template: <del> Field name: The string to be used as a key in the JSON object </del>  Field type: The type of value to be provided, e.g., string, boolean, array of string Template: <del> Key: The value to be used as a field name in the directory object </del>  <del> Resource type: The type of resource labeled by the key </del>  Reference: Where the resource type is defined

In the JSON , could be called a "field name" or a "key." We use both in this document, but we should consolidate one one. I think "field name" is better (and NAME agrees). In part this avoids any ambiguity with cryptographic keys.

In order to help clients configure themselves with the right URLs for each ACME operation, ACME servers provide a directory object.  This should be the only URL needed to configure clients.  It is a JSON  <ins> object, whose fields names are drawn from the following table and whose values are the corresponding URLs. </ins> There is no constraint on the actual URL of the directory except that it should be different from the other ACME server resources' URLs, a host which only functions as an ACME server could place the directory under the path "/".  <ins> The object MAY additionally contain a field "meta".  If present, it </ins> MUST be a JSON object; each field in the object is an item of metadata relating to the service provided by the ACME server. reflect them as already valid in any orders submitted by the client. If a CA wishes to allow pre-authorization within ACME, it can offer a  <ins> "new authorization" resource in its directory by adding the field "new-authz" with a URL for the new authorization resource. </ins> To request authorization for an identifier, the client sends a POST request to the new-authorization resource specifying the identifier Template:  <ins> Field name: The string to be used as a field name in the JSON object </ins> Field type: The type of value to be provided, e.g., string, boolean, array of string Template:  <ins> Field name: The value to be used as a field name in the directory object </ins>  <ins> Resource type: The type of resource labeled by the field </ins> Reference: Where the resource type is defined


All of the challenges above have a binding between the account private key and the validation query made by the server, via the key <del> authorization.  The key authorization is signed by the account private key, reflects the corresponding public key, and is provided to the server in the validation response. </del>  The association of challenges to identifiers is typically done by requiring the client to perform some action that only someone who

As pointed out to the list: There is this sentence in the security considerations (10.2 Integrity of Authorizations) that strikes me as extremely misleading: "All of the challenges above have a binding between the account private key and the validation query made by the server, via the key authorization. The key authorization is signed by the account private key, reflects the corresponding public key, and is provided to the server in the validation response." The key authorization itself does NOT contain the signature of the account's key. It gets though signed by the account's key later on in the challenge response (not the validation response) over the ACME channel (not the validation channel). What about saying that in the chronological order of events?

All of the challenges above have a binding between the account private key and the validation query made by the server, via the key  <ins> authorization.  The key authorization reflects the account public key, is provided to the server in the validation response over the validation channel and signed afterwards by the corresponding private key in the challenge response over the ACME channel. </ins> The association of challenges to identifiers is typically done by requiring the client to perform some action that only someone who


ACME Identifier Types (iana-identifier) <del> ACME Challenge Types (iana-challenge) </del>  All of these registries are under a heading of "Automated Certificate Management Environment (ACME) Protocol" and are administered under a 9.7.6. <del> This registry lists the ways that ACME servers can offer to validate control of an identifier.  The "Identifier Type" field in the template must be contained in the Label column of the ACME Identifier Types registry. </del>  Template: <del> Label: The value to be put in the "type" field of challenge objects using this validation mechanism </del>  <del> Identifier Type: The type of identifier that this mechanism applies to </del>  <del> Reference: Where the challenge type is defined </del>  Initial Contents  [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned to this document ]]

It is useful in some contexts (e.g., ) to have identifiers for non-ACME methods that CAs use to validate control of an identifier. This PR updates the ACME Challenge Types registry to instead address Validation Methods more generally, with a column that indicates whether the method is an ACME method.
Okay, I see your point. Fine.

ACME Identifier Types (iana-identifier)  <ins> ACME Validation Methods (iana-validation) </ins> All of these registries are under a heading of "Automated Certificate Management Environment (ACME) Protocol" and are administered under a 9.7.6.  <ins> This registry lists identifiers for the ways that CAs can validate control of identifiers.  Each method's entry must specify whether it corresponds to an ACME challenge type.  The "Identifier Type" field must be contained in the Label column of the ACME Identifier Types registry. </ins> Template:  <ins> Label: The identifier for this validation method </ins>  <ins> Identifier Type: The type of identifier that this method applies to </ins>  <ins> ACME: "Y" if the validation method corresponds to an ACME challenge type; "N" otherwise. Reference: Where the validation method is defined </ins> Initial Contents <ins> When evaluating a request for an assignment in this registry, the designated expert should ensure that the method being registered has a clear, interoperable definition and does not overlap with existing validation methods.  That is, it should not be possible for a client and server to follow take the same set of actions to fulfill two different validation mechanisms. Validation methods do not have to be compatible with ACME in order to be registered.  For example, a CA might wish to register a validation method in order to support its use with the ACME extensions to CAA I- D.ietf-acme-caa. </ins> [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned to this document ]]


public key and returns status code 200 (OK).  Otherwise, the server responds with an error status code and a problem document describing the error.  If there is an existing account with the new key <del> provided, then the server SHOULD use status code 409 (Conflict). </del>  Note that changing the account key for an account SHOULD NOT have any other impact on the account.  For example, the server MUST NOT

Similar to Section 7.3.1 "Finding an Account URL Given a Key" when a key rollover request will result in a conflict with an existing account the header of the response should indicate the URL of the conflicting account. This saves the client from having to post the new-account endpoint to learn the account URL.

public key and returns status code 200 (OK).  Otherwise, the server responds with an error status code and a problem document describing the error.  If there is an existing account with the new key  <ins> provided, then the server SHOULD use status code 409 (Conflict) and provide the URL of that account in the Location header field. </ins> Note that changing the account key for an account SHOULD NOT have any other impact on the account.  For example, the server MUST NOT


replace draft-ietf-acme-acme above with the RFC number assigned to this ]] <del> Applications which use this media type: Any MIME-complaint transport </del>  Additional information:

Thanks to NAME for the report. Resolves URL
s/MIME-complaint/MIME-compliant/
NAME thanks - URL

replace draft-ietf-acme-acme above with the RFC number assigned to this ]]  <ins> Applications which use this media type: Any MIME-compliant transport </ins> Additional information:


deployment of HTTPS and the practicality of PKIX authentication for other protocols based on Transport Layer Security (TLS) RFC5246.  2. The guiding use case for ACME is obtaining certificates for websites certificate as with a self-signed certificate.  Furthermore, the maintenance of that CA-issued certificate would require minimal manual intervention.  Such close integration of ACME with HTTPS <del> servers would allow the immediate and automated deployment of certificates as they are issued, sparing the human administrator from much of the time-consuming work described in the previous section. </del>  3. client and the ACME server is the HTTPS server.  The ACME server acts as an HTTP and HTTPS client when validating challenges via HTTP.  ACME clients SHOULD send a User-Agent header in accordance with RFC7231, including the name and version of the ACME software in addition to the name and version of the underlying HTTP client All of these registries are under a heading of "Automated Certificate Management Environment (ACME) Protocol" and are administered under a <del> Specification Required policy RFC5226. </del>  9.7.1. that allows non-administrative users to write to .well-known, any user can claim to own the web server's hostname by responding to an HTTP challenge, and likewise for TLS configuration and TLS SNI.  The use of hosting providers is a particular risk for ACME validation.  If the owner of the domain has outsourced operation of

Comments / responses in this thread: URL Hello, Thank you to the editors and WG for your efforts on draft-ietf-acme-acme, it's a well written and easy to understand draft. I do have a few comments, that need to be address by the editors and SHEPHERD. Please review the idnits. There are a few warnings that should be correctable and can be addressed, but more importantly, it calls out several downrefs that are not in the shepherd writeup. These need to be in the writeup and then also mentioned in the IETF last call announcement (I'll make sure the latter happens). Here's my mostly editorial comments: Introduction: It reads very well, but it would be helpful to those unfamiliar with the work to explicitly state that ACME is about DV certificates. The first sentence of the last paragraph seems like the best place to add this in. Current text: 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. Proposed: This document describes an extensible framework for automating the issuance and domain validation procedure for DV certificates, thereby allowing servers and infrastructural software to obtain certificates without user interaction. I do like how the introduction is framed as it’s clear the level of security provided by the certificates issued via ACME. Thanks for that. The introduction should also make it clear that ACME can be used for other services using DV certificates, not just HTTP. This is mentioned in the Terminology section, but I think a clear sentence upfront would be helpful. Section 2: Nit/suggestion: Change the tense to read as a published RFC in the last paragraph, last sentence (take it or leave it). Current: Such close integration of ACME with HTTPS servers would allow the immediate and automated deployment of certificates as they are issued, sparing the human administrator from much of the time-consuming work described in the previous section. Proposed: Such close integration of ACME with HTTPS servers allows the immediate and automated deployment of certificates as they are issued, sparing the human administrator from much of the time-consuming work described in the previous section. IANA Section: Everything looks good except that RFC5226 has been obsoleted, so the new reference is RFC8126 and “specification required” URL still means the same thing, so using that is fine. Security considerations: I think it would be good to mention here that they are DV certs so the reader understands from he introduction and this section the level of cert issued through ACME and doesn’t assume a higher level of assurance. s/ACME is a protocol for managing certificates/ACME is a protocol for managing DV certificates/ I know this is obvious to the people in the WG, but a reference to RFC7525 to properly configure TLS 1.2 should be included to protect against the mentioned attacks. If you want to also reference TLS 1.3 and specify no 0-RTT that would be good too. It’d be great to see this get widely deployed, so there may be a number of newcomers reading this to make their lives easier with cert issuance/maintenance. what if the server that the account verifier has an account on (client for ACME) is compromised and is used to request new certificates or perform other actions? I think this is one of the larger risks, so mentioning this is possible and hardening measures should be taken to prevent compromise would be prudent. Hardening measures or appropriate security controls should be broadly understood terms (I think) so that you wouldn’t need to list out things like turing off unnecessary services. I would think you’d see requests for new phishing domains rather than known ones through this process. What would you look for there as that’s a complex problem - it would be hard to know all legit names to know if one was a play off of the original. This happened with equifax - they provided a site name with a typo and a ‘white hat’ attacker had set up a site that looked just like theirs at that site. But it was announced by equifax. Tough problem as automating a check on the DNS registration may not detect something unusual, but maybe recommending this check could help? RDP lessens what needs to be shared from whois though, although I don’t think that’s widely deployed. Best regards, Kathleen

deployment of HTTPS and the practicality of PKIX authentication for other protocols based on Transport Layer Security (TLS) RFC5246. <ins> It should be noted that while the focus of this document is on validating domain names for purposes of issuing certificates in the Web PKI, ACME supports extensions for uses with other identifiers in other PKI contexts.  For example, as of this writing, there is ongoing work to use ACME for issuance of WebPKI certificates attesting to IP addresses I-D.ietf-acme-ip and STIR certificates attesting to telephone numbers I-D.ietf-acme-telephone. </ins> 2. The guiding use case for ACME is obtaining certificates for websites certificate as with a self-signed certificate.  Furthermore, the maintenance of that CA-issued certificate would require minimal manual intervention.  Such close integration of ACME with HTTPS  <ins> servers allows the immediate and automated deployment of certificates as they are issued, sparing the human administrator from much of the time-consuming work described in the previous section. </ins> 3. client and the ACME server is the HTTPS server.  The ACME server acts as an HTTP and HTTPS client when validating challenges via HTTP. <ins> ACME servers SHOULD follow the recommendations of RFC7525 when configuring their TLS implementations.  ACME servers that support TLS 1.3 MAY allow clients to send early data (0xRTT).  This is safe because the ACME protocol itself includes anti-replay protections. </ins> ACME clients SHOULD send a User-Agent header in accordance with RFC7231, including the name and version of the ACME software in addition to the name and version of the underlying HTTP client All of these registries are under a heading of "Automated Certificate Management Environment (ACME) Protocol" and are administered under a  <ins> Specification Required policy RFC8126. </ins> 9.7.1. that allows non-administrative users to write to .well-known, any user can claim to own the web server's hostname by responding to an HTTP challenge, and likewise for TLS configuration and TLS SNI. <ins> Similarly, if a server that can be used for ACME validation is compromised by a malicious actor, then that malicious actor can use that access to obtain certificates via ACME. </ins> The use of hosting providers is a particular risk for ACME validation.  If the owner of the domain has outsourced operation of


The server SHOULD validate that the contact URLs in the "contact" field are valid and supported by the server.  If the server validates <del> contact URLs it MUST support the "mailto" scheme.  If the server rejects a contact URL for using an unsupported scheme it MUST return an error of type "unsupportedContact", with a description describing the error and what types of contact URLs the server considers acceptable.  If the server rejects a contact URL for using a supported scheme but an invalid value then the server MUST return an error of type "invalidContact". </del>  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

This doesn't address the other piece of feedback, that mailto URLs can contain multiple entries.
If you don't allow , then it's only possible to have one address.
Oh, no, that's totally wrong, will update.

The server SHOULD validate that the contact URLs in the "contact" field are valid and supported by the server.  If the server validates  <ins> contact URLs it MUST support the "mailto" scheme.  Clients MUST NOT provide a "mailto" URL in the "contact" field that contains "hfields" RFC6068, or more than one "addr-spec" in the "to" component.  If a server encounters a "mailto" contact URL that does not meet these criteria, then it SHOULD reject it as invalid. If the server rejects a contact URL for using an unsupported scheme it MUST return an error of type "unsupportedContact", with a description describing the error and what types of contact URLs the server considers acceptable.  If the server rejects a contact URL for using a supported scheme but an invalid value then the server MUST return an error of type "invalidContact". </ins> 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


RFC3339.  This field is REQUIRED for objects with "valid" in the "status" field. <del> If this field is present, then it MUST contain a URL for an order resource, such that this authorization is only valid for that resource.  If this field is absent, then the CA MUST consider this authorization valid for all orders until the authorization expires. </del> For pending authorizations, the challenges that the client can fulfill in order to prove possession of the identifier.  For final authorizations, the challenges that were used.  Each array entry This process may be repeated to associate multiple identifiers to a key pair (e.g., to request certificates with multiple identifiers), or to associate multiple accounts with an identifier (e.g., to allow <del> multiple entities to manage certificates).  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. </del>  Authorization resources are created by the server in response to certificate orders or authorization requests submitted by an account

It is no longer necessary with the order based issuance flow that allows the server to specify which authorizations a client must satisfy to allow issuance of an order. See URL Section 7.1.4 "Authorization Objects" describes an optional "scope" field. If present it must be a URI pointing to an order and the authorization is considered to be valid only for that order. If no scope value is present it is assumed that the authorization is valid for any order. Looking back at the PR that introduced the "scope" field[0] and knowing the current state of order based issuance I'm not clear why this field is needed, or what a client could do with the scope information. Can someone clarify or should this part of the spec be removed? The server determines as a matter of policy which authorizations are required for an order and includes these in the order's array. If part of that server policy is to treat some valid authorizations as only being valid for a specific order then the server can simply not include those valid authorizations in the order's authorizations array and can instead create new pending authorizations for the client to solve. The client doesn't need to understand authorization scope it just needs to know which authorizations the server says are required and how to move these authorizations to a valid state. Since the client can't ask for specific authorizations to be used with specific orders and must react to what the server provides why is it helpful to tell a client that one of the authorizations it solved won't be used with future orders? Similarly I think the scope field interacts weirdly with pre-authorization. Are all authorization objects created with pre-authorization assumed to be global scope since they aren't associated with an order? Have any ACME clients or servers implemented order scope? Let's Encrypt/Boulder/Pebble have not. Daniel / cpu [0] - URL

RFC3339.  This field is REQUIRED for objects with "valid" in the "status" field.  For pending authorizations, the challenges that the client can fulfill in order to prove possession of the identifier.  For final authorizations, the challenges that were used.  Each array entry This process may be repeated to associate multiple identifiers to a key pair (e.g., to request certificates with multiple identifiers), or to associate multiple accounts with an identifier (e.g., to allow  <ins> multiple entities to manage certificates). </ins> Authorization resources are created by the server in response to certificate orders or authorization requests submitted by an account


determine the correct issuer domain name to use when configuring CAA records.  Clients access the directory by sending a GET request to the directory URL. The "signature" field of the JWS will contain the MAC value computed with the MAC key provided by the CA.  When a CA receives a new-account request containing an "external- account-binding" field, it decides whether or not to verify the binding.  If the CA does not verify the binding, then it MUST NOT

While addressing Dale's Gen-ART comments, it occurred to me that while the document said that a CA could require external account binding, it didn't say how. This PR adds a "meta" field and an error code to support that requirements proactively and reactively.
Merging based on NAME review
:ship:

determine the correct issuer domain name to use when configuring CAA records. <ins> If this field is present and set to "true", then the CA requires that all new-account requests include an "external-account- binding" field associating the new account with an external account. </ins> Clients access the directory by sending a GET request to the directory URL. The "signature" field of the JWS will contain the MAC value computed with the MAC key provided by the CA. <ins> If a CA requires that new-account requests contain an "external- account-binding" field, then it MUST provide the value "true" in the "external-account-required" subfield of the "meta" field in the directory object.  If the CA receives a new-account request without an "external-account-binding" field, then it should reply with an error of type "externalAccountRequired". </ins> When a CA receives a new-account request containing an "external- account-binding" field, it decides whether or not to verify the binding.  If the CA does not verify the binding, then it MUST NOT


key, from which the server can look up related authorizations. A CSR encoding the parameters for the certificate being requested. <del> The CSR is sent in the Base64-encoded version of the DER format. (Note: This field uses the same modified Base64-encoding rules used elsewhere in this document, so it is different from PEM.) </del>  The CSR encodes the client's requests with regard to the content of the certificate to be issued.  The CSR MUST indicate the requested is a JWS object whose JSON payload contains the certificate to be revoked: <del> The certificate to be revoked, in the Base64-encoded version of the DER format.  (Note: This field uses the same modified Base64-encoding rules used elsewhere in this document, so it is different from PEM.) </del>  Revocation requests are different from other ACME request in that they can be signed either with an account key pair or the key pair in The "JWK_Thumbprint" step indicates the computation specified in RFC7638, using the SHA-256 digest.  As specified in the individual challenges below, the token for a challenge is a JSON string <del> comprised entirely of characters in the base64 alphabet.  The "||" operator indicates concatenation of strings. </del>  In computations involving key authorizations, such as the digest computations required for the DNS and TLS SNI challenges, the key authorization string MUST be represented in UTF-8 form (or, equivalently, ASCII).  7.2. With HTTP validation, the client in an ACME transaction proves its the client's account key.  The client then computes the SHA-256 digest of the key authorization. <del> The record provisioned to the DNS is the base64 encoding of this </del>  digest.  The client constructs the validation domain name by prepending the label "_acme-challenge" to the domain name being validated, then provisions a TXT record with the digest value under

All of the Base64 strings are actually Base64 URL encoded In the Java support for big ints the top byte is set to 0 to eliminate issues with signs. The thumbprint used here does not support that. It would be useful to mention that in the spec. I think it would help if there was an appendix with a complete example from key to key authorization to help clarify the points above.
Right, point 3 is pretty unclear and requires searching with your favorite search engine.

key, from which the server can look up related authorizations. A CSR encoding the parameters for the certificate being requested.  <ins> The CSR is sent in the Base64url-encoded version of the DER format.  (Note: This field uses the same modified Base64 encoding rules used elsewhere in this document, so it is different from PEM.) </ins> The CSR encodes the client's requests with regard to the content of the certificate to be issued.  The CSR MUST indicate the requested is a JWS object whose JSON payload contains the certificate to be revoked:  <ins> The certificate to be revoked, in the Base64url-encoded version of the DER format.  (Note: This field uses the same modified Base64 encoding rules used elsewhere in this document, so it is different from PEM.) </ins> Revocation requests are different from other ACME request in that they can be signed either with an account key pair or the key pair in The "JWK_Thumbprint" step indicates the computation specified in RFC7638, using the SHA-256 digest.  As specified in the individual challenges below, the token for a challenge is a JSON string  <ins> comprised entirely of characters in the URL-safe Base64 alphabet. The "||" operator indicates concatenation of strings. </ins> In computations involving key authorizations, such as the digest computations required for the DNS and TLS SNI challenges, the key authorization string MUST be represented in UTF-8 form (or, equivalently, ASCII). <ins> An example of how to compute a JWK thumbprint can be found in Section 3.1 of RFC7638.  Note that some cryptographic libraries prepend a zero octet to the representation of the RSA public key parameters N and E, in order to avoid ambiguity with regard to the sign of the number.  As noted in JWA, a JWK object MUST NOT include this zero octet.  That is, any initial zero octets MUST be stripped before the values are Base64url-encoded. </ins> 7.2. With HTTP validation, the client in an ACME transaction proves its the client's account key.  The client then computes the SHA-256 digest of the key authorization.  <ins> The record provisioned to the DNS is the base64url encoding of this </ins> digest.  The client constructs the validation domain name by prepending the label "_acme-challenge" to the domain name being validated, then provisions a TXT record with the digest value under


successful.  If no DNS record is found, or DNS record and response payload do not pass these checks, then the validation fails. <del> 8.6. There may be cases where a server cannot perform automated validation of an identifier, for example, if validation requires some manual steps.  In such cases, the server may provide an "out of band" (OOB) challenge to request that the client perform some action outside of ACME in order to validate possession of the identifier. The OOB challenge requests that the client have a human user visit a web page to receive instructions on how to validate possession of the identifier, by providing a URL for that web page. The string "oob-01" The URL to be visited.  The scheme of this URL MUST be "http" or "https".  Note that this field is distinct from the "url" field of the challenge, which identifies the challenge itself. A client responds to this challenge by presenting the indicated URL for a human user to navigate to.  If the user chooses to complete this challenge (by visiting the website and completing its instructions), the client indicates this by sending a simple acknowledgement response to the server.  The payload of this response is an empty JSON object ("{}", or "e30" base64url-encoded). On receiving a response, the server MUST verify that the value of the "type" field is "oob-01".  Otherwise, the steps the server takes to validate identifier possession are determined by the server's local policy. </del> 9. 9.1. CAs using ACME to allow clients to agree to terms of service should keep in mind that ACME clients can automate this agreement, possibly <del> not involving a human user.  If a CA wishes to have stronger evidence of user consent, it may present an out-of-band requirement or challenge to require human involvement. </del>  11.

The OOB challenge was added to accommodate non-ACME CAs building ACME integrations. Since then two non-ACME CAs have implemented ACME integrations using the external account binding feature but not implementing OOB challenges. Since the target demographic has not implemented this feature and has also not presented a use-case requiring it there seems to be no strong reasons to keep it in-spec.
NAME If you could update this to remove the OOB challenge from the , I'll go ahead and merge
NAME Good catch - thanks! Addressed in 0753c73.

successful.  If no DNS record is found, or DNS record and response payload do not pass these checks, then the validation fails.  9. 9.1. CAs using ACME to allow clients to agree to terms of service should keep in mind that ACME clients can automate this agreement, possibly  <ins> not involving a human user. </ins> 11.


ACME Resource Types (iana-resource)  ACME Identifier Types (iana-identifier) ACME Validation Methods (iana-validation) Initial contents: The fields and descriptions defined in account- objects.  9.7.2. This registry lists field names that are defined for use in ACME Initial contents: The fields and descriptions defined in order- objects.  9.7.3. This registry lists field names that are defined for use in ACME Initial contents: The fields and descriptions defined in authorization-objects.  9.7.4. This registry lists values that are used within URN values that are 9.7.6.  This registry lists the types of identifiers that can be present in ACME authorization objects. [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned to this document ]] <del> 9.7.7. </del>  This registry lists identifiers for the ways that CAs can validate control of identifiers.  Each method's entry must specify whether it

Also, add some more "replace RFC XXXX with this document" notes, for clarity. Thanks to NAME for noticing that this was missing.
Merging based on r+ from NAME
The new registry looks good :+1: - no changes to request there. The existing directory registry () should probably have a "meta" entry:

ACME Resource Types (iana-resource) <ins> ACME Directory Metadata Fields (iana-meta) </ins> ACME Identifier Types (iana-identifier) ACME Validation Methods (iana-validation) Initial contents: The fields and descriptions defined in account- objects. <ins> [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned to this document ]] </ins> 9.7.2. This registry lists field names that are defined for use in ACME Initial contents: The fields and descriptions defined in order- objects. <ins> [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned to this document ]] </ins> 9.7.3. This registry lists field names that are defined for use in ACME Initial contents: The fields and descriptions defined in authorization-objects. <ins> [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned to this document ]] </ins> 9.7.4. This registry lists values that are used within URN values that are 9.7.6. <ins> This registry lists field names that are defined for use in the JSON object included in the "meta" field of an ACME directory object. Template: Field name: The string to be used as a field name in the JSON object Field type: The type of value to be provided, e.g., string, boolean, array of string Reference: Where this field is defined Initial contents: The fields and descriptions defined in account- objects. [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned to this document ]] 9.7.7. </ins> This registry lists the types of identifiers that can be present in ACME authorization objects. [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned to this document ]]  <ins> 9.7.8. </ins> This registry lists identifiers for the ways that CAs can validate control of identifiers.  Each method's entry must specify whether it


In particular, the server MUST include a Link relation header field RFC5988 with relation "up" to provide a certificate under which this certificate was issued, and one with relation "author" to indicate <del> the registration under which this certicate was issued.  The server MAY also include an Expires header as a hint to the client about when to renew the certificate.  (Of course, the real expiration of the certificate is controlled by the notAfter time in the certificate itself.) </del>  A certificate resource always represents the most recent certificate issued for the name/key binding expressed in the CSR.  If the CA

The idea here is that if the CA opts not to log the precertificates it has a mechanism for publishing the proofs that are associated with a cert.
There are two good mechanisms to do this without adding a new endpoint: The CA implementing ACME can include SCTs in its OCSP responses Subscribers that wish to use SCTs, for instance in the TLS Extension mode of operation, may fetch those SCTs directly from the CT logs.
Neither of these seem like great substitutes. The first seems to violate straightforward reference semantics. The second puts a lot more work on the server.
I think this can be easily solved with a .

In particular, the server MUST include a Link relation header field RFC5988 with relation "up" to provide a certificate under which this certificate was issued, and one with relation "author" to indicate  <ins> the registration under which this certicate was issued. The server MAY include an Expires header as a hint to the client about when to renew the certificate.  (Of course, the real expiration of the certificate is controlled by the notAfter time in the certificate itself.) If the CA particpates in Certificate Transparency (CT) RFC6962, then they may want to provide the client with a Signed Certificate Timestamp (SCT) that can be used to prove that a certificate was submitted to a CT log.  An SCT can be included as a extension in the certificate or as an extension to OCSP responses for the certificate. The server can also provide the client with direct access to an SCT for a certificate using a Link relation header field with relation "ct-sct". </ins> A certificate resource always represents the most recent certificate issued for the name/key binding expressed in the CSR.  If the CA