characters outside the base64url alphabet, and MUST NOT include base64 padding characters ("="). <del> A client responds to this challenge by constructing a key authorization from the "token" value provided in the challenge and the client's account key.  The client then provisions the key authorization as a resource on the HTTP server for the domain in question. </del>  The path at which the resource is provisioned is comprised of the fixed prefix "/.well-known/acme-challenge/", followed by the "token" value in the challenge.  The value of the resource MUST be the ASCII representation of the key authorization. <del> The client's response to the validation request indicates its agreement to this challenge by sending the server the key authorization covering the challenge's token and the client's account key. </del>  <del> The key authorization for this challenge.  This value MUST match the token from the challenge and the client's account key. On receiving a response, the server MUST verify that the key authorization in the response matches the "token" value in the challenge and the client's account key.  If they do not match, then the server MUST return an HTTP error in response to the POST request in which the client sent the challenge. </del>  Given a challenge/response pair, the server verifies the client's control of the domain by verifying that the resource was provisioned the end of the body. Verify that key authorization provided by the HTTP server matches <del> the key authorization provided by the client in its response to the challenge. </del>  The server SHOULD follow redirects when dereferencing the URL. 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 client's account key.  The client then computes the SHA-256 digest FIPS180-4 of the key authorization. </del>  The record provisioned to the DNS contains the base64url encoding of this digest.  The client constructs the validation domain name by "example.org", then the client would provision the following DNS record: <del> The response to the DNS challenge provides the computed key authorization to acknowledge that the client is ready to fulfill this challenge. The key authorization for this challenge.  This value MUST match the token from the challenge and the client's account key. </del>  <del> On receiving a response, the server MUST verify that the key authorization in the response matches the "token" value in the challenge and the client's account key.  If they do not match, then the server MUST return an HTTP error in response to the POST request in which the client sent the challenge. </del>  To validate a DNS challenge, the server performs the following steps: <del> Compute the SHA-256 digest FIPS180-4 of the key authorization </del>  Query for TXT records for the validation domain name

Respond with {} instead of providing keyAuthorization Remove "keyAuthorization" from the challenge object returned by the server. Fixes a potential misguide for clients that enabels a MitM attack. Keep the storing of the keyAuthorization on response to retain the same behavior if an account key roll-over happens before the challenge is validated
I like this change in theory, but it's substantive enough that I'd like to give the mailing list a couple more pokes to see if anyone has further thoughts on it before we land it.
This is not an editorial change, and I think it would require pushing back further on last-call timing. Please bring this up and discuss on the mailing list; WG consensus will be required.
This was brought up on the list Dec 27th and only positive responses were received.
https://ietf-wg-URL From the spec This is not consistent with the example: Which is posting to . I would expect the example to show has . Also, there is no other mention of present in the example payload. Is this a mistake?
The example is correct. The URL for the challenge is , as shown in the response body above the example you cite: (Note the at the end that distinguishes the challenge from the authz URL ) As for the field, it looks like NAME fixed this in
thanks
This PR looks good to me. I think the proposed change makes sense and removes a potential error without sacrificing anything functionality wise. NAME NAME Can you give this a review as well?

characters outside the base64url alphabet, and MUST NOT include base64 padding characters ("=").  <ins> A client fulfills this challenge by constructing a key authorization from the "token" value provided in the challenge and the client's account key.  The client then provisions the key authorization as a resource on the HTTP server for the domain in question. </ins> The path at which the resource is provisioned is comprised of the fixed prefix "/.well-known/acme-challenge/", followed by the "token" value in the challenge.  The value of the resource MUST be the ASCII representation of the key authorization.  <ins> A client responds with an empty object ({}) to acknowledge that the challenge can be validated by the server. </ins>  <ins> On receiving a response, the server constructs and stores the key authorization from the challenge "token" value and the current client account key. </ins> Given a challenge/response pair, the server verifies the client's control of the domain by verifying that the resource was provisioned the end of the body. Verify that key authorization provided by the HTTP server matches  <ins> the key authorization stored by the server. </ins> The server SHOULD follow redirects when dereferencing the URL. characters outside the base64url alphabet, including padding characters ("=").  <ins> A client fulfills this challenge by constructing a key authorization from the "token" value provided in the challenge and the client's account key.  The client then computes the SHA-256 digest FIPS180-4 of the key authorization. </ins> The record provisioned to the DNS contains the base64url encoding of this digest.  The client constructs the validation domain name by "example.org", then the client would provision the following DNS record:  <ins> A client responds with an empty object ({}) to acknowledge that the challenge can be validated by the server. </ins>  <ins> On receiving a response, the server constructs and stores the key authorization from the challenge "token" value and the current client account key. </ins> To validate a DNS challenge, the server performs the following steps:  <ins> Compute the SHA-256 digest FIPS180-4 of the stored key authorization </ins> Query for TXT records for the validation domain name


array after they are created.  If a client observes a change in the contents of either array, then it SHOULD consider the order invalid. <del> The "authorizations" array in the challenge SHOULD reflect all </del>  authorizations that the CA takes into account in deciding to issue, even if some authorizations were fulfilled in earlier orders or in pre-authorization transactions.  For example, if a CA allows multiple

Rewrite "in challenge", which seems to be incorrect to "of the order"
Good catch! Thank you NAME :eagle: :mag:

array after they are created.  If a client observes a change in the contents of either array, then it SHOULD consider the order invalid.  <ins> The "authorizations" array of the order SHOULD reflect all </ins> authorizations that the CA takes into account in deciding to issue, even if some authorizations were fulfilled in earlier orders or in pre-authorization transactions.  For example, if a CA allows multiple


rules used elsewhere in this document, so it is different from PEM.)  The CSR encodes the client's requests with regard to the content of the certificate to be issued.  The CSR MUST indicate the requested identifiers, either in the commonName portion of the requested

The new-certificate transaction should allow the client to request a specific lifetime for a certificate. There is no mechanism in PKCS for this, so it will probably have to be JSON in the message body.
Does it also make sense to allow to specify different classes of certificates? For example, with the Let's Encrypt project, only Domain Validated (DV) certs are supported, but perhaps if ACME can become a standard interface for requesting, managing and exchanging certs to various CAs, a certificate request could indicate a , such as: Domain Validation (DV) Organization Validation (OV) Extended Validation (EV) Naturally the class of cert requested would dictate the types of Identity Authorization challenges that would be issued, so perhaps it would be necessary to specify the class at the time an Identity Authorization is requested to assert that level of certification for that Identity.
Being able to specify a certificate lifetime sees sensible. The server should be free to ignore the request. If one were to request OV/EV certificates, you'd need some way of expressing what organizational information to put on the certificate. Logically this would need to be attached to a validation, which means validations would need to start storing personal/organizational information. One would also need a way to specify the validations to be used when requesting a certificate. Since OV/EV involves paperwork for validation, the value proposition of enabling an automated certificate acquisition protocol for it seems minimal, though it could be useful if CAs were to expose their existing validation systems via ACME. You'd then have certain authorization types the acquisition of which is out-of-scope of the spec.
Organizational information is in the subject name, so it can go in the Subject field of the CSR in the new-certificate message. I agree that there are deeper issues to solve with OV/EV, though.
I think it makes sense that the org info would actually be tied to a registration -- that's the representation of the entity that owns the Identifiers (DNS names) that are later validated. The CSR would actually have the org info and one of the tests that the ACME CA would need to do is make sure that it lines up with what was registered. And then of course the validation that is offered up by the ACME server would need to be of a higher quality or threshold than the ones that are defined today (HTTP, DNS, SNI), but they could even include an "out-of-band" validation, for example that's performed offline. So once that validation is completed, however that takes place, then the client can continue to request certs for that validated Identifier.
A registration doesn't necessarily correspond to an organisation, though. A registration might be capable of representing more than one entity, or the same entity might be represented by multiple registrations, but not want to have to repeat the OV/EV verification process for each registration. I suppose you'd want a new authorization subject type, other than DNS, concerning business information. But there'd need to be some way to grant access from one registration's authorizations to another, or copy them, or something. For example a CDN might want to obtain EV certificates for its customers, but obviously this requires a customer to prove their identity and then delegate that authorization to the CDN, etc.

rules used elsewhere in this document, so it is different from PEM.) <ins> The requested value of the notBefore field in the certificate, in the date format defined in The requested value of the notBefore field in the certificate, in the date format defined in </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 identifiers, either in the commonName portion of the requested


