Draft: draft-ietf-acme-acme

Commentary: Trivial wordsmith suggestions . LGTM . Thanks Looks good to me . I 'll be proposing some additional text for section 5 .
Mailing list commentary: has entered the following ballot position for draft - ietf - acme - acme-14 : Discuss 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 for more information about IESG DISCUSS and COMMENT positions . The document , along with other ballot positions , can be found here : DISCUSS : This is a great thing to have , and I intend to eventually ballot Yes , but I do have some questions that may require further discussion before this document is approved . It looks like the server returns an unauthenticated " badSignatureAlgorithm " error when the client sends a JWS using an unsupported signature algorithm ( Section 6.2 ) . What prevents an active attacker from performing a downgrade attack on the signature algorithm used ? Similarly , since we include in the threat model a potentially hostile CDN / MitM between the ACME client and ACME server , can that attacker strip a success response and replace it with a badNonce error , causing the client to retry ( and thus duplicate the request processing on the server ) ? I am not an ART AD , but there is not yet an internationalization directorate , and seeing statements like " inputs for digest computations MUST be encoded using the UTF-8 character set " ( Section 5 ) without additional discussion of normalization and/or what the canonical form for the digest input is makes me nervous . Has sufficient internationalization review been performed to ensure that there are no latent issues in this space ? Section 6.1 has text discussing TLS 1.3 's 0 - RTT mode . If this text is intended to be a profile that defines / allows the use of TLS 1.3 0 - RTT data for the ACME protocol , I think you need to be more specific and say something like " MAY allow clients to send early data ( 0 - RTT ) ; there are no ACME - specific restrictions on which types of requests are permitted in 0 - RTT " , since the runtime configuration is just 0 - RTT yes / no , and the protocol spec is in charge of saying which PDUs are allowed or not . Section 6.2 notes that servers MUST NOT respond to GET requests for sensitvie resources . Why are account resources the only sensitive ones ? Are authorizations not sensitive ? Or are those considered to fall under the umbrella of " account resources " ( Section 7.1 seems pretty clear that they do not ) ? Section 7.1.1 discusses how the server can include a caaIdentities element in its directory metadata ; does this ( or anything else ) need to be integrity protected by anything stronger than the Web PKI cert authenticating the HTTPS connection ? It seems that a bogus caaIdentities value could lead to an unfortunate DoS in some cases . I am also a bit uncertain if the document is internally consistent about whether one challenge verification suffices or there can be cases when multiple challenge verifications are required for a successful authorization . I attmpted to note relevant snippets of the text in my comments on Section 7.1.4 . I also have some important substantive comments in the section - by - section COMMENTS , since they would not in and of themselves block publication . COMMENT : This document was quite easy to read -- thank you for the clear prose and document structure ! It did leave me with some questions as to whether there are missing clarifications , though , so there are a pile of notes in the section - by - section comments below . It seems natural to feel some unease when the concept of automated certificate issuance like this comes up . As far as I can tell , though , the only substantive difference between this flow and the flow it 's replacing is that this one qualitatively feels like it weakens the " know your customer " aspect for the CA -- with current / legacy methods registering for an account can be slow and involves real - world information . Such can be spoofed / forged , of course , but ACME seems to be weakening some aspect by automating it . Given the spoofability , though , this weakening does not seem to be a particular concern with the document . I was going to suggest mentioning the potential for future work in doing time - delayed or periodic revalidation or other schemes to look at the stability of the way that identifiers / challenges were validated , but I see that discussion has already happened . It 's probably worth going over the examples and checking whether nonce values are repeated in ways that are inconsistent with expected usage . For example , I see these three values appearing multiple times ( but I did not cross - check if a nonce returned in the Replay - Nonce response header was then used in a JWS header attribute ): 2 K60BWPrMQG9SDxBDSxtSw 3 IXVHDyxIRGcTE0VSblhPzw 4 JHb54aTKTXBWQOzGYkt9A Perhaps the examples could be offset by a description of what they are ? ( They would probably also benefit from a disclaimer that the whitespace in the is for ease of reading only . ) Section - by - section comments follow . Abstract ( also Introduction ) If I read " authentication of domain names " with no context , I would be more likely to think of the sort of challenge / authorization process that this document describes , than I would be to think of using an X.509 certificate to authenticate myself as being the owner of a given domain name . But it 's unclear whether there 's an alternative phrasing that would be better . Section 1 Different types of certificates reflect different kinds of CA verification of information about the certificate subject . " Domain Validation " ( DV ) certificates are by far the most common type . The only validation the CA is required to perform in the DV issuance process is to verify that the requester has effective control of the domain . Can we get an ( informative ) ref for the " required"/requirements ? Section 6.1 W3C.CR - cors-2013 - 0129 shows up as " outdated " when I follow the link . Section 6.2 IMPORTANT : The JSON Web Signature and Encryption Algorithms registry does not appear to include an explicit indicator of whether an algorithm is MAC - based ; do we need to include text on how to make such a determination ? Section 6.3 For servers following the " SHOULD ... string equality check " and for requests where the equality check fails , does that fall into the " MUST reject the request as unauthorized " bucket ? Section 6.4 In order to protect ACME resources from any possible replay attacks , ACME requests have a mandatory anti - replay mechanism . We do n't seem to actually define what an " ACME request " is that I can see . say , newNonce , but I wonder if some clarification would be useful . IMPORTANT : How tightly are these nonces scoped ? Are they only good on a specific TLS connection ? Bound to an account key pair ? Globally valid ? ( This is not a DISCUSS point because AFAICT there is no loss in security if the nonce space is global to the server . ) Section 6.6 IMPORTANT : Providing an accountDoesNotExist error type probably means we need to give guidance that the server should choose account URLs in a non - guessable way , to avoid account enumeration attacks . [ ... ] Servers MUST NOT use the ACME URN namespace Section 9.6 for errors other than the standard types . " standard " as determined by inclusion in this document , or in the IANA registry ? Section 7.1 The " up " link relation for going from certificate to chain seems to only be needed for alternate content types that can only represent a single certificate . ( Also , the " alternate " link relation is used to provide alternate certifciation chains . ) Could this text be made more clear ? Presumably this is just my confusion , but what does " GET order certificate " mean ? Section 7.1.1 [ ... ] It is a JSON object , whose field names are drawn from the following table and whose values are the corresponding URLs . Er , from the IANA registry , right ? The following metadata items are defined , all of which are OPTIONAL : Maybe also refer to the registry ? Section 7.1.2 IMPORTANT : I ' m unclear if the " contact " is supposed to be a " talk to a human " thing or not . If there are supposed to be different URLs that are used for different purposes , would n't more metadata be needed about them ? So it seems most likely that this is indeed " talk to a human " , in which case that might be worth mentioning . ( Are these always going to be mailto : ? ) Section 7.1.2.1 IMPORTANT : Am I reading this correctly that the GET to the orders URL does not require the client to be authenticated , in effect relying on security - through - obscurity ( of the account URL ) for indicating which account is trying to order certificates for which identifiers ? Section 7.1.4 challenges ( required , array of objects ): For pending authorizations , the challenges that the client can fulfill in order to prove possession of the identifier . For final authorizations ( in the " valid " or " invalid " state ) , the challenges that were used . Each array entry is an object with parameters required to validate the challenge . A client should attempt to fulfill one of these challenges , and a server should consider any one of the challenges sufficient to make the authorization valid . This leaves me slightly confused . A final authorization can have multiple challenges . But a client should only attempt to fulfill one , and a server should treat any one as sufficient . So I can only get to the case with multiple challenges present in a final order of both " should"s are violated ? Is there a way for the server to express that multiple challenges are going to be required ? , but Section 7.1.6 's flow chart for Authorization objects says that a single challenge 's transition to valid also makes the authorization transition to valid , which would seem to close the window ? Section 7.5.1 has inline text that implicitly assumes that only one challenge will be completed / validated . wildcard ( optional , boolean ): 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 . Is there a difference between false and absent ? Section 7.3 A client creates a new account with the server by sending a POST request to the server 's new - account URL . The body of the request is a stub account object optionally containing the " contact " and " termsOfServiceAgreed " fields . Given that we go on to describe those two and also the optional onlyReturnExisting and externalAccountBinding fields , does this list need expanding ? IMPORTANT : How does the client know if a termsOfService in the directory is actually required or just optional ? ( There does n't seem to be a dedicated error type for this ? ) The text as - is seems to only say that if the server requires it , the field must be present in the directory , but not the other way around . I guess Section 7.3.4 describes the procedure for a similar case ; should the same thing happen for the original terms acceptance ? IMPORTANT : The example response uses what appears to be a sequential counter for account ID in the returned account URL , which loses any sort of security - through - obscurity protections if those were desired . Should a more opaque URL component be present , maybe a UUID ? ( The " orders " field would need to be modified accordingly , of course , and this pattern appears in later examples , as well . ) Section 7.3.2 It 's a little unclear to me whether the fields the client can put in the POST are the ones listed from Section 7.3 or 7.1.2 , or the full set from the registry . But presumably the server must ignore the " status " field , too , or at least some values should be disallowed ! The IANA registry 's " configurable " column may not quite be the right thing for this usage , especially given how account deactivation works . Section 7.3.5 The server MAY require a value for the " externalAccountBinding " field to be present in " newAccount " requests . All requests including queries for the current status and modification of existing accounts ? Or just creation of new ones ? 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 . This key needs to also be tied to the external account in question , right ? One might even say that it is provided not to the ACME client , but to the external account holder , who is also running an ACME client . [ ... ] The payload of this  is the account key being registered , in JWK form . This is presumably my fault and not the document 's , but I had to read this a few time to bind it as the ACME account key , and not the external MAC key . If a CA requires that new - account requests contain an " externalAccountBinding " field , then it MUST provide the value " true " in the " externalAccountRequired " subfield of the " meta " field in the directory object . If the CA receives a new - account request without [ ... ] nit : maybe " If such a CA " ? IMPORTANT : I do n't think I understand why " nonce " MUST NOT be present in the external - binding JWS object , though I think I understand why one is not needed in order to bind the MAC to the current transaction . ( That is , this is in effect a " triply nested " construct , where a standalone MAC that certifies an ACME account ( public ) key as being authorized by the external - account holder to act on behal of that external account . But this standalone MAC will only be accepted by the ACME server in the context of the outer JWS POST , that must be signed by the ACME account key , which is assumed to be kept secure by the ACME client , ensuring that both key - holding entities agree to the account linkage . ) Proof of freshness of the commitment from the external account holder to authorize the ACME account key would only be needed if there was a scenario where the external account holder would revoke that association , which does not seem to be a workflow supported by this document . Any need to effectuate such a revocation seems like it would involve issuing a new MAC key for the external account ( and invalidating the old one ) , and revoking / deactivating the ACME account , which is a somewhat heavy hammer but perhaps reasonable for such a scenario . Account key rollover just says that the nonce is NOT REQUIRED , and also uses some nicer ( to me ) language about " outer " and " inner " . It might be nice to synchronize these two sections . Section 7.3.7 IMPORTANT : The " url " in this example looks like an account URL , not an account - deactivation url . If they are one and the same , please include some body text to this effect as is done for account update in Section 7.3.2 . Section 7.4 Is Section 7.1.3 or the registry a better reference for the request payload 's fields ? Does the exact - match policy ( e.g. , on notBefore and notAfter ) result in CA maximum lifetime policies needing to be hardcoded in client software ( as opposed to being discoverable at runtime ) ? ( I like the order url in the example , " [ ... ] /order / asdf " . Not much entropy though . ) IMPORTANT : Why does the example response include an identifier of that was not in the request ? Is the " order 's requested identifiers appear in commonName or subjectAltName " requirement an exclusive or ? After a valid request to finalize has been issued , are " pending " or " ready " still valid statuses that could be returned for that order ? Section 7.4.1 Elsewhere when we list " identifier ( required , object ) " in a JWS payload we also inline the " type " and " value " breakdown of the object . How is " expires " set for this pre - authorization object ? We probably need a reference for " certificate chain as defined in TLS " . Section 7.5 " When a client receives an order from the server " is a bit jarring without some additional context of " in a reply to a new - order request " or " an order object " or similar . Section 7.5.1 To do this , the client updates the authorization object received from the server by filling in any required information in the elements of the " challenges " dictionary . " challenges " looks like an array of objects , not directly a dictionary with elements within it . Section 8 IMPORTANT : What do I do if I get a challenge object that has status " valid " but also includes an " error " field ? Section 8.1 [ ... ] A key authorization is a string that expresses a domain holder 's authorization for a specified key to satisfy a specified challenge , [ ... ] I ' m going to quibble with the language here and say that the keyAuthorization string as defined does not express a specific authorization for a specific challenge , since there is no signature involved , and the JWK thumbprint is separable and can be attached to some other token . ( This may just be an editorial matter with no broader impact , depending on how it 's used . ) One could perhaps argue that the mere existence of the token constitutes an authorization for a specified key to satisfy the challenge , since the token only gets generated upon receipt of such an authorized request . Section 8.3 I ' m not sure that 4086 is a great cite , here . For example , in RFC 8446 we say that " TLS requires a [ CSPRNG ] . In most case , the operating system provides an appropriate facility [ ... ] Should these prove unsatisfactory , [ RFC4086 ] provides guidance on the generation of random values . " On the other hand , citing 4086 like this is not wrong , so use your judgment . 4 . Verify that the body of the response is well - formed key authorization . The server SHOULD ignore whitespace characters at the end of the body . nit : " a well - formed " Can we get some justification for the " SHOULD follow redirects " , given the security considerations surrounding doing so ? Section 8.4 Should this " token " description include the same text about entropy as for the HTTP challenge ? Section 9.7.1 There is perhaps some subtlety here , in that the " configurable " column applies only to the new - account request , but its description in the template does not reflect that restriction . In particular , " status " values from the client are accepted when posted to the account URL , e.g. , for account deactivation . Section 10.1 Can there be overlap between the " validation server " function and the " ACME client " function ? Section 10.2 [ ... ] 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 . I ' m stumbling up around the comma trying to parse this sentence . ( Maybe a serial comma or using " and is signed " would help ? ) IMPORTANT : Also , I do n't see where the key authorization is signed in the challenge response -- the payload is just an empty object for both the HTTP and DNS challenges ' responses . Some of this text sounds like we 're implicitly placing requirements on all ( HTTP|DNS ) server operators ( not just ones trying to use ACME ) to mitgate the risks being described . In general this sort of behavior seems like an anti - design - pattern , though perhaps one could argue that the behaviors in question should be avoided in general , indepnedent of ACME . Section 10.4 Some server implementations include information from the validation server 's response ( in order to facilitate debugging ) . Such Disambiguating " ACME server implementations " may help , since we talk about other HTTP requests in the previous paragraph . Section 11.1 IMPORTANT : This may be an appropriate place to recommend against reuse of account keys , whether after an account gets deactivated or by cycling through keys in a sequence of key - change operations ( or otherwise ) . I think there are some attack scenarios possible wherein ( inner ) objects could be replayed against a different account , if such key reuse occurs . Section 11.3 The http-01 , and dns-01 validation methods mandate the usage of a nit : spurious comma . [ ... ] 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 . IMPORTANT : I ' m not sure I see how this applies to the HTTP mechanism -- could n't you write a script to reply to .well - known / acme - challenge/ with . for a fixed key thumbprint ? The validation server would ned to know about the ACME account in question , but not about any individual authorization request .
Paragraph (version A):
These intermediaries can also change values in the request that are
not signed in the HTTPS request, e.g., the request URL and headers.
ACME uses JWS to provide an integrity mechanism, which protects
against an intermediary changing the request URL to another ACME URL.
Paragraph (version B):
These intermediaries can also change values in the request that are
not signed in the HTTPS request, e.g., the request URL and header
fields.  ACME uses JWS to provide an integrity mechanism, which
protects against an intermediary changing the request URL to another
ACME URL.
Paragraph (version A):
The "Replay-Nonce" header field includes a server-generated value
that the server can use to detect unauthorized replay in future
client requests.  The server MUST generate the value provided in
Replay-Nonce in such a way that they are unique to each message, with
high probability.  For instance, it is acceptable to generate Replay-
Nonces randomly.
Paragraph (version B):
The "Replay-Nonce" header field includes a server-generated value
that the server can use to detect unauthorized replay in future
client requests.  The server MUST generate the value provided in
Replay-Nonce in such a way that they are unique to each message, with
high probability, and unpredictable to anyone besides the server.
For instance, it is acceptable to generate Replay-Nonces randomly.
Paragraph (version A):
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
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.
Paragraph (version B):
The only type of identifier defined by this specification is a fully-
qualified domain name (type: "dns").  The domain name MUST be encoded
in the form in which it would apper in a certificate.  That is, it
MUST be encoded according to the rules in Section 7 of RFC5280.
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 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.
Paragraph (version A):
When a client receives an order from the server it downloads the
authorization resources by sending GET requests to the indicated
URLs.  If the client initiates authorization using a request to the
new authorization resource, it will have already received the pending
authorization object in the response to that request.
Paragraph (version B):
When a client receives an order from the server, it downloads the
authorization resources by sending GET requests to the indicated
URLs.  If the client initiates authorization using a request to the
new authorization resource, it will have already received the pending
authorization object in the response to that request.
Paragraph (version A):
The "JWK_Thumbprint" step indicates the computation specified in
RFC7638, using the SHA-256 digest FIPS180-4.  As noted in RFC7518 any
prepended zero octets in the fields of a JWK object MUST be stripped
before doing the computation.
Paragraph (version B):
The "Thumbprint" step indicates the computation specified in RFC7638,
using the SHA-256 digest FIPS180-4.  As noted in RFC7518 any
prepended zero octets in the fields of a JWK object MUST be stripped
before doing the computation.