Draft: draft-ietf-acme-acme

Commentary: HTTP header fields are always called " header field " HTTP header fields are unquoted " new - X " and " new X " converted to " newX " Miscellaneous other consistency fixes 
 Belated LGTMThis diff looks good to me , thanks : ballotboxwith_check : Sorry to see the quote - marks around words - as - TERMS go , but I defer to others .
Paragraph (version A):
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).
Paragraph (version B):
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).
Paragraph (version A):
When a server rejects a request because its nonce value was
unacceptable (or not present), it MUST provide HTTP status code 400
(Bad Request), and indicate the ACME error type
"urn:ietf:params:acme:error:badNonce".  An error response with the
"badNonce" error type MUST include a Replay-Nonce header with a fresh
nonce that the server will accept in a retry of the original query
(and possibly in other requests, according to the server's nonce
scoping policy).  On receiving such a response, a client SHOULD retry
the request using the new nonce.
Paragraph (version B):
When a server rejects a request because its nonce value was
unacceptable (or not present), it MUST provide HTTP status code 400
(Bad Request), and indicate the ACME error type
"urn:ietf:params:acme:error:badNonce".  An error response with the
"badNonce" error type MUST include a Replay-Nonce header field with a
fresh nonce that the server will accept in a retry of the original
query (and possibly in other requests, according to the server's
nonce scoping policy).  On receiving such a response, a client SHOULD
retry the request using the new nonce.
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, and unpredictable to anyone besides the server.
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):
Creation of resources can be rate limited by ACME servers to ensure
fair usage and prevent abuse.  Once the rate limit is exceeded, the
server MUST respond with an error with the type
"urn:ietf:params:acme:error:rateLimited".  Additionally, the server
SHOULD send a "Retry-After" header RFC7231 indicating when the
current request may succeed again.  If multiple rate limits are in
place, that is the time where all rate limits allow access again for
the current request with exactly the same parameters.
Paragraph (version A):
In addition to the human-readable "detail" field of the error
response, the server MAY send one or multiple link relations in the
"Link" header RFC8288 pointing to documentation about the specific
rate limit that was hit, using the "help" link relation type.
Paragraph (version B):
Creation of resources can be rate limited by ACME servers to ensure
fair usage and prevent abuse.  Once the rate limit is exceeded, the
server MUST respond with an error with the type
"urn:ietf:params:acme:error:rateLimited".  Additionally, the server
SHOULD send a Retry-After header field RFC7231 indicating when the
current request may succeed again.  If multiple rate limits are in
place, that is the time where all rate limits allow access again for
the current request with exactly the same parameters.
Paragraph (version B):
In addition to the human-readable "detail" field of the error
response, the server MAY send one or multiple link relations in the
Link header field RFC8288 pointing to documentation about the
specific rate limit that was hit, using the "help" link relation
type.
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 "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 they do not need to
match the top level type.
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 newOrder 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 they do not need to
match the top level type.
Paragraph (version A):
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 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 newOrder 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 following table illustrates a typical sequence of requests
required to establish a new account with the server, prove control of
an identifier, issue a certificate, and fetch an updated certificate
some time after issuance.  The "->" is a mnemonic for a Location
header pointing to a created resource.
Paragraph (version B):
The following table illustrates a typical sequence of requests
required to establish a new account with the server, prove control of
an identifier, issue a certificate, and fetch an updated certificate
some time after issuance.  The "->" is a mnemonic for a Location
header field pointing to a created resource.
Paragraph (version A):
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 B):
If this field is present and set to "true", then the CA requires
that all newAccount requests include an "externalAccountBinding"
field associating the new account with an external account.
Paragraph (version A):
Including this field in a new-account request, with a value of
true, indicates the client's agreement with the terms of service.
This field cannot be updated by the client.
Paragraph (version B):
Including this field in a newAccount request, with a value of
true, indicates the client's agreement with the terms of service.
This field cannot be updated by the client.
Paragraph (version A):
Any identifier of type "dns" in a new-order request MAY have a
wildcard domain name as its value.  A wildcard domain name consists
of a single asterisk character followed by a single full stop
character ("*.") followed by a domain name as defined for use in the
Subject Alternate Name Extension by RFC5280.  An authorization
returned by the server for a wildcard domain name identifier MUST NOT
include the asterisk and full stop ("*.") prefix in the authorization
identifier value.  The returned authorization MUST include the
optional "wildcard" field, with a value of true.
Paragraph (version B):
Any identifier of type "dns" in a newOrder request MAY have a
wildcard domain name as its value.  A wildcard domain name consists
of a single asterisk character followed by a single full stop
character ("*.") followed by a domain name as defined for use in the
Subject Alternate Name Extension by RFC5280.  An authorization
returned by the server for a wildcard domain name identifier MUST NOT
include the asterisk and full stop ("*.") prefix in the authorization
identifier value.  The returned authorization MUST include the
optional "wildcard" field, with a value of true.
Paragraph (version A):
Authorization objects are created in the "pending" state.  If one of
the challenges listed in the authorization transitions to the "valid"
state, then the authorization also changes to the "valid" state.  If
the client attempts to fulfill a challenge and fails, or if there is
an error while the authorization is still pending, then the
authorization transitions to the "invalid" state.  Once the
authorization is in the valid state, it can expire ("expired"), be
deactivated by the client ("deactivated", see deactivating-an-
authorization), or revoked by the server ("revoked").
Paragraph (version B):
Authorization objects are created in the "pending" state.  If one of
the challenges listed in the authorization transitions to the "valid"
state, then the authorization also changes to the "valid" state.  If
the client attempts to fulfill a challenge and fails, or if there is
an error while the authorization is still pending, then the
authorization transitions to the "invalid" state.  Once the
authorization is in the "valid" state, it can expire ("expired"), be
deactivated by the client ("deactivated", see deactivating-an-
authorization), or revoked by the server ("revoked").
Paragraph (version A):
Proxy caching of responses from the new-nonce resource can cause
clients to receive the same nonce repeatedly, leading to badNonce
errors.  The server MUST include a Cache-Control header field with
the "no-store" directive in responses for the new-nonce resource, in
order to prevent caching of this resource.
Paragraph (version B):
Proxy caching of responses from the new-nonce resource can cause
clients to receive the same nonce repeatedly, leading to "badNonce"
errors.  The server MUST include a Cache-Control header field with
the "no-store" directive in responses for the new-nonce resource, in
order to prevent caching of this resource.
Paragraph (version A):
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.
Paragraph (version B):
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
newAccount 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.
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 "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 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 newAccount 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):
If such 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 B):
If such a CA requires that newAccount 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 newAccount 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.  The account object the CA
returns MUST include an "externalAccountBinding" field with the same
value as the field in the request.  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.  The account object the CA
returns MUST include an "externalAccountBinding" field with the same
value as the field in the request.  If any of these checks fail, then
the CA MUST reject the newAccount request.
Paragraph (version A):
The URL for the account being modified.  The content of this field
MUST be the exact string provided in the Location header field in
response to the new-account request that created the account.
Paragraph (version B):
The URL for the account being modified.  The content of this field
MUST be the exact string provided in the Location header field in
response to the newAccount request that created the account.
Paragraph (version A):
The CSR encodes the client's requests with regard to the content of
the certificate to be issued.  The CSR MUST indicate the exact same
set of requested identifiers as the initial new-order request.
Identifiers of type "dns" MUST appear either in the commonName
portion of the requested subject name or in an extensionRequest
attribute RFC2985 requesting a subjectAltName extension, or both.
(These identifiers may appear in any sort order.)  Specifications
that define new identifier types must specify where in the
certificate signing request these identifiers can appear.
Paragraph (version B):
The CSR encodes the client's requests with regard to the content of
the certificate to be issued.  The CSR MUST indicate the exact same
set of requested identifiers as the initial newOrder request.
Identifiers of type "dns" MUST appear either in the commonName
portion of the requested subject name or in an extensionRequest
attribute RFC2985 requesting a subjectAltName extension, or both.
(These identifiers may appear in any sort order.)  Specifications
that define new identifier types must specify where in the
certificate signing request these identifiers can appear.
Paragraph (version A):
"processing": The certificate is being issued.  Send a POST-as-GET
request after the time given in the "Retry-After" header field of
the response, if any.
Paragraph (version B):
"processing": The certificate is being issued.  Send a POST-as-GET
request after the time given in the Retry-After header field of
the response, if any.
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
"newAuthz" with a URL for the new authorization resource.
Paragraph (version A):
To request authorization for an identifier, the client sends a POST
request to the new-authorization resource specifying the identifier
for which authorization is being requested.
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 newAuthz resource.
Paragraph (version B):
To request authorization for an identifier, the client sends a POST
request to the newAuthz resource specifying the identifier for which
authorization is being requested.
Paragraph (version A):
When a client receives an order from the server in reply to a new
order request, it downloads the authorization resources by sending
POST-as-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 in reply to a new
order request, it downloads the authorization resources by sending
POST-as-GET requests to the indicated URLs.  If the client initiates
authorization using a request to the newAuthz resource, it will have
already received the pending authorization object in the response to
that request.
Paragraph (version A):
The "ACME Account Object Fields" registry lists field names that are
defined for use in ACME account objects.  Fields marked as
"configurable" may be included in a new-account request.
Paragraph (version B):
The "ACME Account Object Fields" registry lists field names that are
defined for use in ACME account objects.  Fields marked as
"configurable" may be included in a newAccount request.
Paragraph (version A):
ACME allows anyone to request challenges for an identifier by
registering an account key and sending a new-order request using that
account key.  The integrity of the authorization process thus depends
on the identifier validation challenges to ensure that the challenge
can only be completed by someone who both (1) holds the private key
of the account key pair and (2) controls the identifier in question.
Paragraph (version B):
ACME allows anyone to request challenges for an identifier by
registering an account key and sending a newOrder request using that
account key.  The integrity of the authorization process thus depends
on the identifier validation challenges to ensure that the challenge
can only be completed by someone who both (1) holds the private key
of the account key pair and (2) controls the identifier in question.