qualified domain name (type: "dns").  If a domain name contains non- ASCII Unicode characters it MUST be encoded using the rules defined in RFC3492.  Servers MUST verify any identifier values that begin <del> with the ASCII Compatible Encoding prefix "xn-" as defined in RFC5890 are properly encoded.  Wildcard domain names (with "*" as the first label) MUST NOT be included in authorization objects. </del>  identifier-validation-challenges describes a set of challenges for domain name validation.

Prior to this commit the IDN prefix referenced from RFC5890 was being turned from to . This commit escapes the two dashes so they remain in the generated doc. Thanks to NAME for reporting! Resolves URL
In https://ietf-wg-URL This should be:
Opened URL with a fix. Thanks!

qualified domain name (type: "dns").  If a domain name contains non- ASCII Unicode characters it MUST be encoded using the rules defined in RFC3492.  Servers MUST verify any identifier values that begin  <ins> with the ASCII Compatible Encoding prefix "xn--" as defined in RFC5890 are properly encoded.  Wildcard domain names (with "*" as the first label) MUST NOT be included in authorization objects. </ins> identifier-validation-challenges describes a set of challenges for domain name validation.


"alg" (Algorithm) <del> "jwk" (JSON Web Key, only for requests to new-account and revoke-cert resources) </del>  <del> "kid" (Key ID, for all other requests) </del>  "nonce" (defined in replay-protection below) The "jwk" and "kid" fields are mutually exclusive.  Servers MUST reject requests that contain both. <del> For new-account requests, and for revoke-cert requests authenticated by certificate key, there MUST be a "jwk" field. </del>  <del> For all other requests, there MUST be a "kid" field.  This field must contain the account URL received by POSTing to the new-account resource. </del>  Note that authentication via signed JWS request bodies implies that GET requests are not authenticated.  Servers MUST NOT respond to GET 7.6. To request that a certificate be revoked, the client sends a POST <del> request to the ACME server's revoke-cert URL.  The body of the POST is a JWS object whose JSON payload contains the certificate to be </del>  revoked: The certificate to be revoked, in the base64url-encoded version of Revocation requests are different from other ACME requests in that they can be signed either with an account key pair or the key pair in <del> the certificate.  Before revoking a certificate, the server MUST verify that the key used to sign the request is authorized to revoke the certificate.  The server MUST consider at least the following accounts authorized for a given certificate: </del>  the account that issued the certificate.

The example was misleading in case a certificate is revoked by signing the revocation request with the certificate's private key. I assume "jwk" should be the public key from the certificate in this case and not the account key; see URL
Merging because it looks like the issue raised by NAME has been addressed.

"alg" (Algorithm)  <ins> "jwk" (JSON Web Key, for all requests not signed using an existing account, e.g. newAccount) </ins>  <ins> "kid" (Key ID, for all requests signed using an existing account) </ins> "nonce" (defined in replay-protection below) The "jwk" and "kid" fields are mutually exclusive.  Servers MUST reject requests that contain both.  <ins> For newAccount requests, and for revokeCert requests authenticated by certificate key, there MUST be a "jwk" field.  This field MUST contain the public key corresponding to the private key used to sign the JWS. </ins>  <ins> For all other requests, the request is signed using an existing account and there MUST be a "kid" field.  This field MUST contain the account URL received by POSTing to the newAccount resource. </ins> Note that authentication via signed JWS request bodies implies that GET requests are not authenticated.  Servers MUST NOT respond to GET 7.6. To request that a certificate be revoked, the client sends a POST  <ins> request to the ACME server's revokeCert URL.  The body of the POST is a JWS object whose JSON payload contains the certificate to be </ins> revoked: The certificate to be revoked, in the base64url-encoded version of Revocation requests are different from other ACME requests in that they can be signed either with an account key pair or the key pair in  <ins> the certificate. Example using an account key pair for the signature: Example using the certificate key pair for the signature: Before revoking a certificate, the server MUST verify that the key used to sign the request is authorized to revoke the certificate. The server MUST consider at least the following accounts authorized for a given certificate: </ins> the account that issued the certificate.


One of the revocation reasonCodes defined in Section 5.3.1 of RFC5280 to be used when generating OCSP responses and CRLs.  If <del> this field is not set the server SHOULD use the unspecified (0) reasonCode value when generating OCSP responses and CRLs.  The </del>  server MAY disallow a subset of reasonCodes from being used by the user.  If a request contains a disallowed reasonCode the server MUST reject it with the error type

