RFC 8555
Automatic Certificate Management Environment (ACME)
7. Certificate Management
In this section, we describe the certificate management functions that ACME enables: o Account Creation o Ordering a Certificate o Identifier Authorization o Certificate Issuance o Certificate Revocation7.1. Resources
ACME is structured as an HTTP-based application with the following types of resources: o Account resources, representing information about an account (Section 7.1.2, Section 7.3) o Order resources, representing an account's requests to issue certificates (Section 7.1.3) o Authorization resources, representing an account's authorization to act for an identifier (Section 7.1.4) o Challenge resources, representing a challenge to prove control of an identifier (Section 7.5, Section 8) o Certificate resources, representing issued certificates (Section 7.4.2) o A "directory" resource (Section 7.1.1) o A "newNonce" resource (Section 7.2) o A "newAccount" resource (Section 7.3) o A "newOrder" resource (Section 7.4) o A "revokeCert" resource (Section 7.6) o A "keyChange" resource (Section 7.3.5) The server MUST provide "directory" and "newNonce" resources.
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 [RFC8288]. The "up" link relation is used with challenge resources to indicate the authorization resource to which a challenge belongs. It is also used, with some media types, from certificate resources to indicate a resource from which the client may fetch a chain of CA certificates that could be used to validate the certificate in the original resource. The "index" link relation is present on all resources other than the directory and indicates the URL of the directory. The following diagram illustrates the relations between resources on an ACME server. For the most part, these relations are expressed by URLs provided as strings in the resources' JSON representations. Lines with labels in quotes indicate HTTP link relations. directory | +--> newNonce | +----------+----------+-----+-----+------------+ | | | | | | | | | | V V V V V newAccount newAuthz newOrder revokeCert keyChange | | | | | | V | V account | order --+--> finalize | | | | | +--> cert | V +---> authorization | ^ | | "up" V | challenge ACME Resources and Relationships
The following table illustrates a typical sequence of requests required to establish a new account with the server, prove control of an identifier, issue a certificate, and fetch an updated certificate some time after issuance. The "->" is a mnemonic for a Location header field pointing to a created resource. +-------------------+--------------------------------+--------------+ | Action | Request | Response | +-------------------+--------------------------------+--------------+ | Get directory | GET directory | 200 | | | | | | Get nonce | HEAD newNonce | 200 | | | | | | Create account | POST newAccount | 201 -> | | | | account | | | | | | Submit order | POST newOrder | 201 -> order | | | | | | Fetch challenges | POST-as-GET order's | 200 | | | authorization urls | | | | | | | Respond to | POST authorization challenge | 200 | | challenges | urls | | | | | | | Poll for status | POST-as-GET order | 200 | | | | | | Finalize order | POST order's finalize url | 200 | | | | | | Poll for status | POST-as-GET order | 200 | | | | | | Download | POST-as-GET order's | 200 | | certificate | certificate url | | +-------------------+--------------------------------+--------------+ The remainder of this section provides the details of how these resources are structured and how the ACME protocol makes use of them.
7.1.1. Directory
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 resource registry (Section 9.7.5) and whose values are the corresponding URLs. +------------+--------------------+ | Field | URL in Value | +------------+--------------------+ | newNonce | New nonce | | | | | newAccount | New account | | | | | newOrder | New order | | | | | newAuthz | New authorization | | | | | revokeCert | Revoke certificate | | | | | keyChange | Key change | +------------+--------------------+ There is no constraint on the URL of the directory except that it should be different from the other ACME server resources' URLs, and that it should not clash with other services. For instance: o a host that functions as both an ACME and a Web server may want to keep the root path "/" for an HTML "front page" and place the ACME directory under the path "/acme". o a host that only functions as an ACME server could place the directory under the path "/". If the ACME server does not implement pre-authorization (Section 7.4.1), it MUST omit the "newAuthz" field of the directory. The object MAY additionally contain a "meta" field. If present, it MUST be a JSON object; each field in the object is an item of metadata relating to the service provided by the ACME server. The following metadata items are defined (Section 9.7.6), all of which are OPTIONAL: termsOfService (optional, string): A URL identifying the current terms of service.
website (optional, string): An HTTP or HTTPS URL locating a website
providing more information about the ACME server.
caaIdentities (optional, array of string): The hostnames that the
ACME server recognizes as referring to itself for the purposes of
CAA record validation as defined in [RFC6844]. Each string MUST
represent the same sequence of ASCII code points that the server
will expect to see as the "Issuer Domain Name" in a CAA issue or
issuewild property tag. This allows clients to determine the
correct issuer domain name to use when configuring CAA records.
externalAccountRequired (optional, boolean): If this field is
present and set to "true", then the CA requires that all
newAccount requests include an "externalAccountBinding" field
associating the new account with an external account.
Clients access the directory by sending a GET request to the
directory URL.
HTTP/1.1 200 OK
Content-Type: application/json
{
"newNonce": "https://example.com/acme/new-nonce",
"newAccount": "https://example.com/acme/new-account",
"newOrder": "https://example.com/acme/new-order",
"newAuthz": "https://example.com/acme/new-authz",
"revokeCert": "https://example.com/acme/revoke-cert",
"keyChange": "https://example.com/acme/key-change",
"meta": {
"termsOfService": "https://example.com/acme/terms/2017-5-30",
"website": "https://www.example.com/",
"caaIdentities": ["example.com"],
"externalAccountRequired": false
}
}
7.1.2. Account Objects
An ACME account resource represents a set of metadata associated with
an account. Account resources have the following structure:
status (required, string): The status of this account. Possible
values are "valid", "deactivated", and "revoked". The value
"deactivated" should be used to indicate client-initiated
deactivation whereas "revoked" should be used to indicate server-
initiated deactivation. See Section 7.1.6.
contact (optional, array of string): An array of URLs that the
server can use to contact the client for issues related to this
account. For example, the server may wish to notify the client
about server-initiated revocation or certificate expiration. For
information on supported URL schemes, see Section 7.3.
termsOfServiceAgreed (optional, boolean): Including this field in a
newAccount request, with a value of true, indicates the client's
agreement with the terms of service. This field cannot be updated
by the client.
externalAccountBinding (optional, object): Including this field in a
newAccount request indicates approval by the holder of an existing
non-ACME account to bind that account to this ACME account. This
field is not updateable by the client (see Section 7.3.4).
orders (required, string): A URL from which a list of orders
submitted by this account can be fetched via a POST-as-GET
request, as described in Section 7.1.2.1.
{
"status": "valid",
"contact": [
"mailto:cert-admin@example.org",
"mailto:admin@example.org"
],
"termsOfServiceAgreed": true,
"orders": "https://example.com/acme/orders/rzGoeA"
}
7.1.2.1. Orders List
Each account object includes an "orders" URL from which a list of
orders created by the account can be fetched via POST-as-GET request.
The result of the 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 field with a
"next" link relation indicating where further entries can be
acquired.
HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://example.com/acme/directory>;rel="index"
Link: <https://example.com/acme/orders/rzGoeA?cursor=2>;rel="next"
{
"orders": [
"https://example.com/acme/order/TOlocE8rfgo",
"https://example.com/acme/order/4E16bbL5iSw",
/* more URLs not shown for example brevity */
"https://example.com/acme/order/neBHYLfw0mg"
]
}
7.1.3. Order Objects
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.
status (required, string): The status of this order. Possible
values are "pending", "ready", "processing", "valid", and
"invalid". See Section 7.1.6.
expires (optional, string): The timestamp after which the server
will consider this order invalid, encoded in the format specified
in [RFC3339]. This field is REQUIRED for objects with "pending"
or "valid" in the status field.
identifiers (required, array of object): An array of identifier
objects that the order pertains to.
type (required, string): The type of identifier. This document
defines the "dns" identifier type. See the registry defined in
Section 9.7.7 for any others.
value (required, string): The identifier itself.
notBefore (optional, string): The requested value of the notBefore
field in the certificate, in the date format defined in [RFC3339].
notAfter (optional, string): The requested value of the notAfter
field in the certificate, in the date format defined in [RFC3339].
error (optional, object): The error that occurred while processing
the order, if any. This field is structured as a problem document
[RFC7807].
authorizations (required, array of string): For pending orders, the
authorizations that the client needs to complete before the
requested certificate can be issued (see Section 7.5), including
unexpired authorizations that the client has completed in the past
for identifiers specified in the order. The authorizations
required are dictated by server policy; there may not be a 1:1
relationship between the order identifiers and the authorizations
required. 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 POST-as-GET request.
finalize (required, string): A URL that a CSR must be POSTed to once
all of the order's authorizations are satisfied to finalize the
order. The result of a successful finalization will be the
population of the certificate URL for the order.
certificate (optional, string): A URL for the certificate that has
been issued in response to this order.
{
"status": "valid",
"expires": "2016-01-20T14:09:07.99Z",
"identifiers": [
{ "type": "dns", "value": "www.example.org" },
{ "type": "dns", "value": "example.org" }
],
"notBefore": "2016-01-01T00:00:00Z",
"notAfter": "2016-01-08T00:00:00Z",
"authorizations": [
"https://example.com/acme/authz/PAniVnsZcis",
"https://example.com/acme/authz/r4HqLzrSrpI"
],
"finalize": "https://example.com/acme/order/TOlocE8rfgo/finalize",
"certificate": "https://example.com/acme/cert/mAt3xBGaobw"
}
Any identifier of type "dns" in a newOrder request MAY have a
wildcard domain name as its value. A wildcard domain name consists
of a single asterisk character followed by a single full stop
character ("*.") followed by a domain name as defined for use in the
Subject Alternate Name Extension by [RFC5280]. An authorization
returned by the server for a wildcard domain name identifier MUST NOT
include the asterisk and full stop ("*.") prefix in the authorization
identifier value. The returned authorization MUST include the
optional "wildcard" field, with a value of true.
The elements of the "authorizations" and "identifiers" arrays are
immutable once set. The server MUST NOT change the contents of
either array after they are created. If a client observes a change
in the contents of either array, then it SHOULD consider the order
invalid.
The "authorizations" array of the order 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 fulfilled based on a single authorization transaction,
then it SHOULD reflect that authorization in all of the orders.
Note that just because an authorization URL is listed in the
"authorizations" array of an order object doesn't mean that the
client is required to take action. There are several reasons that
the referenced authorizations may already be valid:
o The client completed the authorization as part of a previous order
o The client previously pre-authorized the identifier (see
Section 7.4.1)
o The server granted the client authorization based on an external
account
Clients SHOULD check the "status" field of an order to determine
whether they need to take any action.
7.1.4. Authorization Objects
An ACME authorization object represents a server's authorization for
an account to represent an identifier. In addition to the
identifier, an authorization includes several metadata fields, such
as the status of the authorization (e.g., "pending", "valid", or
"revoked") and which challenges were used to validate possession of
the identifier.
The structure of an ACME authorization resource is as follows:
identifier (required, object): The identifier that the account is
authorized to represent.
type (required, string): The type of identifier (see below and
Section 9.7.7).
value (required, string): The identifier itself.
status (required, string): The status of this authorization.
Possible values are "pending", "valid", "invalid", "deactivated",
"expired", and "revoked". See Section 7.1.6.
expires (optional, string): The timestamp after which the server
will consider this authorization invalid, encoded in the format
specified in [RFC3339]. This field is REQUIRED for objects with
"valid" in the "status" field.
challenges (required, array of objects): For pending authorizations,
the challenges that the client can fulfill in order to prove
possession of the identifier. For valid authorizations, the
challenge that was validated. For invalid authorizations, the
challenge that was attempted and failed. 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.
wildcard (optional, boolean): This field MUST be present and true
for authorizations created as a result of a newOrder request
containing a DNS identifier with a value that was a wildcard
domain name. For other authorizations, it MUST be absent.
Wildcard domain names are described in Section 7.1.3.
The only type of identifier defined by this specification is a fully
qualified domain name (type: "dns"). The domain name MUST be encoded
in the form in which it would appear in a certificate. That is, it
MUST be encoded according to the rules in Section 7 of [RFC5280].
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. If an
authorization object conveys authorization for the base domain of a
newOrder DNS identifier containing a wildcard domain name, then the
optional authorizations "wildcard" field MUST be present with a value
of true.
Section 8 describes a set of challenges for domain name validation. { "status": "valid", "expires": "2015-03-01T14:09:07.99Z", "identifier": { "type": "dns", "value": "www.example.org" }, "challenges": [ { "url": "https://example.com/acme/chall/prV_B7yEyA4", "type": "http-01", "status": "valid", "token": "DGyRejmCefe7v4NfDGDKfA", "validated": "2014-12-01T12:05:58.16Z" } ], "wildcard": false }7.1.5. Challenge Objects
An ACME challenge object represents a server's offer to validate a client's possession of an identifier in a specific way. Unlike the other objects listed above, there is not a single standard structure for a challenge object. The contents of a challenge object depend on the validation method being used. The general structure of challenge objects and an initial set of validation methods are described in Section 8.7.1.6. Status Changes
Each ACME object type goes through a simple state machine over its lifetime. The "status" field of the object indicates which state the object is currently in. Challenge objects are created in the "pending" state. They transition to the "processing" state when the client responds to the challenge (see Section 7.5.1) and the server begins attempting to validate that the client has completed the challenge. Note that within the "processing" state, the server may attempt to validate the challenge multiple times (see Section 8.2). Likewise, client
requests for retries do not cause a state change. If validation is
successful, the challenge moves to the "valid" state; if there is an
error, the challenge moves to the "invalid" state.
pending
|
| Receive
| response
V
processing <-+
| | | Server retry or
| | | client retry request
| +----+
|
|
Successful | Failed
validation | validation
+---------+---------+
| |
V V
valid invalid
State Transitions for Challenge Objects
Authorization objects are created in the "pending" state. If one of
the challenges listed in the authorization transitions to the "valid"
state, then the authorization also changes to the "valid" state. If
the client attempts to fulfill a challenge and fails, or if there is
an error while the authorization is still pending, then the
authorization transitions to the "invalid" state. Once the
authorization is in the "valid" state, it can expire ("expired"), be
deactivated by the client ("deactivated", see Section 7.5.2), or
revoked by the server ("revoked").
pending --------------------+
| |
Challenge failure | |
or | |
Error | Challenge valid |
+---------+---------+ |
| | |
V V |
invalid valid |
| |
| |
| |
+--------------+--------------+
| | |
| | |
Server | Client | Time after |
revoke | deactivate | "expires" |
V V V
revoked deactivated expired
State Transitions for Authorization Objects
Order objects are created in the "pending" state. Once all of the
authorizations listed in the order object are in the "valid" state,
the order transitions to the "ready" state. The order moves to the
"processing" state after the client submits a request to the order's
"finalize" URL and the CA begins the issuance process for the
certificate. Once the certificate is issued, the order enters the
"valid" state. If an error occurs at any of these stages, the order
moves to the "invalid" state. The order also moves to the "invalid"
state if it expires or one of its authorizations enters a final state
other than "valid" ("expired", "revoked", or "deactivated").
pending --------------+
| |
| All authz |
| "valid" |
V |
ready ---------------+
| |
| Receive |
| finalize |
| request |
V |
processing ------------+
| |
| Certificate | Error or
| issued | Authorization failure
V V
valid invalid
State Transitions for Order Objects
Account objects are created in the "valid" state, since no further
action is required to create an account after a successful newAccount
request. If the account is deactivated by the client or revoked by
the server, it moves to the corresponding state.
valid
|
|
+-----------+-----------+
Client | Server |
deactiv.| revoke |
V V
deactivated revoked
State Transitions for Account Objects
Note that some of these states may not ever appear in a "status"
field, depending on server behavior. For example, a server that
issues synchronously will never show an order in the "processing"
state. A server that deletes expired authorizations immediately will
never show an authorization in the "expired" state.
(next page on part 3)
