Draft: draft-ietf-acme-acme

Commentary: As discussed on list and at IETF 97 : " application " -"order " " registration " -"account " Note that this is based on top of , so the diff is bigger than it should be .
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):
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):
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 account object echoing the client's input.
Paragraph (version B):
The client's order 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 A):
For the singular resources above ("directory", "new-nonce", "new-
registration", "new-application", "revoke-certificate", and "key-
change") the resource may be addressed by multiple URIs, but all must
provide equivalent functionality.
Paragraph (version B):
For the singular resources above ("directory", "new-nonce", "new-
account", "new-order", "revoke-certificate", and "key-change") the
resource may be addressed by multiple URIs, but all must provide
equivalent functionality.
Paragraph (version A):
The status of this registration.  Possible values are: "valid",
"deactivated", and "revoked". "deactivated" should be used to
indicate user initiated deactivation whereas "revoked" should be
used to indicate administratively initiated deactivation.
Paragraph (version A):
Including this field in a new-registration request, with a value
of true, indicates the client's agreement with the terms of
service.  This field is not updateable by the client.
Paragraph (version A):
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.  This field is not updateable by the client.
Paragraph (version A):
Each registration object includes an applications URI from which a
list of applications created by the registration can be fetched via
GET request.  The result of the GET request MUST be a JSON object
whose "applications" field is an array of URIs, each identifying an
applications belonging to the registration.  The server SHOULD
include pending applications, and SHOULD NOT include applications
that are invalid in the array of URIs.  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 A):
An ACME application object 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 A):
The status of this application.  Possible values are: "pending",
"valid", and "invalid".
Paragraph (version A):
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 status of this account.  Possible values are: "valid",
"deactivated", and "revoked".  The value "deactivated" should be
used to indicate user initiated deactivation whereas "revoked"
should be used to indicate administratively initiated
deactivation.
Paragraph (version B):
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 is not updateable by the client.
Paragraph (version B):
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 link
relation "next" indicating a URL to retrieve further entries.
Paragraph (version B):
An ACME order object represents a client's request for a certificate,
and is used to track the progress of that order through to issuance.
Thus, the object contains information about the requested
certificate, the authorizations that the server requires the client
to complete, and any certificates that have resulted from this order.
Paragraph (version B):
The status of this order.  Possible values are: "pending",
"valid", and "invalid".
Paragraph (version B):
The timestamp after which the server will consider this order
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 A):
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 A):
A URL for the certificate that has been issued in response to this
application.
Paragraph (version A):
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 A):
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 A):
The status of this requirement.  Possible values are: "pending",
"valid", and "invalid".
Paragraph (version A):
All additional fields are specified by the requirement type.
Paragraph (version A):
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 A):
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 A):
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 A):
To fulfill this requirement, the ACME client should direct the user
to the indicated web page.
Paragraph (version B):
The status of the authorization.  This field MUST have the same
value as it does in the underlying authorization object.
Paragraph (version B):
A URL from which the authorization can be fetched with a GET
request.
Paragraph (version B):
A URL for the certificate that has been issued in response to this
order.
Paragraph (version B):
The elements of the "authorizations" 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
order invalid.
Paragraph (version B):
The "authorizations" array in the challenge SHOULD reflect all
authorizations that the CA takes into account in deciding to issue,
even if some authorizations were fulfilled in earlier orders or in
pre-authorization transactions.  For example, if a CA allows multiple
orders to be fufilled based on a single authorization transaction,
then it SHOULD reflect that authorization in all of the order.
Paragraph (version A):
A client creates a new account with the server by sending a POST
request to the server's new-registration URI.  The body of the
request is a stub registration object containing only the "contact"
field.
Paragraph (version A):
The server MUST ignore any values provided in the "key", and
"applications" fields in registration bodies sent by the client, as
well as any other fields that it does not recognize.  If new fields
are specified in the future, the specification of those fields MUST
describe whether they may be provided by the client.
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 only the "contact" field.
Paragraph (version B):
The server MUST ignore any values provided in the "key", and "orders"
fields in account bodies sent by the client, as well as any other
fields that it does not recognize.  If new fields are specified in
the future, the specification of those fields MUST describe whether
they may be provided by the client.
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.
Paragraph (version A):
If the server already has a registration object with the provided
account key, then it MUST return a 200 (OK) response and provide the
URI of that registration in a Content-Location header field.  This
allows a client that has an account key but not the corresponding
registration URI to recover the registration 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-
registration requests that do not have the "terms-of-service-agreed"
set to "true".
Paragraph (version A):
If the client wishes to update this information in the future, it
sends a POST request with updated information to the registration
URI.  The server MUST ignore any updates to the "key", or
"applications" fields or any other fields it does not recognize.  The
server MUST verify that the request is signed with the private key
corresponding to the "key" field of the request before updating the
registration.
Paragraph (version A):
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 ({}).
Paragraph (version B):
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 B):
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 a 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):
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".
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 URI.
The server MUST ignore any updates to the "key", or "order" fields or
any other fields it does not recognize.  The server MUST verify that
the request is signed with the private key corresponding to the "key"
field of the request before updating the registration.
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 trivial ({}).
Paragraph (version A):
As described above, a client can indicate its agreement with the CA's
terms of service by setting the "terms-of-service-agreed" field in
its registration object to "true".
Paragraph (version B):
As described above, a client can indicate its agreement with the CA's
terms of service by setting the "terms-of-service-agreed" field in
its account object to "true".
Paragraph (version A):
A client may wish to change the public key that is associated with a
registration in order to recover from a key compromise or proactively
mitigate the impact of an unnoticed key compromise.
Paragraph (version B):
A client may wish to change the public key that is associated with a
account in order to recover from a key compromise or proactively
mitigate the impact of an unnoticed key compromise.
Paragraph (version A):
The URL for account being modified.  The content of this field
MUST be the exact string provided in the Location header field in
response to the new-registration request that created the account.
Paragraph (version B):
The URL for 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 A):
If all of these checks pass, then the server updates the
corresponding registration by replacing the old account key with the
new public key and returns status code 200.  Otherwise, the server
responds with an error status code and a problem document describing
the error.
Paragraph (version B):
If all of these checks pass, then the server updates the
corresponding account by replacing the old account key with the new
public key and returns status code 200.  Otherwise, the server
responds with an error status code and a problem document describing
the error.
Paragraph (version A):
The server MUST verify that the request is signed by the account key.
If the server accepts the deactivation request, it should reply with
a 200 (OK) status code and the current contents of the registration
object.
Paragraph (version B):
The server MUST verify that the request is signed by the account key.
If the server accepts the deactivation request, it should reply with
a 200 (OK) status code and the current contents of the account
object.
Paragraph (version A):
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 A):
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 A):
The server MUST 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 MUST
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 A):
"invalid": The certificate will not be issued.  Consider this
application process abandoned.
Paragraph (version A):
"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):
If the server is willing to issue the requested certificate, it
responds with a 201 (Created) response.  The body of this response is
an order object reflecting the client's request and any
authorizations the client must complete before the certificate will
be issued.
Paragraph (version B):
The order 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
order object, any object in the "authorizations" array whose status
is "pending" represents an authorization transaction that the client
must complete before the server will issue the certificate (see
identifier-authorization).  If the client fails to complete the
required actions before the "expires" time, then the server SHOULD
change the status of the order to "invalid" and MAY delete the order
resource.
Paragraph (version B):
The server MUST issue the requested certificate and update the order
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 MUST
proactively issue the requested certificate and provide a URL for it
in the "certificate" field of the order.  The server MUST, however,
still list the completed authorizations in the "authorizations"
array, with the state "valid".
Paragraph (version B):
"invalid": The certificate will not be issued.  Consider this
order process abandoned.
Paragraph (version B):
"pending": The server does not believe that the client has
fulfilled the requirements.  Check the "authorizations" array for
entries that are still pending.
Paragraph (version A):
"valid": The server has issued the certificate and provisioned its
URL to the "certificate" field of the application.  Download the
certificate.
Paragraph (version A):
The application process described above presumes that authorization
objects are created reactively, in response to an application for
issuance.  Some servers may also wish to enable clients to obtain
authorization for an identifier proactively, outside of the context
of a specific issuance.  For example, a client hosting virtual
servers for a collection of names might wish to obtain authorization
before any servers are created, and only create a certificate when a
server starts up.
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 case, the CA should provision its ACME server
with authorization objects corresponding to these authorizations and
reflect them as already-valid requirements in any issuance
applications requested by the client.
Paragraph (version B):
"valid": The server has issued the certificate and provisioned its
URL to the "certificate" field of the order.  Download the
certificate.
Paragraph (version B):
The order process described above presumes that authorization objects
are created reactively, in response to an application for issuance.
Some servers may also wish to enable clients to obtain authorization
for an identifier proactively, outside of the context of a specific
issuance.  For example, a client hosting virtual servers for a
collection of names might wish to obtain authorization before any
servers are created, and only create a certificate when a server
starts up.
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 for an
identifier.  In these case, 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 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):
The server MUST also provide a link relation header field with
relation "author" to indicate the order 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 application process to request one.
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 order 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).  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 A):
Authorization resources are created by the server in response to
certificate applications or authorization requests submitted by an
account key holder; their URLs are provided to the client in the
responses to these requests.  The authorization object is implicitly
tied to the account key used to sign the request.
Paragraph (version A):
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.  If the client
initiates authorization using a request to the new authorization
resource, it will have already recevied the pending authorization
object in the response to that request.
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 order by setting the
"scope" field of the authorization to the URI for that order.
Paragraph (version B):
Authorization resources are created by the server in response to
certificate orders or authorization requests submitted by an account
key holder; their URLs are provided to the client in the responses to
these requests.  The authorization object is implicitly tied to the
account key used to sign the request.
Paragraph (version B):
When a client receives an order from the server with "pending" entry
in the authorizations array, 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 recevied the pending authorization
object in the response to that request.
Paragraph (version A):
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 B):
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.