As recommended by . Thanks to for the catch.
NAME I believe you need write, admin, or owner permissions on the repo for a "changes requested" review to show up this way in the GH UI.
(Merging myself because it's the real author is NAME I'm just the scribe)
Could you please change the spelling? (Why won't I get a "Changes requested" with red marker?) Hello, https://ietf-wg-URL states: If this field is not set the server SHOULD use the unspecified (0) reasonCode value when generating OCSP responses and CRLs. Yet URL says the opposite: the reason code CRL entry extension SHOULD be absent instead of using the unspecified (0) reasonCode value. Could this be reworded somehow? It would make sense to store `0' in a database but later don't add a CRLReason extension / ASN.1 field. Cheers, Jörn

One of the revocation reasonCodes defined in Section 5.3.1 of RFC5280 to be used when generating OCSP responses and CRLs.  If  <ins> this field is not set the server SHOULD omit the reasonCode CRL entry extension when generating OCSP responses and CRLs.  The </ins> server MAY disallow a subset of reasonCodes from being used by the user.  If a request contains a disallowed reasonCode the server MUST reject it with the error type


6.4.  Once a client has created an account with an ACME server, it is possible that the private key for the account will be lost.  The recovery contacts included in the registration allows the client to may now use this in the same way as if he had gotten it from a new- registration transaction. <del> 6.5. </del>  The identifier authorization process establishes the authorization of an account to manage certificates for a given identifier.  This the validation is still in progress, the server MUST return a 202 (Accepted) response with a Retry-After header field. <del> 6.6. </del>  The holder of an authorized key pair for an identifier may use ACME to request that a certificate be issued for that identifier.  The the certificate URI does not yield one, then the client may initiate a new-certificate transaction to request one. <del> 6.7. </del>  To request that a certificate be revoked, the client sends a POST request to the ACME server's revoke-cert URI.  The body of the POST

What advantage does including the old key provide?
Having the new key sign over the field makes the hand-over mutual -- the old key blesses the new key by signing over the JWS and the new key accepts by signing over the thumbprint. Basically, the field is acting as an identifier for the registration for purposes of the new key's acceptance of the hand-over. Note that this is well-defined because the server is required to only have one registration for a given key-pair (it MUST return a 409/Conflict if there's an attempt to duplicate).
Account keys should change over time to improve security. We should have a way to change the key associated with an account with changing anything else about the account. Something liike: Post: /rotate-key { "key": { / JWK key / } } Note: The request should be signed with the old key. All authorizations should remain with the account. If there are any requests being validated then they should still use the old key (as specified by the oriignal authorization request.

6.4. <ins> A client may wish to change the public key that is associated with a registration, e.g., in order to mitigate the risk of key compromise. To do this, the client first constructs a JSON object representing a request to update the registration: The string "reg", indicating an update to the registration. The JWK thumbprint of the old key RFC7638, base64url-encoded The client signs this object with the new key pair and encodes the object and signature as a JWS.  The client then sends this JWS to the server in the "newKey" field of a request to update the registration. On receiving a request to the registration URL with the "newKey" attribute set, the server MUST perform the following steps: Check that the contents of the "newKey" attribute are a valid JWS Check that the "newKey" JWS verifies using the key in the "jwk" header parameter of the JWS Check that the payload of the JWS is a valid JSON object Check that the "resource" field of the object has the value "reg" Check that the "oldKey" field of the object contains the JWK thumbprint of the account key for this registration If all of these checks pass, then the server updates the registration by replacing the old account key with the public key carried in the "jwk" header parameter of the "newKey" JWS object. 6.5. </ins> Once a client has created an account with an ACME server, it is possible that the private key for the account will be lost.  The recovery contacts included in the registration allows the client to may now use this in the same way as if he had gotten it from a new- registration transaction.  <ins> 6.6. </ins> The identifier authorization process establishes the authorization of an account to manage certificates for a given identifier.  This the validation is still in progress, the server MUST return a 202 (Accepted) response with a Retry-After header field.  <ins> 6.7. </ins> The holder of an authorized key pair for an identifier may use ACME to request that a certificate be issued for that identifier.  The the certificate URI does not yield one, then the client may initiate a new-certificate transaction to request one.  <ins> 6.8. </ins> To request that a certificate be revoked, the client sends a POST request to the ACME server's revoke-cert URI.  The body of the POST


challenge failed. Different challenges allow the server to obtain proof of different <del> aspects of control over an identifier.  In some challenges, like HTTP, TLS SNI, and DNS, the client directly proves its ability to do certain things related to the identifier.  The choice of which challenges to offer to a client under which circumstances is a matter of server policy. </del>  The identifier validation challenges described in this section all relate to validation of domain names.  If ACME is extended in the 8.4. <del> The TLS with Server Name Indication (TLS SNI) validation method proves control over a domain name by requiring the client to configure a TLS server referenced by the DNS A and AAAA resource records for 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 TLS server and verifying a particular certificate is presented. The string "tls-sni-02" A random value that uniquely identifies the challenge.  This value MUST have at least 128 bits of entropy.  It MUST NOT contain any characters outside the base64url alphabet, including padding characters ("="). A client responds to this challenge by constructing a self-signed certificate which the client MUST provision at the domain name concerned in order to pass the challenge. The certificate may be constructed arbitrarily, except that each certificate MUST have exactly two subjectAlternativeNames, SAN A and SAN B.  Both MUST be dNSNames RFC5280. SAN A MUST be constructed as follows: compute the SHA-256 digest FIPS180-4 of the challenge token and encode it in lowercase hexadecimal form.  The dNSName is "x.y.token.acme.invalid", where x is the first half of the hexadecimal representation and y is the second half. SAN B MUST be constructed as follows: compute the SHA-256 digest of the key authorization and encode it in lowercase hexadecimal form. The dNSName is "x.y.ka.acme.invalid" where x is the first half of the hexadecimal representation and y is the second half. The client MUST ensure that the certificate is served to TLS connections specifying a Server Name Indication (SNI) value of SAN A. The response to the TLS-SNI challenge simply acknowledges that the client is ready to fulfill this challenge. The key authorization for this challenge.  This value MUST match the token from the challenge and the client's account key. On receiving a response, the server MUST verify that the key authorization in the response matches the "token" value in the challenge and the client's account key.  If they do not match, then the server MUST return an HTTP error in response to the POST request in which the client sent the challenge. Given a challenge/response pair, the ACME server verifies the client's control of the domain by verifying that the TLS server was configured appropriately, using these steps: Compute SAN A and SAN B in the same way as the client. Open a TLS connection to the domain name being validated, presenting SAN A in the SNI field.  This connection MUST be sent to TCP port 443 on the TLS server.  In the ClientHello initiating the TLS handshake, the server MUST include a server_name extension (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 proves association with the client. Verify that the certificate contains a subjectAltName extension containing dNSName entries of SAN A and SAN B and no other entries.  The comparison MUST be insensitive to case and ordering of names. If all of the above verifications succeed, then the validation is successful.  Otherwise, the validation fails. 8.5. </del> When the identifier being validated is a domain name, the client can prove control of that domain by provisioning a TXT resource record containing a designated value for a specific validation domain name. HTTP: Provision files under .well-known on a web server for the domain <del> TLS SNI: Configure a TLS server for the domain </del> DNS: Provision DNS resource records for the domain There are several ways that these assumptions can be violated, both by misconfiguration and by attacks.  For example, on a web server 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 <del> HTTP challenge, and likewise for TLS configuration and TLS SNI. 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. </del>  The use of hosting providers is a particular risk for ACME validation.  If the owner of the domain has outsourced operation of The DNS is a common point of vulnerability for all of these challenges.  An entity that can provision false DNS records for a domain can attack the DNS challenge directly and can provision false <del> A/AAAA records to direct the ACME server to send its TLS SNI or HTTP validation query to a remote 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) hosting providers noted above are a particular case. It is RECOMMENDED that the server perform DNS queries and make HTTP <del> and TLS connections from various network perspectives, in order to make MitM attacks harder. </del>  10.3. 11.2. <del> In many cases, TLS-based services are deployed on hosted platforms that use the Server Name Indication (SNI) TLS extension to distinguish between different hosted services or "virtual hosts". When a client initiates a TLS connection with an SNI value indicating a provisioned host, the hosting platform routes the connection to that host. When a connection comes in with an unknown SNI value, one might expect the hosting platform to terminate the TLS connection. However, some hosting platforms will choose a virtual host to be the "default", and route connections with unknown SNI values to that host. In such cases, the owner of the default virtual host can complete a TLS-based challenge (e.g., "tls-sni-02") for any domain with an A record that points to the hosting platform.  This could result in mis-issuance in cases where there are multiple hosts with different owners resident on the hosting platform. A CA that accepts TLS-based proof of domain control should attempt to check whether a domain is hosted on a domain with a default virtual host before allowing an authorization request for this host to use a TLS-based challenge.  Typically, systems with default virtual hosts do not allow the holder of the default virtual host to control what certificates are presented on a request-by-request basis.  Rather, the default virtual host can configure which certificate is presented in TLS on a fairly static basis, so that the certificate presented should be stable over small intervals. A CA can detect such a bounded default vhost by initiating TLS connections to the host with random SNI values within the namespace used for the TLS-based challenge (the "acme.invalid" namespace for "tls-sni-02").  If it receives the same certificate on two different connections, then it is very likely that the server is in a default virtual host configuration.  Conversely, if the TLS server returns an unrecognized_name alert, then this is an indication that the server is not in a default virtual host configuration. </del>  11.3. <del> 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 initial authorization request. 11.4. </del> ACME provides certificate chains in the widely-used format known colloquially as PEM (though it may diverge from the actual Privacy Enhanced Mail specifications RFC1421, as noted in RFC7468).  Some

Recent developments[[0]] [[1]] [[2]] have identified real-world server/hosting configurations that violate the assumptions of TLS-SNI-01 and its currently specified replacement, TLS-SNI-02. In light of these issues and the feasibility of addressing them across the entire Internet it seems prudent that the ACME specification remove the affected challenge type pending the development of a better alternative (TLS-SNI-03?). This will allow the draft last-call to proceed while the details of TLS-SNI-03 are worked out. The "Default Virtual Hosts" sub-section of the "Operational Considerations" section is removed since it spoke exclusively to a concern with TLS-SNI-02 validation. When the dust has settled on TLS-SNI-03 we should certainly include a section that describes why TLS-SNI-01/02 were removed that could replace this information. [0]: URL [1]: URL [2]: URL
NAME I don't think we need a place-holder in-doc for this
r+ with the one comment addressedShould there be any mention of that makes sure we use in a future RFC in case if gets re-added?

challenge failed. Different challenges allow the server to obtain proof of different  <ins> aspects of control over an identifier.  In some challenges, like HTTP and DNS, the client directly proves its ability to do certain things related to the identifier.  The choice of which challenges to offer to a client under which circumstances is a matter of server policy. </ins> The identifier validation challenges described in this section all relate to validation of domain names.  If ACME is extended in the 8.4.  When the identifier being validated is a domain name, the client can prove control of that domain by provisioning a TXT resource record containing a designated value for a specific validation domain name. HTTP: Provision files under .well-known on a web server for the domain  DNS: Provision DNS resource records for the domain There are several ways that these assumptions can be violated, both by misconfiguration and by attacks.  For example, on a web server 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  <ins> HTTP challenge.  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 DNS is a common point of vulnerability for all of these challenges.  An entity that can provision false DNS records for a domain can attack the DNS challenge directly and can provision false  <ins> A/AAAA records to direct the ACME server to send its HTTP 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) hosting providers noted above are a particular case. It is RECOMMENDED that the server perform DNS queries and make HTTP  <ins> connections from various network perspectives, in order to make MitM attacks harder. </ins> 10.3. 11.2.  <ins> The http-01, 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 initial authorization request. </ins> 11.3.  ACME provides certificate chains in the widely-used format known colloquially as PEM (though it may diverge from the actual Privacy Enhanced Mail specifications RFC1421, as noted in RFC7468).  Some


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 URL <del> in a Location header field. </del>  7.3.1.

