Draft: draft-ietf-acme-acme

Commentary: Also moves various scattered character encoding references to their own section .
Paragraph (version B):
All requests and responses sent via HTTP by ACME clients, ACME
servers, and validation servers as well as any inputs for digest
computations MUST be encoded using the UTF-8 RFC3629 character set.
Paragraph (version A):
All ACME requests with a non-empty body MUST encapsulate their
payload in a JSON Web Signature (JWS) RFC7515 object, signed (in most
cases) using the account's private key.  The server MUST verify the
JWS before processing the request.  Encapsulating request bodies in
JWS provides a simple authentication of requests.
Paragraph (version B):
All ACME requests with a non-empty body MUST encapsulate their
payload in a JSON Web Signature (JWS) RFC7515 object, signed using
the account's private key unless otherwise specified.  The server
MUST verify the JWS before processing the request.  Encapsulating
request bodies in JWS provides authentication of requests.
Paragraph (version A):
The "url" header parameter specifies the URL RFC3986 to which this
JWS object is directed.  The "url" parameter MUST be carried in the
protected header of the JWS.  The value of the "url" header MUST be a
JSON string representing the URL.
Paragraph (version B):
The "url" header parameter specifies the URL RFC3986 to which this
JWS object is directed.  The "url" parameter MUST be carried in the
protected header of the JWS.  The value of the "url" header MUST be a
string representing the URL.
Paragraph (version A):
The "index" link relation is present on all resources other than the
directory and indicates the directory URL.
Paragraph (version B):
The "index" link relation is present on all resources other than the
directory and indicates the URL of the directory.
Paragraph (version A):
The challenges that the client can fulfill in order to prove
possession of the identifier (for pending authorizations).  For
final authorizations, the challenges that were used.  Each array
entry is an object with parameters required to validate the
challenge.  A client should attempt to fulfill at most one of
these challenges, and a server should consider any one of the
challenges sufficient to make the authorization valid.
Paragraph (version A):
The only type of identifier defined by this specification is a fully-
qualified domain name (type: "dns").  The value of the identifier
MUST be the ASCII representation of the domain name.  If a domain
name contains 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.
Paragraph (version B):
The challenges that the client can fulfill in order to prove
possession of the identifier (for pending authorizations).  For
final authorizations, 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.  For final
authorizations it contains the challenges that were completed.
Paragraph (version B):
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.
Paragraph (version A):
To get a fresh nonce, the client sends a HEAD request to the new-
nonce resource on the server.  The server's response MUST include a
Replay-Nonce header field containing a fresh nonce, and SHOULD have
status code 204 (No Content).  The server SHOULD also respond to GET
requests for this resource, returning an empty body (while still
providing a Replay-Nonce header).
Paragraph (version B):
To get a fresh nonce, the client sends a HEAD request to the new-
nonce resource on the server.  The server's response MUST include a
Replay-Nonce header field containing a fresh nonce, and SHOULD have
status code 204 (No Content).  The server SHOULD also respond to GET
requests for this resource, returning an empty body (while still
providing a Replay-Nonce header) with a 204 (No Content) status.
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 only the "contact" 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 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 A):
The server creates an account object with the included contact
information.  The "key" element of the account is set to the public
key used to verify the JWS (i.e., the "jwk" element of the JWS
header).  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 200 (OK) response and provide the
URI of that account in the Content-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 B):
The server creates an account and populates the account object with
the "key" field containing the JWK public key used to verify the JWS.
The server returns this account object in a response with a 201
(Created) status code, with the account URI 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 URI of that account in the Content-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):
Servers SHOULD NOT respond to GET requests for account 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
"contact" or "certificates" fields), then it SHOULD do so by sending
a POST request with an empty update.  That is, it should send a JWS
whose payload is trivial ({}).
Paragraph (version B):
Servers SHOULD NOT respond to GET requests for account 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
"contact" or "certificates" fields), then it SHOULD do so by sending
a POST request with an empty update.  That is, it should send a JWS
whose payload is an empty object ({}).
Paragraph (version A):
"valid": The server has issued the certificate and provisioned its
URL to the "certificate" field of the order.  Download the
certificate.
Paragraph (version B):
"valid": The server has issued the certificate and provisioned its
URL to the "certificate" field of the order.
Paragraph (version A):
When a client receives an order from the server it downloads the
authorization resource by sending a GET request to the indicated URL.
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 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).  This allows the client to send information only for challenges
it is responding to.
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 B):
To prove control of the identifier and receive authorization, the
client needs to respond with information to complete the challenges.
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.
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 URI (not authorization
URI) once it is ready for the server to attempt validation.
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 that identifier by
sending a POST request with the static object {"status":
"deactivated"}.
Paragraph (version A):
The server MUST verify that the request is signed by the account key
corresponding to the account that owns the authorization.  If the
server accepts the deactivation, it should reply with a 200 (OK)
status code and the current contents of the authorization object.
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 URI.
Paragraph (version B):
The server MUST verify that the request is signed by the account key
corresponding to the account that owns the authorization.  If the
server accepts the deactivation, it should reply with a 200 (OK)
status code and the updated contents of the authorization object.
Paragraph (version A):
All additional fields are specified by the challenge type.  If the
server sets a challenge's "status" to "invalid", it SHOULD also
include the "error" field to help the client diagnose why they failed
the challenge.
Paragraph (version B):
All additional fields are specified by the challenge type.  If the
server sets a challenge's "status" to "invalid", it SHOULD also
include the "error" field to help the client diagnose why the
challenge failed.
Paragraph (version A):
The "JWK_Thumbprint" step indicates the computation specified in
RFC7638, using the SHA-256 digest FIPS180-4.  As specified in the
individual challenges below, the token for a challenge is a JSON
string comprised entirely of characters in the URL-safe base64
alphabet.  The "||" operator indicates concatenation of strings.
Paragraph (version A):
In computations involving key authorizations, such as the digest
computations required for the DNS and TLS SNI challenges, the key
authorization string MUST be represented in UTF-8 form (or,
equivalently, ASCII).
Paragraph (version A):
An example of how to compute a JWK thumbprint can be found in
Section 3.1 of RFC7638.  Note that some cryptographic libraries
prepend a zero octet to the representation of the RSA public key
parameters N and E, in order to avoid ambiguity with regard to the
sign of the number.  As noted in JWA RFC7518, a JWK object MUST NOT
include this zero octet.  That is, any initial zero octets MUST be
stripped before the values are base64url-encoded.
Paragraph (version B):
The "JWK_Thumbprint" step indicates the computation specified in
RFC7638, using the SHA-256 digest FIPS180-4.  As noted in JWA RFC7518
any prepended zero octets in the JWK object MUST be stripped before
doing the computation.
Paragraph (version B):
As specified in the individual challenges below, the token for a
challenge is a string comprised entirely of characters in the URL-
safe base64 alphabet.  The "||" operator indicates concatenation of
strings.
Paragraph (version A):
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 under 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 reconfigured
TLS server and verifying a particular challenge certificate is
presented.
Paragraph (version B):
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.
Paragraph (version A):
SAN A MUST be constructed as follows: compute the SHA-256 digest
FIPS180-4 of the UTF-8-encoded 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.
Paragraph (version A):
SAN B MUST be constructed as follows: compute the SHA-256 digest of
the UTF-8 encoded 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.
Paragraph (version B):
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.
Paragraph (version B):
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.
Paragraph (version A):
When the identifier being validated is a domain name, the client can
prove control of that domain by provisioning a resource record under
it.  The DNS challenge requires the client to provision a TXT record
containing a designated value under a specific validation domain
name.
Paragraph (version B):
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.
Paragraph (version A):
All of these registries are under a heading of "Automated Certificate
Management Environment (ACME) Protocol" and are be administered under
a Specification Required policy RFC5226.
Paragraph (version B):
All of these registries are under a heading of "Automated Certificate
Management Environment (ACME) Protocol" and are administered under a
Specification Required policy RFC5226.
Paragraph (version A):
ACME allows anyone to request challenges for an identifier by
registering an account key and sending a new-order request under 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 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.