Draft: draft-ietf-acme-acme

Commentary: ( Cash - box can be implemented as an out - of - band precondition ) 
 I 'd prefer to have the missing identifier in the precondition response instead of an already created and pending authorization . 
 At IETF 95 , issue came up that supporting pre - ACME CAs would likely involve the need for payment . This is a stub issue to start discussion of how ACME might respond . 
 Oops , this was dealt with in the previous repository : I 'm filing my PR anyway since I 've already written it , and I 'm dubious about the ' = * ' proposal . 
 Closing this in favor of
Paragraph (version A):
The first phase of ACME is for the client to register with the ACME
server.  The client generates an asymmetric key pair and associates
this key pair with a set of contact information by signing the
contact information.  The server acknowledges the registration by
replying with a registration object echoing the client's input.
Paragraph (version A):
Before a client can issue certificates, it must establish an
authorization with the server for an account key pair to act for the
identifier(s) that it wishes to include in the certificate.  To do
this, the client must demonstrate to the server both (1) that it
holds the private key of the account key pair, and (2) that it has
authority over the identifier being claimed.
Paragraph (version A):
Proof of possession of the account key is built into the ACME
protocol.  All messages from the client to the server are signed by
the client, and the server verifies them using the public key of the
account key pair.
Paragraph (version A):
To verify that the client controls the identifier being claimed, the
server issues the client a set of challenges.  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 the
challenge.
Paragraph (version A):
For example, if the client requests a domain name, the server might
challenge the client to provision a record in the DNS under that
name, or to provision a file on a web server referenced by an A or
AAAA record under that name.  The server would then query the DNS for
the record in question, or send an HTTP request for the file.  If the
client provisioned the DNS or the web server as expected, then the
server considers the client authorized for the domain name.
Paragraph (version A):
Once the client has authorized an account key pair for an identifier,
it can use the key pair to authorize the issuance of certificates for
the identifier.  To do this, the client sends a PKCS#10 Certificate
Signing Request (CSR) to the server (indicating the identifier(s) to
be included in the issued certificate) and a signature over the CSR
by the private key of the account key pair.
Paragraph (version A):
Note that as a result, the CSR is signed twice: One by the private
key corresponding to the public key in the CSR, and once by the
private key of the account key pair.  The former signature indicates
that the holder of the key in the CSR is willing to act for the
indicated identifiers, and the latter signature indicates to the
server that the issuance of the certificate is authorized by the
client (i.e., the domain holder).
Paragraph (version A):
If the server agrees to issue the certificate, then it creates the
certificate and provides it in its response.  The certificate is
assigned a URI, which the client can use to fetch updated versions of
the certificate.
Paragraph (version B):
The first phase of ACME is for the client to register with the ACME
server.  The client generates an asymmetric key pair and associates
this key pair with a set of contact information by signing the
contact information.  The server acknowledges the registration by
replying with a registration object echoing the client's input.  The
server can also provide terms of service at this stage, which the
client can present to a human user.
Paragraph (version B):
The client's application for a certificate describes the desired
certificate using a PKCS#10 Certificate Signing Request (CSR) plus a
few additional fields that capture semantics that are not supported
in the CSR format.  If the server is willing to consider issuing such
a certificate, it responds with a list of requirements that the
client must satisfy before the certificate will be issued.
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 the challenges to check that
the client has accomplished the challenge.
Paragraph (version B):
Once the validation process is complete and the server is satisfied
that the client has met its requirements, the server can either
proactively issue the requested certificate or wait for the client to
request that the application be "finalized", at which point the
certificate will be issued and provided to the client.
Paragraph (version A):
A URI from which a list of authorizations granted to this account
can be fetched via a GET request.  The result of the GET request
MUST be a JSON object whose "authorizations" field is an array of
strings, where each string is the URI of an authorization
belonging to this registration.  The server SHOULD include pending
authorizations, and SHOULD NOT include authorizations that are
invalid or expired.  The server MAY return an incomplete list,
along with a Link header with link relation "next" indicating a
URL to retrieve further entries.
Paragraph (version B):
A URI from which a list of authorizations submitted by this
account can be fetched via a GET request.  The result of the GET
request MUST be a JSON object whose "applications" field is an
array of strings, where each string is the URI of an authorization
belonging to this registration.  The server SHOULD include pending
applications, and SHOULD NOT include applications that are
invalid.  The server MAY return an incomplete list, along with a
Link header with link relation "next" indicating a URL to retrieve
further entries.
Paragraph (version B):
An ACME registration resource represents a client's request for a
certificate, and is used to track the progress of that application
through to issuance.  Thus, the object contains information about the
requested certificate, the server's requirements, and any
certificates that have resulted from this application.
Paragraph (version B):
The status of this authorization.  Possible values are: "unknown",
"pending", "processing", "valid", and "invalid".
Paragraph (version B):
The timestamp after which the server will consider this
application invalid, encoded in the format specified in RFC 3339
RFC3339.  This field is REQUIRED for objects with "pending" or
"valid" in the status field.
Paragraph (version B):
The requirements that the client needs to fulfill before the
requested certificate can be granted (for pending applications).
For final applications, the requirements that were met.  Each
entry is a dictionary with parameters describing the requirement
(see below).
Paragraph (version B):
A URL for the certificate that has been issued in response to this
application.
Paragraph (version B):
The elements of the "requirements" array are immutable once set,
except for their "status" fields.  If any other part of the object
changes after the object is created, the client MUST consider the
application invalid.
Paragraph (version B):
The "requirements" array in the challenge SHOULD reflect everything
that the CA required the client to do before issuance, even if some
requirements were fulfilled in earlier applications.  For example, if
a CA allows multiple applications to be fufilled based on a single
authorization transaction, then it must reflect that authorization in
all of the applications.
Paragraph (version B):
The status of this requirement.  Possible values are: "pending",
"valid", and "invalid".
Paragraph (version B):
All additional fields are specified by the requirement type.
Paragraph (version B):
A requirement with type "authorization" requests that the ACME client
complete an authorization transaction.  The server specifies the
authorization by pre-provisioning a pending authorization resource
and providing the URI for this resource in the requirement.
Paragraph (version B):
To fulfill this requirement, the ACME client should fetch the
authorization object from the indicated URL, then follow the process
for obtaining authorization as specified in identifier-authorization.
Paragraph (version B):
A requirement with type "out-of-band" requests that the ACME client
have a human user visit a web page in order to receive further
instructions for how to fulfill the requirement.  The requirement
object provides a URI for the web page to be visited.
Paragraph (version B):
To fulfill this requirement, the ACME client should direct the user
to the indicated web page.
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.  Wildcard domain
names (with "*" as the first label) MUST NOT be included in
authorization requests.  See certificate-issuance below for more
information about wildcard domains.
Paragraph (version B):
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.  Wildcard domain
names (with "*" as the first label) MUST NOT be included in
authorization requests.
Paragraph (version A):
The server creates a registration object with the included contact
information.  The "key" element of the registration is set to the
public key used to verify the JWS (i.e., the "jwk" element of the JWS
header).  The server returns this registration object in a 201
(Created) response, with the registration URI in a Location header
field.  The server SHOULD also indicate its new-authorization URI
using the "next" link relation.
Paragraph (version B):
The server creates a registration object with the included contact
information.  The "key" element of the registration is set to the
public key used to verify the JWS (i.e., the "jwk" element of the JWS
header).  The server returns this registration object in a 201
(Created) response, with the registration URI in a Location header
field.
Paragraph (version B):
Servers SHOULD NOT respond to GET requests for registration 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 ({"resource":"reg"}).
Paragraph (version A):
Once an account is deactivated, the server MUST NOT accept further
requests authorized by that account's key.  It is up to server policy
how long to retain data related to that account, whether to revoke
certificates issued by that account, and whether to send email to
that account's contacts.  ACME does not proviate a way to reactivate
a deactivated account.
Paragraph (version B):
Once an account is deactivated, the server MUST NOT accept further
requests authorized by that account's key.  It is up to server policy
how long to retain data related to that account, whether to revoke
certificates issued by that account, and whether to send email to
that account's contacts.  ACME does not provide a way to reactivate a
deactivated account.
Paragraph (version B):
If the server is willing to issue the requested certificate, it
responds with a 201 (Created) response.  The body of this response is
an application object reflecting the client's request and any
requirements the client must fulfill before the certificate will be
issued.
Paragraph (version B):
The application object returned by the server represents a promise
that if the client fulfills the server's requirements before the
"expires" time, then the server will issue the requested certificate.
In the application object, any object in the "requirements" array
whose status is "pending" represents an action that the client must
perform before the server will issue the certificate.  If the client
fails to complete the required actions before the "expires" time,
then the server SHOULD change the status of the application to
"invalid" and MAY delete the application resource.
Paragraph (version B):
The server SHOULD issue the requested certificate and update the
application resource with a URL for the certificate as soon as the
client has fulfilled the server's requirements.  If the client has
already satisfied the server's requirements at the time of this
request (e.g., by obtaining authorization for all of the identifiers
in the certificate in previous transactions), then the server MAY
proactively issue the requested certificate and provide a URL for it
in the "certificate" field of the application.  The server MUST,
however, still list the satisfied requirements in the "requirements"
array, with the state "valid".
Paragraph (version B):
"invalid": The certificate will not be issued.  Consider this
application process abandoned.
Paragraph (version B):
"pending": The server does not believe that the client has
fulfilled the requirements.  Check the "requirements" array for
requirements that are still pending.
Paragraph (version B):
"processing": The server agrees that the requirements have been
fulfilled, and is in the process of generating the certificate.
Retry after the time given in the "Retry-After" header field of
the response, if any.
Paragraph (version B):
"valid": The server has issued the certificate and provisioned its
URL to the "certificate" field of the application.  Download the
certificate.
Paragraph (version B):
To download the issued certificate, the client simply sends a GET
request to the certificate URL.
Paragraph (version B):
The server MUST also provide a link relation header field with
relation "author" to indicate the application under which this
certificate was issued.
Paragraph (version B):
A certificate resource represents a single, immutable certificate.
If the client wishes to obtain a renewed certificate, the client
initiates a new application process to request one.
Paragraph (version A):
The identifier authorization process establishes the authorization of
an account to manage certificates for a given identifier.  This
process must assure the server of two things: First, that the client
controls the private key of the account key pair, and second, that
the client holds the identifier in question.  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).
Paragraph (version A):
As illustrated by the figure in the overview section above, the
authorization process proceeds in two phases.  The client first
requests a new authorization, and the server issues challenges, then
the client responds to those challenges and the server validates the
client's responses.
Paragraph (version A):
To begin the key authorization process, the client sends a POST
request to the server's new-authorization resource.  The body of the
POST request MUST contain a JWS object, whose payload is a partial
authorization object.  This JWS object MUST contain only the
"identifier" field, so that the server knows what identifier is being
authorized.  The server MUST ignore any other fields present in the
client's request object.
Paragraph (version A):
The authorization object is implicitly tied to the account key used
to sign the request.  Once created, the authorization may only be
updated by that account.
Paragraph (version A):
When submitting a new authorization request, the key "existing" with
a string value MAY be included in the resource object.  This object
is not considered part of an authorization resource but controls
request processing as described below.
Paragraph (version A):
If the authorization request specifies "existing" with a value of
"accept" or "require", before proceeding, the server SHOULD determine
if there are any existing authorization resources for the account and
given identifier which are presently valid.  If one or more such
authorizations exists, a response SHOULD returned with status code
303 (See Other) and a Location header pointing to the existing
resource URL; processing of the request then stops.  If there are
multiple such authorizations, the authorization with the latest
expiry date SHOULD be returned.  Otherwise, if the "existing" item
was "require", status code 404 (Not Found) is returned; if it was
"accept" or was any other value or was absent, processing continues
as follows.
Paragraph (version A):
Before processing the authorization further, the server SHOULD
determine whether it is willing to issue certificates for the
identifier.  For example, the server should check that the identifier
is of a supported type.  Servers might also check names against a
blacklist of known high-value identifiers.  If the server is
unwilling to issue for the identifier, it SHOULD return a 403
(Forbidden) error, with a problem document describing the reason for
the rejection.
Paragraph (version A):
If the server is willing to proceed, it builds a pending
authorization object from the initial authorization object submitted
by the client.
Paragraph (version A):
The server allocates a new URI for this authorization, and returns a
201 (Created) response, with the authorization URI in a Location
header field, and the JSON authorization object in the body.
Paragraph (version B):
The identifier authorization process establishes the authorization of
an account to manage certificates for a given identifier.  This
process must assure the server of two things: First, that the client
controls the private key of the account key pair, and second, that
the client holds the identifier in question.  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 application by setting the
"scope" field of the authorization to the URI for that application.
Paragraph (version B):
Authorization resources are created by the server in response to
certificate applications submitted by an account key holder; their
URLs are provided to the client in "authorization" requirement
objects.  The authorization object is implicitly tied to the account
key used to sign the new-application request.
Paragraph (version B):
When a client receives an application from the server with an
"authorization" requirement, it downloads the authorization resource
by sending a GET request to the indicated URL.
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
or the new-authorization URI).  This allows the client to send
information only for challenges it is responding to.
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).  This allows the client to send information only for challenges
it is responding to.
Paragraph (version A):
The holder of an account key pair authorized for one or more
identifiers may use ACME to request that a certificate be issued for
any subset of those identifiers.  The client makes this request by
sending a POST request to the server's new-certificate resource.  The
body of the POST is a JWS object whose JSON payload contains a
Certificate Signing Request (CSR) RFC2986.  The CSR encodes the
parameters of the requested certificate; authority to issue is
demonstrated by the JWS signature by an account key, from which the
server can look up related authorizations.  Some attributes which
cannot be reflected in a CSR are placed directly in the certificate
request.
Paragraph (version A):
It is up to the server's local policy to decide which names are
acceptable in a certificate, given the authorizations that the server
associates with the client's account key.  A server MAY consider a
client authorized for a wildcard domain if it is authorized for the
underlying domain name (without the "*" label).  Servers SHOULD NOT
extend authorization across identifier types.  For example, if a
client is authorized for "example.com", then the server should not
allow the client to issue a certificate with an iPAddress
subjectAltName, even if it contains an IP address to which
example.com resolves.
Paragraph (version A):
If the CA decides to issue a certificate, then the server creates a
new certificate resource and returns a URI for it in the Location
header field of a 201 (Created) response.
Paragraph (version A):
If the certificate is available at the time of the response, it is
provided in the body of the response.  If the CA has not yet issued
the certificate, the body of this response will be empty.  The client
should then send a GET request to the certificate URI to poll for the
certificate.  As long as the certificate is unavailable, the server
MUST provide a 202 (Accepted) response and include a Retry-After
header to indicate when the server believes the certificate will be
issued (as in the example above).
Paragraph (version A):
The server MUST also provide a link relation header field with
relation "author" to indicate the registration under which this
certificate was issued.
Paragraph (version A):
A certificate resource represents a single, immutable certificate.
If the client wishes to obtain a renewed certificate, the client
initiates a new-certificate transaction to request one.
Paragraph (version A):
The status of this authorization.  Possible values are: "pending",
"valid", and "invalid".  If this field is missing, then the
default value is "pending".
Paragraph (version B):
The status of this authorization.  Possible values are: "pending",
"valid", and "invalid".
Paragraph (version A):
ACME allows anyone to request challenges for an identifier by
registering an account key and sending a new-authorization 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-application 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 A):
HTTP: The value provided in the validation request is signed by
the account private key.
Paragraph (version A):
TLS SNI: The validation TLS request uses the account key pair as
the server's key pair.
Paragraph (version A):
DNS: The MAC covers the account key, and the MAC key is derived
from an ECDH public key signed with the account private key.
Paragraph (version B):
All of the challenges above have a binding between the account
private key and the validation query made by the server, via the key
authorization.  The key authorization is signed by the account
private key, reflects the corresponding public key, and is provided
to the server in the validation response.