Section 6.2 "Request Authentication" says: Prior to this commit Section 7.3 "Account Creation" doesn't mention that the account URL also doubles as the key ID. To make the question of "What is my Key ID?" more obvious for client implementers this commit adds a brief mention of this fact where the specification discusses the account URL. Thanks to NAME for flagging this and providing a chance to avoid confusion and add clarity.
thanks

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 URL  <ins> in a Location header field.  The account URL is used as the "kid" value in the JWS authenticating subsequent requests by this account (See request-authentication). </ins> 7.3.1.


The JWS MUST NOT have the value "none" in its "alg" field  The JWS MUST NOT have a Message Authentication Code (MAC)-based algorithm in its "alg" field document returned with the error MUST include an "algorithms" field with an array of supported "alg" values. <del> In the examples below, JWS objects are shown in the JSON or flattened JSON serialization, with the protected header and payload expressed as base64url(content) instead of the actual base64-encoded value, so that the content is readable. </del> 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 provided to clients and having the resource check that requests have the same string in their "url" header parameter. <del> 6.3.1. </del>  The "url" header parameter specifies the URL RFC3986 to which this 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. <del> 6.4. </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.4.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.4.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.5. </del>  Creation of resources can be rate limited by ACME servers to ensure fair usage and prevent abuse.  Once the rate limit is exceeded, the "Link" header pointing to documentation about the specific rate limit that was hit, using the "help" link relation type. <del> 6.6. </del>  Errors can be reported in ACME both at the HTTP layer and within challenge objects as defined in identifier-validation-challenges. example, an "error of type 'badCSR'" refers to an error document with "type" value "urn:ietf:params:acme:error:badCSR". <del> 6.6.1. </del>  Sometimes a CA may need to return multiple errors in response to a request.  Additionally, the CA may need to attribute errors to

This change is designed to partially address the JWS serialization format issues raised in the and threads on the mailing list. This change uses the Content-Type header to specify JWS serialization formats, and includes restrictions on the serializations. It doesn't include converting between serializations, or how to handle inner JWS messages. In short, this change should be a cleaner version of that still allows the compact serialization. Specifically, this change requires ACME implementations to use the HTTP Content-Type header to indicate the JWS serialization format used for the request body. The change also specifies restrictions on the specific serialization formats when used with ACME (don't use unencoded payloads, don't use detached payloads, don't use unprotected headers). In addition, the change prohibits multiple signatures in JWS objects used for ACME purposes. This change doesn't include advice on how to convert between the JWS serializations. Converting between JWS serializations may be needed if, for example, an ACME implementation uses a JWS library that doesn't support all JWS serializations and/or doesn't provide programmers with control over what JWS serialization is produced. In such cases, programmers may have to convert between JWS serializations before and/or after using said pre-existing JWS library. I have started a draft of a separate JOSE serialization conversion guide at URL The separate conversion guide is designed to not be ACME-specific. Accordingly, the separate conversion guide includes things like unencoded payloads, detached payloads, unprotected headers, and JWEs. One thing that is not included in this change is how the serialization format requirements should be applied to a "nested" JWS like the one found in a key change or an external account binding. Should a "nested" JWS be required to use the same serialization as the "outer" JWS? If a nested JWS should follow the outer JWS serialization format, the following additional changes may need to be made: Change the new "JWS Serialization Formats" section (introduced in this pull request). For example, the list in that section could be changed to the following: Content-Type "application/jose": A JWS of this Content-Type MUST meet the following criteria: The JWS Compact Serialization {{!RFC7515}} MUST be used. The JWS Payload MUST NOT be detached. The JWS Unencoded Payload Option {{!RFC7797}} MUST NOT be used. A JWS placed anywhere inside the payload of a JWS of this Content-Type MUST meet the above criteria as well. Content-Type "application/jose+json": A JWS of this Content-Type MUST meet the following criteria: Either the JWS Flattened JSON {{!RFC7515}} or the JWS General JSON {{!RFC7515}} Serialization MUST be used. The JWS Payload MUST NOT be detached. The JWS Unencoded Payload Option {{!RFC7797}} MUST NOT be used. The JWS Unprotected Header {{!RFC7515}} SHOULD NOT be used. A JWS placed anywhere inside the payload of a JWS of this Content-Type MUST meet the above criteria as well. Update the specifications for the nested JWS: Right now, "externalAccountBinding" can be an object. If this JWS must follow the same guidelines as the outer JWS, "externalAccountBinding" could be an "object or string", depending on whether a JSON or compact serialization is used. If I understand correctly, the payload of the outer JWS for the "keyChange" (Account Key Roll-Over) endpoint is not a JSON object like in the other ACME requests. Instead, the payload for the "outer" JWS for this endpoint is merely this nested JWS itself. If this understanding is correct, I don't think any changes have to be made. If this understanding is not correct, I am not sure what changes may have to be made.
I verified locally that this branch passes CI tests. For some reason, I don't have permission to re-run CI. I'm about to send another PR on top of this one to fix a minor bug, so CI will run then.

The JWS MUST NOT have the value "none" in its "alg" field <ins> The JWS MUST NOT have multiple signatures. </ins> The JWS MUST NOT have a Message Authentication Code (MAC)-based algorithm in its "alg" field document returned with the error MUST include an "algorithms" field with an array of supported "alg" values.  6.3. <ins> The JSON Web Signature (JWS) specification RFC7515 contains multiple JWS serialization formats.  When sending an ACME request with a non- empty body, an ACME client implementation MUST use the HTTP Content- Type RFC7231 header to indicate which JWS serialization format is used for encapsulating the ACME request payload.  The following Content-Type values may be used for this purpose: "application/jose": The JWS Compact Serialization RFC7515 MUST be used. The JWS Payload MUST NOT be detached. The JWS Unencoded Payload Option RFC7797 MUST NOT be used. "application/jose+json": Either the JWS Flattened JSON Serialization RFC7515 or the JWS General JSON Serialization RFC7515 MUST be used. The JWS Payload MUST NOT be detached. The JWS Unencoded Payload Option RFC7797 MUST NOT be used. The JWS Unprotected Header RFC7515 SHOULD NOT be used. In the examples below, JWS objects are shown in the General JSON or Flattened JSON serialization, with the protected header and payload expressed as base64url(content) instead of the actual base64-encoded value, so that the content is readable. 6.4. </ins> 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 provided to clients and having the resource check that requests have the same string in their "url" header parameter.  <ins> 6.4.1. </ins> The "url" header parameter specifies the URL RFC3986 to which this 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.5. </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.5.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.5.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.6. </ins> Creation of resources can be rate limited by ACME servers to ensure fair usage and prevent abuse.  Once the rate limit is exceeded, the "Link" header pointing to documentation about the specific rate limit that was hit, using the "help" link relation type.  <ins> 6.7. </ins> Errors can be reported in ACME both at the HTTP layer and within challenge objects as defined in identifier-validation-challenges. example, an "error of type 'badCSR'" refers to an error document with "type" value "urn:ietf:params:acme:error:badCSR".  <ins> 6.7.1. </ins> Sometimes a CA may need to return multiple errors in response to a request.  Additionally, the CA may need to attribute errors to


identifier-validation-challenges describes a set of challenges for domain name validation.  7.2. Before sending a POST request to the server, an ACME client needs to 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 <del> different validation mechanisms. </del>  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

As suggested by Felipe Gasper
NAME fixed. Note, also standardized on "validation method" (vs. "mechanism"). Hello, I’ve been looking over the -09 draft and have created a Perl client module against Pebble as well as LE’s new testing endpoint. I’m curious about whether the specification intends to define Challenge objects. They appear to exist, of course, but they’re not defined as objects per se in section 7.1 of the draft. Thank you! -Felipe Gasper Mississauga, ON

identifier-validation-challenges describes a set of challenges for domain name validation. <ins> 7.1.5. An ACME challenge object represents a server's offer to validate a client's possession of an identifier in a specific way.  Unlike the other objects listed above, there is not a single standard structure for a challenge object.  The contents of a challenge object depend on the validation method being used.  The general structure of challenge objects and an initial set of validation methods are described in identifier-validation-challenges. </ins> 7.2. Before sending a POST request to the server, an ACME client needs to 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  <ins> different validation methods. </ins> 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


7.3.3. <del> Servers SHOULD NOT respond to GET requests for account resources as </del>  these requests are not authenticated.  If a client wishes to query the server for information about its account (e.g., to examine the "contact" or "orders" fields), then it SHOULD do so by sending a POST

