Draft: draft-ietf-acme-acme

Commentary: This PR addresses my following comment on the mailing list . Things that remain URIs " type " field in problem details " contact " fields in account objects Needs clarification Should " terms - of - service " remain a URI ? Seems unlikely that they are published as book . There is a part I think that should be a URL too . provide an integrity mechanism , which protects against an intermediary Right know I think the wording " ACME URL " makes sense . But it could be clarified why this is a ACME URL . 
 Maybe I will just create separate PRs for the parts that are not covered yet . Then , they can be discussed separately . 
 Plus we should check for similar inconsistencies elsewhere . 
 PR at 
 Fixed .
Paragraph (version A):
Communications between an ACME client and an ACME server are done
over HTTPS, using JSON Web Signature (JWS) RFC7515 to provide some
additional security properties for messages sent from the client to
the server.  HTTPS provides server authentication and
confidentiality.  With some ACME-specific extensions, JWS provides
authentication of the client's request payloads, anti-replay
protection, and integrity for the HTTPS request URI.
Paragraph (version B):
Communications between an ACME client and an ACME server are done
over HTTPS, using JSON Web Signature (JWS) RFC7515 to provide some
additional security properties for messages sent from the client to
the server.  HTTPS provides server authentication and
confidentiality.  With some ACME-specific extensions, JWS provides
authentication of the client's request payloads, anti-replay
protection, and integrity for the HTTPS request URL.
Paragraph (version A):
For all other requests, there MUST be a "kid" field.  This field must
contain the account URI received by POSTing to the new-account
resource.
Paragraph (version B):
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.
Paragraph (version A):
These intermediaries can also change values in the request that are
not signed in the HTTPS request, e.g., the request URI and headers.
ACME uses JWS to provide an integrity mechanism, which protects
against an intermediary changing the request URI to another ACME URI.
Paragraph (version A):
As noted in request-authentication above, all ACME request objects
carry a "url" parameter in their protected header.  This header
parameter encodes the URL to which the client is directing the
request.  On receiving such an object in an HTTP request, the server
MUST compare the "url" parameter to the request URI.  If the two do
not match, then the server MUST reject the request as unauthorized.
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 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):
As noted in request-authentication above, all ACME request objects
carry a "url" parameter in their protected header.  This header
parameter encodes the URL to which the client is directing the
request.  On receiving such an object in an HTTP request, the server
MUST compare the "url" parameter to the request URL.  If the two do
not match, then the server MUST reject the request as unauthorized.
Paragraph (version A):
ACME uses different URIs for different management functions.  Each
function is listed in a directory along with its corresponding URI,
so clients only need to be configured with the directory URI.  These
URIs are connected by a few different link relations RFC5988.
Paragraph (version B):
ACME uses different URLs for different management functions.  Each
function is listed in a directory along with its corresponding URL,
so clients only need to be configured with the directory URL.  These
URLs are connected by a few different link relations RFC5988.
Paragraph (version A):
In order to help clients configure themselves with the right URIs for
each ACME operation, ACME servers provide a directory object.  This
should be the only URL needed to configure clients.  It is a JSON
object, whose keys are drawn from the following table and whose
values are the corresponding URLs.
Paragraph (version B):
In order to help clients configure themselves with the right URLs for
each ACME operation, ACME servers provide a directory object.  This
should be the only URL needed to configure clients.  It is a JSON
object, whose keys are drawn from the following table and whose
values are the corresponding URLs.
Paragraph (version A):
Clients access the directory by sending a GET request to the
directory URI.
Paragraph (version B):
Clients access the directory by sending a GET request to the
directory URL.
Paragraph (version A):
A URI from which a list of orders submitted by this account can be
fetched via a GET request, as described in orders-list.
Paragraph (version A):
Each account object includes an "orders" URI from which a list of
orders created by the account can be fetched via GET request.  The
result of the GET request MUST be a JSON object whose "orders" field
is an array of URIs, each identifying an order belonging to the
account.  The server SHOULD include pending orders, and SHOULD NOT
include orders that are invalid in the array of URIs.  The server MAY
return an incomplete list, along with a Link header with a "next"
link relation indicating where further entries can be acquired.
Paragraph (version B):
A URL from which a list of orders submitted by this account can be
fetched via a GET request, as described in orders-list.
Paragraph (version B):
Each account object includes an "orders" URL from which a list of
orders created by the account can be fetched via GET request.  The
result of the GET request MUST be a JSON object whose "orders" field
is an array of URLs, each identifying an order belonging to the
account.  The server SHOULD include pending orders, and SHOULD NOT
include orders that are invalid in the array of URLs.  The server MAY
return an incomplete list, along with a Link header with a "next"
link relation indicating where further entries can be acquired.
Paragraph (version A):
If this field is present, then it MUST contain a URI for an order
resource, such that this authorization is only valid for that
resource.  If this field is absent, then the CA MUST consider this
authorization valid for all orders until the authorization
expires.
Paragraph (version B):
If this field is present, then it MUST contain a URL for an order
resource, such that this authorization is only valid for that
resource.  If this field is absent, then the CA MUST consider this
authorization valid for all orders until the authorization
expires.
Paragraph (version A):
A client creates a new account with the server by sending a POST
request to the server's new-account URI.  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 "terms-of-service-agreed" field.
Paragraph (version A):
The server creates an account and stores the public key used to
verify the JWS (i.e., the "jwk" element of the JWS header) to
authenticate future requests from the account.  The server returns
this account object in a 201 (Created) response, with the account URI
in a Location header field.
Paragraph (version A):
If the server already has an account registered with the provided
account key, then it MUST return a response with a 200 (OK) status
code and provide the URI of that account in the Location header
field.  This allows a client that has an account key but not the
corresponding account URI to recover the account URI.
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 URI 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):
The server creates an account and stores the public key used to
verify the JWS (i.e., the "jwk" element of the JWS header) to
authenticate future requests from the account.  The server returns
this account object in a 201 (Created) response, with the account URL
in a Location header field.
Paragraph (version B):
If the server already has an account registered with the provided
account key, then it MUST return a response with a 200 (OK) status
code and provide the URL of that account in the Location header
field.  This allows a client that has an account key but not the
corresponding account URI to recover the account URL.
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 "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 A):
If the client wishes to update this information in the future, it
sends a POST request with updated information to the account URI.
The server MUST ignore any updates to "order" fields or any other
fields it does not recognize.
Paragraph (version B):
If the client wishes to update this information in the future, it
sends a POST request with updated information to the account URL.
The server MUST ignore any updates to "order" fields or any other
fields it does not recognize.
Paragraph (version A):
The server allocates a new URI for this authorization, and returns a
201 (Created) response, with the authorization URI in the Location
header field, and the JSON authorization object in the body.  The
client then follows the process described in identifier-authorization
to complete the authorization process.
Paragraph (version B):
The server allocates a new URL for this authorization, and returns a
201 (Created) response, with the authorization URL in the Location
header field, and the JSON authorization object in the body.  The
client then follows the process described in identifier-authorization
to complete the authorization process.
Paragraph (version A):
This process may be repeated to associate multiple identifiers to a
key pair (e.g., to request certificates with multiple identifiers),
or to associate multiple accounts with an identifier (e.g., to allow
multiple entities to manage certificates).  The server may declare
that an authorization is only valid for a specific order by setting
the "scope" field of the authorization to the URI for that order.
Paragraph (version B):
This process may be repeated to associate multiple identifiers to a
key pair (e.g., to request certificates with multiple identifiers),
or to associate multiple accounts with an identifier (e.g., to allow
multiple entities to manage certificates).  The server may declare
that an authorization is only valid for a specific order by setting
the "scope" field of the authorization to the URL for that order.
Paragraph (version A):
The client sends these updates back to the server in the form of a
JSON object with the response fields required by the challenge type,
carried in a POST request to the challenge URI (not authorization
URI) once it is ready for the server to attempt validation.
Paragraph (version B):
The client sends these updates back to the server in the form of a
JSON object with the response fields required by the challenge type,
carried in a POST request to the challenge URL (not authorization
URL) once it is ready for the server to attempt validation.
Paragraph (version A):
To check on the status of an authorization, the client sends a GET
request to the authorization URI, and the server responds with the
current authorization object.  In responding to poll requests while
the validation is still in progress, the server MUST return a 200
(OK) response and MAY include a Retry-After header field to suggest a
polling interval to the client.
Paragraph (version B):
To check on the status of an authorization, the client sends a GET
request to the authorization URL, and the server responds with the
current authorization object.  In responding to poll requests while
the validation is still in progress, the server MUST return a 200
(OK) response and MAY include a Retry-After header field to suggest a
polling interval to the client.
Paragraph (version A):
If a client wishes to relinquish its authorization to issue
certificates for an identifier, then it may request that the server
deactivates each authorization associated with it by sending POST
requests with the static object {"status": "deactivated"} to each
authorization URI.
Paragraph (version B):
If a client wishes to relinquish its authorization to issue
certificates for an identifier, then it may request that the server
deactivates each authorization associated with it by sending POST
requests with the static object {"status": "deactivated"} to each
authorization URL.
Paragraph (version A):
ACME uses an extensible challenge/response framework for identifier
validation.  The server presents a set of challenges in the
authorization object it sends to a client (as objects in the
"challenges" array), and the client responds by sending a response
object in a POST request to a challenge URI.
Paragraph (version B):
ACME uses an extensible challenge/response framework for identifier
validation.  The server presents a set of challenges in the
authorization object it sends to a client (as objects in the
"challenges" array), and the client responds by sending a response
object in a POST request to a challenge URL.
Paragraph (version A):
Construct a URI by populating the URI template RFC6570
"http://{domain}/.well-known/acme-challenge/{token}", where: * the
domain field is set to the domain name being verified; and * the
token field is set to the token in the challenge.
Paragraph (version A):
Verify that the resulting URI is well-formed.
Paragraph (version A):
Dereference the URI using an HTTP GET request.  This request MUST
be sent to TCP port 80 on the HTTP server.
Paragraph (version B):
Construct a URL by populating the URL template RFC6570
"http://{domain}/.well-known/acme-challenge/{token}", where: * the
domain field is set to the domain name being verified; and * the
token field is set to the token in the challenge.
Paragraph (version B):
Verify that the resulting URL is well-formed.
Paragraph (version B):
Dereference the URL using an HTTP GET request.  This request MUST
be sent to TCP port 80 on the HTTP server.
Paragraph (version A):
The server SHOULD follow redirects when dereferencing the URI.
Paragraph (version B):
The server SHOULD follow redirects when dereferencing the URL.