Draft: draft-ietf-acme-acme

Commentary: Merging based on review
Paragraph (version A):
Put a CA-provided challenge at a DNS location corresponding to
the target domain.
Paragraph (version A):
Receive CA challenge at a (hopefully) administrator-controlled
email address corresponding to the domain and then respond to
it on the CA's web page.
Paragraph (version B):
Put a CA-provided challenge in a DNS record corresponding to
the target domain.
Paragraph (version B):
Receive CA-provided challenge at a (hopefully) administrator-
controlled email address corresponding to the domain and then
respond to it on the CA's web page.
Paragraph (version A):
The ACME client prompts the operator for the intended domain
name(s) that the web server is to stand for.
Paragraph (version B):
The operator's ACME client prompts the operator for the intended
domain name(s) that the web server is to stand for.
Paragraph (version A):
The CA verifies that the client controls the requested domain
name(s).
Paragraph (version A):
Once the CA is satisfied, the certificate is issued and the ACME
client automatically downloads and installs it, potentially
notifying the operator via email, SMS, etc.
Paragraph (version B):
The CA verifies that the client controls the requested domain
name(s) by having the ACME client perform some action related to
the domain name(s).
Paragraph (version B):
Once the CA is satisfied, it issues the certificate and the ACME
client automatically downloads and installs it, potentially
notifying the operator via email, SMS, etc.
Paragraph (version A):
ACME allows a client to request certificate management actions using
a set of JavaScript Object Notation (JSON) messages carried over
HTTPS.  In many ways, ACME functions much like a traditional CA, in
which a user creates an account, requests a certificate, and proves
control of the domains in that certificate in order for the CA to
sign the requested certificate.
Paragraph (version B):
ACME allows a client to request certificate management actions using
a set of JavaScript Object Notation (JSON) messages carried over
HTTPS.
Issuance using ACME resembles a traditional CA's issuance process, in
which a user creates an account, requests a certificate, and proves
control of the domains in that certificate in order for the CA to
sign the requested certificate.
Paragraph (version A):
For example, in most cases, the server will require the client to
demonstrate that it controls the identifiers in the requested
certificate.  Because there are many different ways to validate
possession of different types of identifiers, the server will choose
from an extensible set of challenges that are appropriate for the
identifier being claimed.  The client responds with a set of
responses that tell the server which challenges the client has
completed.  The server then validates the challenges to check that
the client has accomplished them.
Paragraph (version B):
For example, in most cases, the server will require the client to
demonstrate that it controls the identifiers in the requested
certificate.  Because there are many different ways to validate
possession of different types of identifiers, the server will choose
from an extensible set of challenges that are appropriate for the
identifier being claimed.  The client responds with a set of
responses that tell the server which challenges the client has
completed.  The server then validates that the client has completed
the challenges.
Paragraph (version A):
Except for the directory resource, all ACME resources are addressed
with URLs provided to the client by the server.  For these resources,
the client MUST set the "url" header parameter to the exact string
provided by the server (rather than performing any re-encoding on the
URL).  The server SHOULD perform the corresponding string equality
check, configuring each resource with the URL string provided to
clients and having the resource check that requests have the same
string in their "url" header parameter.
Paragraph (version B):
Except for the directory resource, all ACME resources are addressed
with URLs provided to the client by the server.  In requests sent to
these resources, the client MUST set the "url" header parameter to
the exact string provided by the server (rather than performing any
re-encoding on the URL).  The server SHOULD perform the corresponding
string equality check, configuring each resource with the URL string
provided to clients and having the resource check that requests have
the same string in their "url" header parameter.
Paragraph (version A):
Creation of resources can be rate limited 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 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):
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 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 tokens in the "Link"
header pointing to documentation about the specific hit rate limits
using the "urn:ietf:params:acme:documentation" relation.
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 pointing to documentation about the specific rate limit
that was hit, using the "help" link relation type.
Paragraph (version B):
In the remainder of this document, we use the tokens in the table
above to refer to error types, rather than the full URNs.  For
example, an "error of type 'badCSR'" refers to an error document with
"type" value "urn:ietf:params:acme:error:badCSR".
Paragraph (version A):
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 fields names 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 field names are drawn from the following table and
whose values are the corresponding URLs.
Paragraph (version A):
For pending orders, the authorizations that the client needs to
complete before the requested certificate can be issued (see
identifier-authorization).  For final orders, the authorizations
that were completed.  Each entry is a URL from which an
authorization can be fetched with a GET request.
Paragraph (version B):
For pending orders, the authorizations that the client needs to
complete before the requested certificate can be issued (see
identifier-authorization).  For final orders (in the "valid" or
"invalid" state), the authorizations that were completed.  Each
entry is a URL from which an authorization can be fetched with a
GET request.
Paragraph (version A):
For pending authorizations, the challenges that the client can
fulfill in order to prove possession of the identifier.  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 successfully completed.
Paragraph (version B):
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.
For final authorizations, it contains the challenges that were
successfully completed.
Paragraph (version A):
The server MAY require a value to be present for the "external-
account-binding" field.  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):
To enable ACME account binding, a CA needs to provision the ACME
client with a MAC key and a key identifier.  The key identifier MUST
be an ASCII string.  The MAC key SHOULD be provided in base64url-
encoded form, to maximize compatibility between provisioning systems
and ACME clients.
Paragraph (version B):
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):
To enable ACME account binding, a CA needs to provide the ACME client
with a MAC key and a key identifier, using some mechanism outside of
ACME.  The key identifier MUST be an ASCII string.  The MAC key
SHOULD be provided in base64url-encoded form, to maximize
compatibility between non-ACME provisioning systems and ACME clients.
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 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 "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 A):
The client then encapsulates the key-change object in a JWS, signed
with the requested new account key (i.e., the key matching the
"newKey" value).
Paragraph (version B):
The client then encapsulates the key-change object in an "inner" JWS,
signed with the requested new account key (i.e., the key matching the
"newKey" value).  This JWS then becomes the payload for the "outer"
JWS that is the body of the ACME request.
Paragraph (version B):
The inner JWS MUST have a "jwk" header parameter, containing the
public key of the new key pair (i.e., the same value as the
"newKey" field).
Paragraph (version A):
In some cases, a CA running an ACME server might have a completely
external, non-ACME process for authorizing a client to issue for an
identifier.  In these cases, the CA should provision its ACME server
with authorization objects corresponding to these authorizations and
reflect them as already valid in any orders submitted by the client.
Paragraph (version B):
In some cases, a CA running an ACME server might have a completely
external, non-ACME process for authorizing a client to issue
certificates for an identifier.  In these cases, the CA should
provision its ACME server with authorization objects corresponding to
these authorizations and reflect them as already valid in any orders
submitted by the client.
Paragraph (version A):
The status of this authorization.  Possible values are: "pending",
"valid", and "invalid".
Paragraph (version A):
The time at which this challenge was completed by the server,
encoded in the format specified in RFC 3339 RFC3339.  This field
is REQUIRED if the "status" field is "valid".
Paragraph (version A):
Errors that occurred while the server was validating the
challenge, if any, structured as problem documents RFC7807.  The
server MUST NOT modify the array except by appending entries onto
the end.  The server can limit the size of this object by limiting
the number of times it will retry a challenge.
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 the
challenge failed.
Paragraph (version B):
The status of this challenge.  Possible values are: "pending",
"valid", and "invalid".
Paragraph (version B):
The time at which the server validated this challenge, encoded in
the format specified in RFC 3339 RFC3339.  This field is REQUIRED
if the "status" field is "valid".
Paragraph (version B):
Errors that occurred while the server was validating the
challenge, if any, structured as problem documents RFC7807.  The
server MUST NOT modify the array except by appending entries onto
the end.  The server can limit the size of this object by limiting
the number of times it will try to validate a 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 "errors" 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 noted in JWA RFC7518
any prepended zero octets in the JWK object MUST be stripped before
doing the computation.
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 fields of a JWK object MUST be
stripped before doing the computation.
Paragraph (version A):
With HTTP validation, the client in an ACME transaction proves its
control over a domain name by proving that for that domain name it
can provision resources to be returned by an HTTP server.  The ACME
server challenges the client to provision a file at a specific path,
with a specific string as its content.
Paragraph (version B):
With HTTP validation, the client in an ACME transaction proves its
control over a domain name by proving that it can provision HTTP
resources on a server accessible under that domain name.  The ACME
server challenges the client to provision a file at a specific path,
with a specific string as its content.
Paragraph (version A):
A random value that uniquely identifies the challenge.  This value
MUST have at least 128 bits of entropy.  It MUST NOT contain any
characters outside the base64url alphabet, including padding
characters ("=").
Paragraph (version B):
A random value that uniquely identifies the challenge.  This value
MUST have at least 128 bits of entropy.  It MUST NOT contain any
characters outside the base64url alphabet, and MUST NOT include
base64 padding characters ("=").
Paragraph (version A):
The client's response to this challenge indicates its agreement to
this challenge by sending the server the key authorization covering
the challenge's token and the client's account key.
Paragraph (version B):
The client's response to the validation request indicates its
agreement to this challenge by sending the server the key
authorization covering the challenge's token and the client's account
key.
Paragraph (version A):
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):
the token field is set to the token in the challenge.
Paragraph (version A):
File should contain one or more certificates encoded as PEM according
to RFC 7468 RFC7468.  In order to provide easy interoperation with
TLS, the first certificate MUST be an end-entity certificate.  Each
following certificate SHOULD directly certify one preceding it.
Because certificate validation requires that trust anchors be
distributed independently, a certificate that specifies a trust
anchor MAY be omitted from the chain, provided that supported peers
are known to possess any omitted certificates.
Paragraph (version B):
File contains one or more certificates encoded with the PEM textual
encoding, according to RFC 7468 RFC7468.  In order to provide easy
interoperation with TLS, the first certificate MUST be an end-entity
certificate.  Each following certificate SHOULD directly certify one
preceding it.  Because certificate validation requires that trust
anchors be distributed independently, a certificate that specifies a
trust anchor MAY be omitted from the chain, provided that supported
peers are known to possess any omitted certificates.
Paragraph (version B):
This registry lists field names that are defined for use in ACME
authorization objects.  Fields marked as "configurable" may be
included in a new-authorization request.
Paragraph (version B):
Initial contents: The fields and descriptions defined in
authorization-objects.