Section "Request Authentication" already forbade it.
In general, we have not been making MUST-level requirements for servers in this document because CAs are subject to a lot of external constraints already. Under that theory, I would say we should just close this. NAME NAME wdyt?
If you don't want this change, can you change "Servers MUST NOT respond to GET requests for resources that might be considered sensitive. Account resources are the only sensitive resources defined in this specification." instead to resolve the inconsistency?
NAME I agree with NAME - this isn't a new MUST-level requirement, it's already said elsewhere that the server MUST NOT respond to sensitive resources and the account object has contact information you wouldn't want returned to an unauthenticated GET request. It seems fine to emphasize this in the account information section.
I'm going to merge this. NAME gives an OOB +1. Thanks NAME !

7.3.3.  <ins> Servers MUST NOT respond to GET requests for account resources as </ins> these requests are not authenticated.  If a client wishes to query the server for information about its account (e.g., to examine the "contact" or "orders" fields), then it SHOULD do so by sending a POST


ACME can also be used to automate some aspects of certificate management even where non-automated processes are still needed.  For example, the external account binding feature (see external-account- <del> binding) can be used to associate authorizations with an account that were not validated through the ACME authorization process.  This allows ACME to address issuance scenarios that cannot yet be fully automated, such as the issuance of Extended Validation certificates. </del>  2.

Merging because editorial.
account binding feature (see {{external-account-binding}}) can be used to associate authorizations with an account that were not validated through the ACME authorization process. To me (non-native English speaker) "were not" refers to "an account" which would be a grammar mistake. If it refers to "authorizations" would it be better to switch "authorizations" and "an account"?
I think it is technically correct (it does refer to "authorizations"), but I agree it's an awkward sentence. Filed to address.

ACME can also be used to automate some aspects of certificate management even where non-automated processes are still needed.  For example, the external account binding feature (see external-account-  <ins> binding) can allow an ACME account to use authorizations that have been granted to an external, non-ACME account.  This allows ACME to address issuance scenarios that cannot yet be fully automated, such as the issuance of Extended Validation certificates. </ins> 2.


JWS objects sent in ACME requests MUST meet the following additional criteria:  The JWS MUST NOT have the value "none" in its "alg" field <del> The JWS MUST NOT have multiple signatures. </del>  The JWS MUST NOT have a Message Authentication Code (MAC)-based algorithm in its "alg" field  The JWS Protected Header MUST include the following fields: "alg" (Algorithm) document returned with the error MUST include an "algorithms" field with an array of supported "alg" values. <del> 6.3. The JSON Web Signature (JWS) specification RFC7515 contains multiple JWS serialization formats.  When sending an ACME request with a non- empty body, an ACME client implementation MUST use the HTTP Content- Type RFC7231 header to indicate which JWS serialization format is used for encapsulating the ACME request payload.  The following Content-Type values may be used for this purpose: "application/jose": The JWS Compact Serialization RFC7515 MUST be used. The JWS Payload MUST NOT be detached. The JWS Unencoded Payload Option RFC7797 MUST NOT be used. "application/jose+json": Either the JWS Flattened JSON Serialization RFC7515 or the JWS General JSON Serialization RFC7515 MUST be used. The JWS Payload MUST NOT be detached. </del>  <del> The JWS Unencoded Payload Option RFC7797 MUST NOT be used. The JWS Unprotected Header RFC7515 SHOULD NOT be used. In the examples below, JWS objects are shown in the Flattened JSON serialization, with the protected header and payload expressed as base64url(content) instead of the actual base64-encoded value, so that the content is readable. 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, provided to clients and having the resource check that requests have the same string in their "url" header parameter. <del> 6.4.1. </del>  The "url" header parameter specifies the URL RFC3986 to which this 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. <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 by ACME servers to ensure fair usage and prevent abuse.  Once the rate limit is exceeded, the "Link" header pointing to documentation about the specific rate limit that was hit, using the "help" link relation type. <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. example, an "error of type 'badCSR'" refers to an error document with "type" value "urn:ietf:params:acme:error:badCSR". <del> 6.7.1. </del>  Sometimes a CA may need to return multiple errors in response to a request.  Additionally, the CA may need to attribute errors to

This is my attempt to find a quick way out of this content-type mess. Replaces and
This also looks good to me, thanks for drafting it!
+1 - This looks like a low complexity path forward that resolves ambiguity.

JWS objects sent in ACME requests MUST meet the following additional criteria: <ins> The JWS MUST be in the Flattened JSON Serialization </ins> The JWS MUST NOT have the value "none" in its "alg" field  <ins> The JWS MUST NOT have multiple signatures The JWS Unencoded Payload Option RFC7797 MUST NOT be used The JWS Unprotected Header RFC7515 MUST NOT be used </ins> The JWS MUST NOT have a Message Authentication Code (MAC)-based algorithm in its "alg" field <ins> The JWS The JWS Payload MUST NOT be detached </ins> The JWS Protected Header MUST include the following fields: "alg" (Algorithm) document returned with the error MUST include an "algorithms" field with an array of supported "alg" values.  <ins> Because client requests in ACME carry JWS objects in the Flattened JSON Serialization, they must have the "Content-Type" header field set to "application/jose+json".  If a request does not meet this requirement, then the server MUST return a response with status code 415 (Unsupported Media Type). </ins>  <ins> 6.3. </ins> It is common in deployment for the entity terminating TLS for HTTPS to be different from the entity operating the logical HTTPS server, provided to clients and having the resource check that requests have the same string in their "url" header parameter.  <ins> 6.3.1. </ins> The "url" header parameter specifies the URL RFC3986 to which this 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. </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 by ACME servers to ensure fair usage and prevent abuse.  Once the rate limit is exceeded, the "Link" header pointing to documentation about the specific rate limit that was hit, using the "help" link relation type.  <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. example, an "error of type 'badCSR'" refers to an error document with "type" value "urn:ietf:params:acme:error:badCSR".  <ins> 6.6.1. </ins> Sometimes a CA may need to return multiple errors in response to a request.  Additionally, the CA may need to attribute errors to


Subject Alternate Name Extension by RFC 5280 RFC5280.  An authorization returned by the server for a wildcard domain name identifier MUST NOT include the asterisk and full stop ("*.") prefix <del> in the authorization identifier value. </del>  The elements of the "authorizations" and "identifiers" array are immutable once set.  The server MUST NOT change the contents of For final authorizations, it contains the challenges that were successfully completed.  The only type of identifier defined by this specification is a fully- qualified domain name (type: "dns").  If a domain name contains non- ASCII Unicode characters it MUST be encoded using the rules defined in RFC3492.  Servers MUST verify any identifier values that begin with the ASCII Compatible Encoding prefix "xn--" as defined in RFC5890 are properly encoded.  Wildcard domain names (with "*" as the <del> first label) MUST NOT be included in authorization objects. </del>  identifier-validation-challenges describes a set of challenges for domain name validation.

requests are allowed to send DNS type identifiers with a value that contains a wildcard prefix ('') as the leftmost label. The authorization object created for the wildcard identifiers in the requests are not allowed to carry the wildcard prefix in the authorization identifier per spec language: This is sensible because the authorization is not for the logical wildcard but for the specific base domain. This leaves an ambiguous situation for client developers/users. Imagine a situation where a user requests a new order with the following request body: It's possible two authorizations will be created for this case, but both will contain the identifier . This can be confusing to users! (e.g. shred/acme4j) If one of the authorizations fails a challenge validation operation the client can't know whether it was the "URL" validation, or the "URL" validation that failed and won't be able to prompt the user to retry with the failed domain removed. Generally speaking it makes presenting accurate error information difficult without over-fitting Let's Encrypt's particular Wildcard issuance policies. (E.g. see discussion in URL and URL) This commit introduces an optional boolean authorization field that can be used to indicate the authorization's identifier should be considered the base domain of a wildcard identifier that was requested. This replaces , which included the baggage of .

