Tech-invite   3GPPspecs   Glossaries   IETFRFCs   Groups   SIP   ABNFs   Ti+   Search in Tech-invite

in Index   Prev   Next
in Index   None   None  Group: ACME

RFC 8555

Automatic Certificate Management Environment (ACME)

Pages: 95
Proposed STD
Errata
Part 2 of 6 – Pages 20 to 33
First   Prev   Next

Top   ToC   RFC8555 - Page 20   prevText
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 Revocation

7.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.
Top   ToC   RFC8555 - Page 21
   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
Top   ToC   RFC8555 - Page 22
   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.
Top   ToC   RFC8555 - Page 23
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.
Top   ToC   RFC8555 - Page 24
   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.
Top   ToC   RFC8555 - Page 25
   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.
Top   ToC   RFC8555 - Page 26
   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].
Top   ToC   RFC8555 - Page 27
   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
Top   ToC   RFC8555 - Page 28
   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.
Top   ToC   RFC8555 - Page 29
   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.
Top   ToC   RFC8555 - Page 30
   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
Top   ToC   RFC8555 - Page 31
   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").
Top   ToC   RFC8555 - Page 32
                      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").
Top   ToC   RFC8555 - Page 33
    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 Section