Draft: draft-ietf-acme-acme

Commentary: Using camelCase like suggested . There does not seem to be standard among RFCs containing  . JWE uses snake_case , but I do n't see a reason why the payload should use the same convention . Renamed sub - problems to subproblems since this spelling seems to be more common . Only changed the parts which refer to the keys . Phrases like " new - account request " are unchanged . Changes done via a script . I can resubmit the PR with a different convention if required . 
 Would you mind running your script again ? I think this is ready to merge , but needs some updates to account for the changes in ( sorry for adding conflicts ! ) 
 Master is merged now . I noted one more small inconsistency : Order objects have authorizations , finalizeURL , and certificate as keys that refer to URL(s ) . Would n't it be more consistent to drop the URL from finalizeURL ? Sorry for the pedantry . 
 I do n't have strong opinions on that one way or the other :-) 
 Big : +1 : on " finalizeURL " -"finalize " I 'll wait for you to make that change , then merge 
 done 
 I just wanted to chime in as a client developer and say that I prefer this approach to as well . As pointed out above , this change is limited to the directory endpoint and the rest is in parts of the spec that I think most ACME software has n't implemented yet . In , the changes affect more pieces of existing functionality such as key authorizations and the new key field for accounts . I think this PR makes it easier for implementations to keep compatibility with new and old ACME software while everyone transitions and allows for more reuse of existing implementations . 
 LGTM . The only quibble I might have is with " subproblems " . I understand the logic here , but it just looks a little ugly to me . wdyt?I think this is the better alternative compared to . Thanks for fixing these inconsistencies The diffs in this PR are primarily concentrated in the directory endpoint names which should be a fairly low - impact change for existing client / server codebases . The other non - directory field names that change are mostly scattered through parts of the spec that do n't have considerable penetration in the existing client / server space ( e.g. the new terms - of - service - agreed check , sub - problems , external - account - binding , etc ) . I suspect the alternative PR that switches everything to snake - case will be more work to adopt across the existing ACME ecosystem .