Subject Alternate Name Extension by RFC 5280 RFC5280.  An authorization returned by the server for a wildcard domain name identifier MUST NOT include the asterisk and full stop ("*.") prefix  <ins> in the authorization identifier value.  The returned authorization MUST include the optional "wildcard" field, with a value of true. </ins> The elements of the "authorizations" and "identifiers" array are immutable once set.  The server MUST NOT change the contents of For final authorizations, it contains the challenges that were successfully completed. <ins> For authorizations created as a result of a newOrder request containing a DNS identifier with a value that contained a wildcard prefix this field MUST be present, and true. </ins> The only type of identifier defined by this specification is a fully- qualified domain name (type: "dns").  If a domain name contains non- ASCII Unicode characters it MUST be encoded using the rules defined in RFC3492.  Servers MUST verify any identifier values that begin with the ASCII Compatible Encoding prefix "xn--" as defined in RFC5890 are properly encoded.  Wildcard domain names (with "*" as the  <ins> first label) MUST NOT be included in authorization objects.  If an authorization object conveys authorization for the base domain of a newOrder DNS type identifier with a wildcard prefix then the optional authorizations "wildcard" field MUST be present with a value of true. </ins> identifier-validation-challenges describes a set of challenges for domain name validation.


a host which only functions as an ACME server could place the directory under the path "/". <del> If the ACME server does not implement pre-authorization (Section 7.4.1) it MUST omit the "newAuthz" field of the directory. </del>  The object MAY additionally contain a field "meta".  If present, it MUST be a JSON object; each field in the object is an item of request to the new-authorization resource specifying the identifier for which authorization is being requested. <del> The identifier that the account is authorized to represent: </del>  <del> The type of identifier. The identifier itself. </del>  Before processing the authorization request, the server SHOULD determine whether it is willing to issue certificates for the

Replaces
This text looks fine to me. I think there should be discussion in WGLC about this since folks that care about pre-authorization might be surprised by this new constraint.

a host which only functions as an ACME server could place the directory under the path "/".  <ins> If the ACME server does not implement pre-authorization (pre- authorization) it MUST omit the "newAuthz" field of the directory. </ins> The object MAY additionally contain a field "meta".  If present, it MUST be a JSON object; each field in the object is an item of request to the new-authorization resource specifying the identifier for which authorization is being requested.  <ins> The identifier to appear in the resulting authorization object (see authorization-objects) </ins>  <ins> Note that because the identifier in a pre-authorization request is the exact identifier to be included in the authorization object, pre- authorization cannot be used to authorize issuance with wildcard DNS identifiers. </ins> Before processing the authorization request, the server SHOULD determine whether it is willing to issue certificates for the


allows a client to look up an account URL based on an account key (see finding-an-account-url-given-a-key).  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,

1) Include optional field in the Account Creation section with a forward pointer to the external account binding section. 2) Include the mandatory "orders" field in the example new account response. 3) Correct the "orders" field type in Section 9.7.1 to match the type from 7.1.2 Thanks to NAME for flagging these issues on the WG Mailing List.

allows a client to look up an account URL based on an account key (see finding-an-account-url-given-a-key). <ins> An optional field for binding the new account with an existing non-ACME account (see external-account-binding ). </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 identifier itself. The status of this authorization.  Possible values are: "pending", <del> "valid", "invalid", "deactivated", and "revoked". </del>  The timestamp after which the server will consider this authorization invalid, encoded in the format specified in RFC 3339

1) Section 7.1.4 - Include "expires" in possible authz status values. 2) 7.1.2.1 - Fix orders link rel relation syntax Thanks to NAME for flagging these issues on-list.

The identifier itself. The status of this authorization.  Possible values are: "pending",  <ins> "valid", "invalid", "deactivated", "expired", and "revoked". </ins> The timestamp after which the server will consider this authorization invalid, encoded in the format specified in RFC 3339


extension. A request to finalize an order will result in error if the order <del> indicated does not have status "pending", if the CSR and order </del>  identifiers differ, or if the account is not authorized for the identifiers indicated in the CSR.

When the "ready" status was added to the order process we missed a place in Section 7.4 where the specification claims an order should be in status "processing" when it is ready for finalization. This commit changes this sentence to say the order is ready for finalization when it is status "ready". Thanks to NAME for flagging this issue on-list.

extension. A request to finalize an order will result in error if the order  <ins> indicated does not have status "ready", if the CSR and order </ins> identifiers differ, or if the account is not authorized for the identifiers indicated in the CSR.


because the ACME protocol itself includes anti-replay protections (see replay-protection). <del> 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 software. </del>  ACME clients SHOULD send an Accept-Language header in accordance with RFC7231 to enable localization of error messages. 11.1.  As noted above, DNS forgery attacks against the ACME server can result in the server making incorrect decisions about domain control and thus mis-issuing certificates.  Servers SHOULD perform DNS these resolvers both for both CAA record lookups and all record lookups in furtherance of a challenge scheme (A, AAAA, TXT, etc.). <del> 11.2. </del>  The http-01, and dns-01 validation methods mandate the usage of a random token value to uniquely identify the challenge.  The value of that automatically replies to challenges without participating in the creation of the initial authorization request. <del> 11.3. </del>  ACME provides certificate chains in the widely-used format known colloquially as PEM (though it may diverge from the actual Privacy

Thanks for the comments NAME I've updated the PR to address.
There has been list discussion on this PR and consensus is positive. I'm going to merge this now that NAME has addressed the feedback provided.
LGTM :rocket:

because the ACME protocol itself includes anti-replay protections (see replay-protection).  <ins> ACME clients MUST send a User-Agent header, in accordance with RFC7231.  This header SHOULD include the name and version of the ACME software in addition to the name and version of the underlying HTTP client software. </ins> ACME clients SHOULD send an Accept-Language header in accordance with RFC7231 to enable localization of error messages. 11.1. <ins> ACME relies on two different classes of key pair: Account key pairs, which are used to authenticate account holders Certificate key pairs, which are used to sign and verify CSRs (and whose public keys are included in certificates) Compromise of the private key of an account key pair has more serious consequences than compromise of a private key corresponding to a certificate.  While the compromise of a certificate key pair allows the attacker to impersonate the entities named in the certificate for the lifetime of the certificate, the compromise of an account key pair allows the attacker to take full control of the victim's ACME account, and take any action that the legitimate account holder could take within the scope of ACME: Issuing certificates using existing authorizations Revoking existing certificates Accessing and changing account information (e.g., contacts) Changing the account key pair for the account, locking out the legitimate account holder For this reason, it is RECOMMENDED that account key pairs be used for no other purpose besides ACME authentication.  For example, the public key of an account key pair SHOULD NOT be included in a certificate.  ACME clients and servers SHOULD verify that a CSR submitted in a finalize request does not contain a public key for any known account key pair.  In particular, when a server receives a finalize request, it MUST verify that the public key in a CSR is not the same as the public key of the account key pair used to authenticate that request. 11.2. </ins> As noted above, DNS forgery attacks against the ACME server can result in the server making incorrect decisions about domain control and thus mis-issuing certificates.  Servers SHOULD perform DNS these resolvers both for both CAA record lookups and all record lookups in furtherance of a challenge scheme (A, AAAA, TXT, etc.).  <ins> 11.3. </ins> The http-01, and dns-01 validation methods mandate the usage of a random token value to uniquely identify the challenge.  The value of that automatically replies to challenges without participating in the creation of the initial authorization request.  <ins> 11.4. </ins> ACME provides certificate chains in the widely-used format known colloquially as PEM (though it may diverge from the actual Privacy


For pending orders, the authorizations that the client needs to complete before the requested certificate can be issued (see <del> identifier-authorization).  For final orders (in the "valid" or "invalid" state), the authorizations that were completed.  Each entry is a URL from which an authorization can be fetched with a GET request. </del>  A URL that a CSR must be POSTed to once all of the order's authorizations are satisfied to finalize the order.  The result of (see identifier-authorization).  If the client fails to complete the required actions before the "expires" time, then the server SHOULD change the status of the order to "invalid" and MAY delete the order <del> resource. </del>  Once the client believes it has fulfilled the server's requirements, it should send a POST request to the order resource's finalize URL.

This PR clarifies that a client SHOULD NOT assume that the "identifiers", "authorizations" or "challenges" arrays returned in various server response objects are sorted. This PR also clarifies that while some have a 1:1 relationship between order identifiers and order authorizations this isn't a universal truth. This resolves URL
NAME Is 6 days without any feedback on-list sufficient to merge?
On the reuqest, there are two arrays returned, one for the and one for the . However, there is no order specified in ACMEv2. As two arrays are returned (and no hash), this might imply that the order of matches the order of . This is not specified right now. Having this specified would allow clients to know in advance for which identity they are requesting the authorization challenge before requesting the URL, e.g. for better error reporting. Also ok would be to just explicitly specify that the order is not guaranteed or the number of entries is not guaranteed to match in order to make it more clear to developers. cf. URL
From the outcome of the linked conversation, we should just specify that no specific order is guaranteed.
:+1: - URL I will start a mailing list thread since this is a new SHOULD NOT.
Looks good to me; let's wait a little bit for feedback on-list.

For pending orders, the authorizations that the client needs to complete before the requested certificate can be issued (see  <ins> identifier-authorization).  The authorizations required are dictated by server policy and there may not be a 1:1 relationship between the order identifiers and the authorizations required. For final orders (in the "valid" or "invalid" state), the authorizations that were completed.  Each entry is a URL from which an authorization can be fetched with a GET request. </ins> A URL that a CSR must be POSTed to once all of the order's authorizations are satisfied to finalize the order.  The result of (see identifier-authorization).  If the client fails to complete the required actions before the "expires" time, then the server SHOULD change the status of the order to "invalid" and MAY delete the order  <ins> resource.  Clients SHOULD NOT make any assumptions about the sort order of "identifiers" or "authorizations" elements in the returned order object. </ins> Once the client believes it has fulfilled the server's requirements, it should send a POST request to the order resource's finalize URL.


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. <del> For final authorizations, it contains the challenges that were successfully completed. </del> For authorizations created as a result of a newOrder request containing a DNS identifier with a value that contained a wildcard

In section 7.1.4 "Authorization Objects" the "challenges" field is described as containing: Later, after discussing the array entries a duplicate sentence appears: This is already covered by the initial description of what a final authorization's challenges array holds and so this commit removes the second redundant sentence.

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 authorizations created as a result of a newOrder request containing a DNS identifier with a value that contained a wildcard


ACME Order Object Fields (iana-order)  ACME Error Types (iana-error) ACME Resource Types (iana-resource)

Section 9.7 "New Registries" itemizes the subsections that include new IANA registries. We added a subsection for "Authorization Object Fields" but forgot to add a link to it from the top level 9.7 text. This commit adds that forward pointer.

ACME Order Object Fields (iana-order) <ins> ACME Authorization Object Fields (iana-authz) </ins> ACME Error Types (iana-error) ACME Resource Types (iana-resource)


associate an ACME account with an existing account in a non-ACME system, such as a CA customer database. <del> To enable ACME account binding, a CA needs to provide the ACME client with a MAC key and a key identifier, using some mechanism outside of ACME.  The key identifier MUST be an ASCII string.  The MAC key SHOULD be provided in base64url-encoded form, to maximize compatibility between non-ACME provisioning systems and ACME clients. </del>  The ACME client then computes a binding JWS to indicate the external account holder's approval of the ACME account key.  The payload of File contains one or more certificates encoded with the PEM textual encoding, according to RFC 7468 RFC7468.  In order to provide easy interoperation with TLS, the first certificate MUST be an end-entity <del> certificate.  Each following certificate SHOULD directly certify one preceding it.  Because certificate validation requires that trust </del>  anchors be distributed independently, a certificate that specifies a trust anchor MAY be omitted from the chain, provided that supported peers are known to possess any omitted certificates.

A few editorial things that Dale found.
Editorial diffs only. Merging as-is. Thanks NAME !
:shipit:

associate an ACME account with an existing account in a non-ACME system, such as a CA customer database.  <ins> To enable ACME account binding, the CA operating the ACME server needs to provide the ACME client with a MAC key and a key identifier, using some mechanism outside of ACME.  The key identifier MUST be an ASCII string.  The MAC key SHOULD be provided in base64url-encoded form, to maximize compatibility between non-ACME provisioning systems and ACME clients. </ins> The ACME client then computes a binding JWS to indicate the external account holder's approval of the ACME account key.  The payload of File contains one or more certificates encoded with the PEM textual encoding, according to RFC 7468 RFC7468.  In order to provide easy interoperation with TLS, the first certificate MUST be an end-entity  <ins> certificate.  Each following certificate SHOULD directly certify the one preceding it.  Because certificate validation requires that trust </ins> anchors be distributed independently, a certificate that specifies a trust anchor MAY be omitted from the chain, provided that supported peers are known to possess any omitted certificates.


"alg" (Algorithm) "jwk" (JSON Web Key, for all requests not signed using an <del> existing account, e.g. newAccount) </del>  "kid" (Key ID, for all requests signed using an existing account)

Thanks to NAME .
Thanks NAME Merging with one review as this is strictly editorial. I’m not sure what the best forum is to report minor typographical issues, but: : "jwk" (JSON Web Key, for all requests not signed using an existing account, e.g. newAccount) ^^ Everyplace else in the spec puts a comma after “e.g.”, so I would think there should be one here as well. -Felipe Gasper

"alg" (Algorithm) "jwk" (JSON Web Key, for all requests not signed using an  <ins> existing account, e.g., newAccount) </ins> "kid" (Key ID, for all requests signed using an existing account)


Either "jwk" (JSON Web Key) or "kid" (Key ID) as specified below  The "jwk" and "kid" fields are mutually exclusive.  Servers MUST reject requests that contain both.

As proposed in EKR's AD review, discussed on-list and at IETF 102.
Of course, this needs WG consensus first.
Yes NAME just posting this so we can be concrete about the discussion in the meeting.
Merging this on AD+chair guidance guidance that we can

Either "jwk" (JSON Web Key) or "kid" (Key ID) as specified below <ins> An ACME server MUST implement the "ES256" signature algorithm RFC7518 and SHOULD implement the "EdDSA" signature algorithm using the "Ed25519" variant (indicated by "crv") RFC8037. </ins> The "jwk" and "kid" fields are mutually exclusive.  Servers MUST reject requests that contain both.


request is signed with the private key corresponding to the "key" field of the request before updating the registration.  Servers SHOULD NOT respond to GET requests for registration resources as these requests are not authenticated.  If a client wishes to query the server for information about its account (e.g., to examine the Verify that the resulting URI is well-formed. <del> Dereference the URI using an HTTP or HTTPS GET request.  If using HTTPS, the ACME server MUST ignore the certificate provided by the HTTPS server. </del>  Verify that the body of the response is well-formed key authorization.  The server SHOULD ignore whitespace characters at

vs. The spec doesn't seem to be consistent. And why does it have to be completed with HTTP? I honestly don't understand that.
LE's seems to give a choice. I'd really prefer that. This would make it possible to not even listen on port 80 for things like APIs, e.g. GitHub does that on .
As discussed on the list and in the document, the HTTP challenge needs to be HTTP-only in order to avoid the default-vhost issues. Thanks for catching the stray HTTPS text. I will remove it.
Do you have a link to the discussion?
See URL Is that example just bogus or what's the for? There are only two challenges, so it can't be an index there.
Good point. Left over from when we had three challenges in the example.
Contact information may have been misspelled during registration. Contact information such as phone numbers may also change. https://acme-URL exposes only the endpoint and that endpoint doesn't accept updates, because it has to respond with 409 Conflict for already existing keys. There should be a way to update that information. See also URL
thanks NAME yes updating the contact email for registered LE account is a must have feature otherwise an LE notifications/renew notices may end up going to invalid email addresses.
Right now, the spec says that you can update anything in the registration with a : Note that the request goes to the registration URL, not the new-registration URL. I'll add an example to the document to clarify.

request is signed with the private key corresponding to the "key" field of the request before updating the registration. <ins> For example, to update the contact information in the above registration, the client could send the following request: </ins> Servers SHOULD NOT respond to GET requests for registration resources as these requests are not authenticated.  If a client wishes to query the server for information about its account (e.g., to examine the Verify that the resulting URI is well-formed.  <ins> Dereference the URI using an HTTP GET request. </ins> Verify that the body of the response is well-formed key authorization.  The server SHOULD ignore whitespace characters at


If the client sends a JWS signed with an algorithm that the server does not support, then the server MUST return an error with status code 400 (Bad Request) and type <del> "urn:ietf:params:acme:error:badSignatureAlgorithm" (see errors).  The problem document returned with the error MUST include an "algorithms" field with an array of supported "alg" values. </del>  Because client requests in ACME carry JWS objects in the Flattened JSON Serialization, they must have the "Content-Type" header field The server granted the client authorization based on an external account <del> Clients should check the "status" field of an order to determine </del>  whether they need to take any action. 7.1.4. Validation responses need to be bound to an account key pair in order to avoid situations where a MitM on ACME HTTPS requests can switch <del> out a legitimate domain holder's account key for one of his choosing, e.g.: </del>  Legitimate domain holder registers account key pair A B (the MitM) instead of account key A (the legitimate domain holder) <del> 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 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. </del>  The association of challenges to identifiers is typically done by requiring the client to perform some action that only someone who

EKR pointed out to me privately a couple of remaining issues after his AD review. This PR addresses those issues.
No complaints from me, looks good. Thanks NAME

If the client sends a JWS signed with an algorithm that the server does not support, then the server MUST return an error with status code 400 (Bad Request) and type  <ins> "urn:ietf:params:acme:error:badSignatureAlgorithm".  The problem document returned with the error MUST include an "algorithms" field with an array of supported "alg" values.  See errors for more details on the structure of error responses. </ins> Because client requests in ACME carry JWS objects in the Flattened JSON Serialization, they must have the "Content-Type" header field The server granted the client authorization based on an external account  <ins> Clients SHOULD check the "status" field of an order to determine </ins> whether they need to take any action. 7.1.4. Validation responses need to be bound to an account key pair in order to avoid situations where a MitM on ACME HTTPS requests can switch  <ins> out a legitimate domain holder's account key for one of his choosing. Such MitMs can arise, for example, if a CA uses a CDN or third-party reverse proxy in front of its ACME interface.  An attack by such an MitM could have the following form: </ins> Legitimate domain holder registers account key pair A B (the MitM) instead of account key A (the legitimate domain holder)  <ins> All of the challenges defined in this document have a binding between the account private key and the validation query made by the server, via the key 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


2. The guiding use case for ACME is obtaining certificates for websites <del> (HTTPS RFC2818).  In this case, the user's web server is intended to speak for one or more domains, and the process of certificate issuance is intended to verify that this web 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 In most HTTPS transactions used by ACME, the ACME client is the HTTPS client and the ACME server is the HTTPS server.  The ACME server acts <del> as an HTTP and HTTPS client when validating challenges via HTTP. </del>  ACME servers SHOULD follow the recommendations of RFC7525 when configuring their TLS implementations.  ACME servers that support TLS 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 can be accessed in the "termsOfService" subfield of the "meta" field in the directory object, and the server MUST reject new-account requests that do not have the "termsOfServiceAgreed" field set to "true".  Clients SHOULD NOT automatically agree to terms by default. Rather, they SHOULD require some user interaction for agreement to terms. </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 The inner JWS MUST have the same "url" header parameter as the outer JWS. <del> The inner JWS is NOT REQUIRED to have a "nonce" header parameter. The server MUST ignore any value provided for the "nonce" header parameter. </del>  This transaction has signatures from both the old and new keys so that the server can verify that the holders of the two keys both successful.  If the request fails, or the body does not pass these checks, then it has failed.  8.4. When the identifier being validated is a domain name, the client can 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. validation response for his own account key.  The risks due to hosting providers noted above are a particular case. <del> It is RECOMMENDED that the server perform DNS queries and make HTTP connections from various network perspectives, in order to make MitM attacks harder. </del>  10.3.

URL URL
Looks good to me. I didn't necessarily expect the bit about de-provisioning a challenge response to need a SHOULD, but I don't object.
Thanks NAME With approval from co-author, chair, and AD, I guess it's safe to merge :)
So the de-provision isn't just editorial, but it is only a SHOULD. All of these look fine to me. LGTM :rocket: Thanks NAME Ben Campbell has entered the following ballot position for draft-ietf-acme-acme-14: Yes When responding, please keep the subject line intact and reply to all email addresses included in the To and CC lines. (Feel free to cut this introductory paragraph, however.) Please refer to URL for more information about IESG DISCUSS and COMMENT positions. The document, along with other ballot positions, can be found here: URL COMMENT: Thanks for the work on this; I'm happy to see it nearing completion. I have a few minor comments: Substantive : "The ACME server acts as an HTTP and HTTPS client when validating challenges via HTTP." Section 8.3 says that HTTP challenge validation cannot use HTTPS. Also, §6 says that all interactions between the client and server use HTTPS. I recognize challenge validation is not really an interaction between the client and server, but I suspect some readers may be confused. "ACME servers SHOULD follow the recommendations of [RFC7525] when configuring their TLS implementations." Why not MUST? : "... and the server MUST reject new-account requests that do not have the "termsOfServiceAgreed" field set to "true". " The MUST seems overly strong there; is there no room for local policy? Would it be completely insane to offer optional ToS? (For example, maybe one gets some additional service for agreeing to terms, but still gets a cert either way.) "Clients SHOULD NOT automatically agree to terms by default." Why not MUST NOT? : Is there a lifetime after which a provisioned HTTP resource in response to a challenge should go away? Editorial and Nits , first paragraph: Is the "user" the person requesting services from the ACME server? : " It is RECOMMENDED that the server perform DNS queries and make HTTP connections from various network perspectives..." : " The inner JWS is NOT REQUIRED to have a "nonce" header parameter." "NOT REQUIRED" is not among the terms defined by 2119/8174. I suspect this is intended as a statement of fact, and should therefore not be capitalized. I'm not sure what that means. Given that this uses an upper-case RECOMMENDED, can it be stated more concretely? : Is this section also to be removed? Thanks for the work on this; I'm happy to see it nearing completion. I have a few minor comments:Section 8.3 says that HTTP challenge validation cannot use HTTPS. Also, §6 says that all interactions between the client and server use HTTPS. I recognize challenge validation is not really an interaction between the client and server, but I suspect some readers may be confused. Why not MUST? The MUST seems overly strong there; is there no room for local policy? Would it be completely insane to offer optional ToS? (For example, maybe one gets some additional service for agreeing to terms, but still gets a cert either way.) Why not MUST NOT? §2, first paragraph: Is the "user" the person requesting services from the ACME server? "NOT REQUIRED" is not among the terms defined by 2119/8174. I suspect this is intended as a statement of fact, and should therefore not be capitalized. I'm not sure what that means. Given that this uses an upper-case RECOMMENDED, can it be stated more concretely? §13.3: Is this section also to be removed?

2. The guiding use case for ACME is obtaining certificates for websites  <ins> (HTTPS RFC2818).  In this case, a web server is intended to speak for one or more domains, and the process of certificate 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 In most HTTPS transactions used by ACME, the ACME client is the HTTPS client and the ACME server is the HTTPS server.  The ACME server acts  <ins> as a client when validating challenges: an HTTP client when validating an 'http-01' challenge, a DNS client with 'dns-01', etc. </ins> ACME servers SHOULD follow the recommendations of RFC7525 when configuring their TLS implementations.  ACME servers that support TLS using a supported scheme but an invalid value then the server MUST return an error of type "invalidContact".  <ins> If the server wishes to require the client to agree to terms under which the ACME service is to be used, it MUST indicate the URL where such terms can be accessed in the "termsOfService" subfield of the "meta" field in the directory object, and the server MUST reject new- account requests that do not have the "termsOfServiceAgreed" field set to "true".  Clients SHOULD NOT automatically agree to terms by default.  Rather, they SHOULD require some user interaction for agreement to terms. </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 The inner JWS MUST have the same "url" header parameter as the outer JWS.  <ins> The inner JWS MAY omit the "nonce" header parameter.  The server MUST ignore any value provided for the "nonce" header parameter. </ins> This transaction has signatures from both the old and new keys so that the server can verify that the holders of the two keys both successful.  If the request fails, or the body does not pass these checks, then it has failed. <ins> The client SHOULD de-provision the resource provisioned for this challenge once the challenge is complete, i.e., once the "status" field of the challenge has the value "valid" or "invalid". </ins> 8.4. When the identifier being validated is a domain name, the client can successful.  If no DNS record is found, or DNS record and response payload do not pass these checks, then the validation fails. <ins> The client SHOULD de-provision the resource record(s) provisioned for this challenge once the challenge is complete, i.e., once the "status" field of the challenge has the value "valid" or "invalid". </ins> 9. 9.1. validation response for his own account key.  The risks due to hosting providers noted above are a particular case.  <ins> Attackers can also exploit vulnerabilities in Internet routing protocols to gain access to the validation channel (see, e.g., RFC7132).  In order to make such attacks more difficult, it is RECOMMENDED that the server perform DNS queries and make HTTP connections from multiple points in the network.  Since routing attacks are often localized or dependent on the position of the attacker, forcing the attacker to attack multiple points (the server's validation vantage points) or a specific point (the DNS / HTTP server) makes it more difficult to subvert ACME validation using attacks on routing. </ins> 10.3.