Paragraph (version A):
Sometimes a CA may need to return multiple errors in response to a
request.  Additionally, the CA may need to attribute errors to
specific identifiers.  For instance, a new-order request may contain
multiple identifiers for which the CA cannot issue.  In this
situation, an ACME problem document MAY contain the "sub-problems"
field, containing a JSON array of problem documents, each of which
MAY contain an "identifier" field.  If present, the "identifier"
field MUST contain an ACME identifier (iana-identifier).  The
"identifier" field MUST NOT be present at the top level in ACME
problem documents.  It can only be present in sub-problems.  Sub-
problems need not all have the same type, and do not need to match
the top level type.
Paragraph (version A):
ACME clients may choose to use the "identifier" field of a sub-
problem as a hint that an operation would succeed if that identifier
were omitted.  For instance, if an order contains ten DNS
identifiers, and the new-order request returns a problem document
with two sub-problems, referencing two of those identifiers, the ACME
client may choose to submit another order containing only the eight
identifiers not listed in the problem document.
Paragraph (version B):
Sometimes a CA may need to return multiple errors in response to a
request.  Additionally, the CA may need to attribute errors to
specific identifiers.  For instance, a new-order request may contain
multiple identifiers for which the CA cannot issue.  In this
situation, an ACME problem document MAY contain the "subproblems"
field, containing a JSON array of problem documents, each of which
MAY contain an "identifier" field.  If present, the "identifier"
field MUST contain an ACME identifier (iana-identifier).  The
"identifier" field MUST NOT be present at the top level in ACME
problem documents.  It can only be present in subproblems.
Subproblems need not all have the same type, and do not need to match
the top level type.
Paragraph (version B):
ACME clients may choose to use the "identifier" field of a subproblem
as a hint that an operation would succeed if that identifier were
omitted.  For instance, if an order contains ten DNS identifiers, and
the new-order request returns a problem document with two
subproblems, referencing two of those identifiers, the ACME client
may choose to submit another order containing only the eight
identifiers not listed in the problem document.
Paragraph (version A):
The server MUST provide "directory" and "new-nonce" resources.
Paragraph (version B):
The server MUST provide "directory" and "newNonce" resources.
Paragraph (version A):
If this field is present and set to "true", then the CA requires
that all new-account requests include an "external-account-
binding" field associating the new account with an external
account.
Paragraph (version B):
If this field is present and set to "true", then the CA requires
that all new-account requests include an "externalAccountBinding"
field associating the new account with an external account.
Paragraph (version A):
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 containing the "contact" field and optionally
the "terms-of-service-agreed" field.
Paragraph (version B):
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 containing the "contact" field and optionally
the "termsOfServiceAgreed" field.
Paragraph (version A):
If the server wishes to present the client with terms under which the
ACME service is to be used, it MUST indicate the URL where such terms
can be accessed in the "terms-of-service" subfield of the "meta"
field in the directory object, and the server MUST reject new-account
requests that do not have the "terms-of-service-agreed" set to
"true".  Clients SHOULD NOT automatically agree to terms by default.
Rather, they SHOULD require some user interaction for agreement to
terms.
Paragraph (version B):
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" set to "true".
Clients SHOULD NOT automatically agree to terms by default.  Rather,
they SHOULD require some user interaction for agreement to terms.
Paragraph (version A):
If a client wishes to find the URL for an existing account and does
not want an account to be created if one does not already exist, then
it SHOULD do so by sending a POST request to the new-account URL with
a JWS whose payload has an "only-return-existing" field set to "true"
({"only-return-existing": true}).  If a client sends such a request
and an account does not exist, then the server MUST return an error
response with status code 400 (Bad Request) and type
"urn:ietf:params:acme:error:accountDoesNotExist".
Paragraph (version B):
If a client wishes to find the URL for an existing account and does
not want an account to be created if one does not already exist, then
it SHOULD do so by sending a POST request to the new-account URL with
a JWS whose payload has an "onlyReturnExisting" field set to "true"
({"onlyReturnExisting": true}).  If a client sends such a request and
an account does not exist, then the server MUST return an error
response with status code 400 (Bad Request) and type
"urn:ietf:params:acme:error:accountDoesNotExist".
Paragraph (version A):
As described above, a client can indicate its agreement with the CA's
terms of service by setting the "terms-of-service-agreed" field in
its account object to "true".
Paragraph (version B):
As described above, a client can indicate its agreement with the CA's
terms of service by setting the "termsOfServiceAgreed" field in its
account object to "true".
Paragraph (version A):
The server MAY require a value for the "external-account-binding"
field to be present in "new-account" requests.  This can be used to
associate an ACME account with an existing account in a non-ACME
system, such as a CA customer database.
Paragraph (version B):
The server MAY require a value for the "externalAccountBinding" field
to be present in "newAccount" requests.  This can be used to
associate an ACME account with an existing account in a non-ACME
system, such as a CA customer database.
Paragraph (version A):
If a CA requires that new-account requests contain an "external-
account-binding" field, then it MUST provide the value "true" in the
"external-account-required" subfield of the "meta" field in the
directory object.  If the CA receives a new-account request without
an "external-account-binding" field, then it should reply with an
error of type "externalAccountRequired".
Paragraph (version B):
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
an "externalAccountBinding" field, then it should reply with an error
of type "externalAccountRequired".
Paragraph (version A):
If all of these checks pass and the CA creates a new account, then
the CA may consider the new account associated with the external
account corresponding to the MAC key and MUST reflect the value of
the "external-account-binding" field in the resulting account object.
If any of these checks fail, then the CA MUST reject the new-account
request.
Paragraph (version B):
If all of these checks pass and the CA creates a new account, then
the CA may consider the new account associated with the external
account corresponding to the MAC key and MUST reflect the value of
the "externalAccountBinding" field in the resulting account object.
If any of these checks fail, then the CA MUST reject the new-account
request.
Paragraph (version A):
If a CA wishes to allow pre-authorization within ACME, it can offer a
"new authorization" resource in its directory by adding the field
"new-authz" with a URL for the new authorization resource.
Paragraph (version B):
If a CA wishes to allow pre-authorization within ACME, it can offer a
"new authorization" resource in its directory by adding the field
"newAuthz" with a URL for the new authorization resource.