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 3 of 6 – Pages 34 to 53
First   Prev   Next

Top   ToC   Page 34   prevText
7.2.  Getting a Nonce

   Before sending a POST request to the server, an ACME client needs to
   have a fresh anti-replay nonce to put in the "nonce" header of the
   JWS.  In most cases, the client will have gotten a nonce from a
   previous request.  However, the client might sometimes need to get a
   new nonce, e.g., on its first request to the server or if an existing
   nonce is no longer valid.

   To get a fresh nonce, the client sends a HEAD request to the newNonce
   resource on the server.  The server's response MUST include a Replay-
   Nonce header field containing a fresh nonce and SHOULD have status
   code 200 (OK).  The server MUST also respond to GET requests for this
   resource, returning an empty body (while still providing a Replay-
   Nonce header) with a status code of 204 (No Content).

   HEAD /acme/new-nonce HTTP/1.1
   Host: example.com

   HTTP/1.1 200 OK
   Replay-Nonce: oFvnlFP1wIhRlYS2jTaXbA
   Cache-Control: no-store
   Link: <https://example.com/acme/directory>;rel="index"

   Proxy caching of responses from the newNonce resource can cause
   clients to receive the same nonce repeatedly, leading to "badNonce"
   errors.  The server MUST include a Cache-Control header field with
   the "no-store" directive in responses for the newNonce resource, in
   order to prevent caching of this resource.

7.3.  Account Management

   In this section, we describe how an ACME client can create an account
   on an ACME server and perform some modifications to the account after
   it has been created.

   A client creates a new account with the server by sending a POST
   request to the server's newAccount URL.  The body of the request is a
   stub account object containing some subset of the following fields:

   contact (optional, array of string):  Same meaning as the
      corresponding server field defined in Section 7.1.2.

   termsOfServiceAgreed (optional, boolean):  Same meaning as the
      corresponding server field defined in Section 7.1.2.
Top   ToC   Page 35
   onlyReturnExisting (optional, boolean):  If this field is present
      with the value "true", then the server MUST NOT create a new
      account if one does not already exist.  This allows a client to
      look up an account URL based on an account key (see
      Section 7.3.1).

   externalAccountBinding (optional, object):  Same meaning as the
      corresponding server field defined in Section 7.1.2

   POST /acme/new-account HTTP/1.1
   Host: example.com
   Content-Type: application/jose+json

   {
     "protected": base64url({
       "alg": "ES256",
       "jwk": {...},
       "nonce": "6S8IqOGY7eL2lsGoTZYifg",
       "url": "https://example.com/acme/new-account"
     }),
     "payload": base64url({
       "termsOfServiceAgreed": true,
       "contact": [
         "mailto:cert-admin@example.org",
         "mailto:admin@example.org"
       ]
     }),
     "signature": "RZPOnYoPs1PhjszF...-nh6X1qtOFPB519I"
   }

   The server MUST ignore any values provided in the "orders" fields in
   account objects 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 can be
   provided by the client.  The server MUST NOT reflect the
   "onlyReturnExisting" field or any unrecognized fields in the
   resulting account object.  This allows clients to detect when servers
   do not support an extension field.

   The server SHOULD validate that the contact URLs in the "contact"
   field are valid and supported by the server.  If the server validates
   contact URLs, it MUST support the "mailto" scheme.  Clients MUST NOT
   provide a "mailto" URL in the "contact" field that contains "hfields"
   [RFC6068] or more than one "addr-spec" in the "to" component.  If a
   server encounters a "mailto" contact URL that does not meet these
   criteria, then it SHOULD reject it as invalid.
Top   ToC   Page 36
   If the server rejects a contact URL for using an unsupported scheme,
   it MUST return an error of type "unsupportedContact", with a
   description of the error and what types of contact URLs the server
   considers acceptable.  If the server rejects a contact URL for using
   a supported scheme but an invalid value, then the server MUST return
   an error of type "invalidContact".

   If the server wishes to require the client to agree to terms under
   which the ACME service is to be used, it MUST indicate the URL where
   such terms can be accessed in the "termsOfService" subfield of the
   "meta" field in the directory object, and the server MUST reject
   newAccount requests that do not have the "termsOfServiceAgreed" field
   set to "true".  Clients SHOULD NOT automatically agree to terms by
   default.  Rather, they SHOULD require some user interaction for
   agreement to terms.

   The server creates an account and stores the public key used to
   verify the JWS (i.e., the "jwk" element of the JWS header) to
   authenticate future requests from the account.  The server returns
   this account object in a 201 (Created) response, with the account URL
   in a Location header field.  The account URL is used as the "kid"
   value in the JWS authenticating subsequent requests by this account
   (see Section 6.2).  The account URL is also used for requests for
   management actions on this account, as described below.

   HTTP/1.1 201 Created
   Content-Type: application/json
   Replay-Nonce: D8s4D2mLs8Vn-goWuPQeKA
   Link: <https://example.com/acme/directory>;rel="index"
   Location: https://example.com/acme/acct/evOfKhNU60wg

   {
     "status": "valid",

     "contact": [
       "mailto:cert-admin@example.org",
       "mailto:admin@example.org"
     ],

     "orders": "https://example.com/acme/acct/evOfKhNU60wg/orders"
   }

7.3.1.  Finding an Account URL Given a Key

   If the server receives a newAccount request signed with a key for
   which it already has an account registered with the provided account
   key, then it MUST return a response with status code 200 (OK) and
   provide the URL of that account in the Location header field.  The
Top   ToC   Page 37
   body of this response represents the account object as it existed on
   the server before this request; any fields in the request object MUST
   be ignored.  This allows a client that has an account key but not the
   corresponding account URL to recover the account URL.

   If a client wishes to find the URL for an existing account and does
   not want an account to be created if one does not already exist, then
   it SHOULD do so by sending a POST request to the newAccount URL with
   a JWS whose payload has an "onlyReturnExisting" field set to "true"
   ({"onlyReturnExisting": true}).  If a client sends such a request and
   an account does not exist, then the server MUST return an error
   response with status code 400 (Bad Request) and type
   "urn:ietf:params:acme:error:accountDoesNotExist".

7.3.2.  Account Update

   If the client wishes to update this information in the future, it
   sends a POST request with updated information to the account URL.
   The server MUST ignore any updates to the "orders" field,
   "termsOfServiceAgreed" field (see Section 7.3.3), the "status" field
   (except as allowed by Section 7.3.6), or any other fields it does not
   recognize.  If the server accepts the update, it MUST return a
   response with a 200 (OK) status code and the resulting account
   object.

   For example, to update the contact information in the above account,
   the client could send the following request:

   POST /acme/acct/evOfKhNU60wg HTTP/1.1
   Host: example.com
   Content-Type: application/jose+json

   {
     "protected": base64url({
       "alg": "ES256",
       "kid": "https://example.com/acme/acct/evOfKhNU60wg",
       "nonce": "ax5RnthDqp_Yf4_HZnFLmA",
       "url": "https://example.com/acme/acct/evOfKhNU60wg"
     }),
     "payload": base64url({
       "contact": [
         "mailto:certificates@example.org",
         "mailto:admin@example.org"
       ]
     }),
     "signature": "hDXzvcj8T6fbFbmn...rDzXzzvzpRy64N0o"
   }
Top   ToC   Page 38
7.3.3.  Changes of Terms of Service

   As described above, a client can indicate its agreement with the CA's
   terms of service by setting the "termsOfServiceAgreed" field in its
   account object to "true".

   If the server has changed its terms of service since a client
   initially agreed, and the server is unwilling to process a request
   without explicit agreement to the new terms, then it MUST return an
   error response with status code 403 (Forbidden) and type
   "urn:ietf:params:acme:error:userActionRequired".  This response MUST
   include a Link header field with link relation "terms-of-service" and
   the latest terms-of-service URL.

   The problem document returned with the error MUST also include an
   "instance" field, indicating a URL that the client should direct a
   human user to visit in order for instructions on how to agree to the
   terms.

 HTTP/1.1 403 Forbidden
 Replay-Nonce: T81bdZroZ2ITWSondpTmAw
 Link: <https://example.com/acme/directory>;rel="index"
 Link: <https://example.com/acme/terms/2017-6-02>;rel="terms-of-service"
 Content-Type: application/problem+json
 Content-Language: en

 {
   "type": "urn:ietf:params:acme:error:userActionRequired",
   "detail": "Terms of service have changed",
   "instance": "https://example.com/acme/agreement/?token=W8Ih3PswD-8"
 }

7.3.4.  External Account Binding

   The server MAY require a value for the "externalAccountBinding" field
   to be present in "newAccount" requests.  This can be used to
   associate an ACME account with an existing account in a non-ACME
   system, such as a CA customer database.

   To enable ACME account binding, the CA operating the ACME server
   needs to provide the ACME client with a MAC key and a key identifier,
   using some mechanism outside of ACME.  The key identifier MUST be an
   ASCII string.  The MAC key SHOULD be provided in base64url-encoded
   form, to maximize compatibility between non-ACME provisioning systems
   and ACME clients.
Top   ToC   Page 39
   The ACME client then computes a binding JWS to indicate the external
   account holder's approval of the ACME account key.  The payload of
   this JWS is the ACME account key being registered, in JWK form.  The
   protected header of the JWS MUST meet the following criteria:

   o  The "alg" field MUST indicate a MAC-based algorithm

   o  The "kid" field MUST contain the key identifier provided by the CA

   o  The "nonce" field MUST NOT be present

   o  The "url" field MUST be set to the same value as the outer JWS

   The "signature" field of the JWS will contain the MAC value computed
   with the MAC key provided by the CA.

   POST /acme/new-account HTTP/1.1
   Host: example.com
   Content-Type: application/jose+json

   {
     "protected": base64url({
       "alg": "ES256",
       "jwk": /* account key */,
       "nonce": "K60BWPrMQG9SDxBDS_xtSw",
       "url": "https://example.com/acme/new-account"
     }),
     "payload": base64url({
       "contact": [
         "mailto:cert-admin@example.org",
         "mailto:admin@example.org"
       ],
       "termsOfServiceAgreed": true,

       "externalAccountBinding": {
         "protected": base64url({
           "alg": "HS256",
           "kid": /* key identifier from CA */,
           "url": "https://example.com/acme/new-account"
         }),
         "payload": base64url(/* same as in "jwk" above */),
         "signature": /* MAC using MAC key from CA */
       }
     }),
     "signature": "5TWiqIYQfIDfALQv...x9C2mg8JGPxl5bI4"
   }
Top   ToC   Page 40
   If such a CA requires that newAccount requests contain an
   "externalAccountBinding" field, then it MUST provide the value "true"
   in the "externalAccountRequired" subfield of the "meta" field in the
   directory object.  If the CA receives a newAccount request without an
   "externalAccountBinding" field, then it SHOULD reply with an error of
   type "externalAccountRequired".

   When a CA receives a newAccount request containing an
   "externalAccountBinding" field, it decides whether or not to verify
   the binding.  If the CA does not verify the binding, then it MUST NOT
   reflect the "externalAccountBinding" field in the resulting account
   object (if any).  To verify the account binding, the CA MUST take the
   following steps:

   1.  Verify that the value of the field is a well-formed JWS

   2.  Verify that the JWS protected field meets the above criteria

   3.  Retrieve the MAC key corresponding to the key identifier in the
       "kid" field

   4.  Verify that the MAC on the JWS verifies using that MAC key

   5.  Verify that the payload of the JWS represents the same key as was
       used to verify the outer JWS (i.e., the "jwk" field of the outer
       JWS)

   If all of these checks pass and the CA creates a new account, then
   the CA may consider the new account associated with the external
   account corresponding to the MAC key.  The account object the CA
   returns MUST include an "externalAccountBinding" field with the same
   value as the field in the request.  If any of these checks fail, then
   the CA MUST reject the newAccount request.

7.3.5.  Account Key Rollover

   A client may wish to change the public key that is associated with an
   account in order to recover from a key compromise or proactively
   mitigate the impact of an unnoticed key compromise.

   To change the key associated with an account, the client sends a
   request to the server containing signatures by both the old and new
   keys.  The signature by the new key covers the account URL and the
   old key, signifying a request by the new key holder to take over the
   account from the old key holder.  The signature by the old key covers
   this request and its signature, and indicates the old key holder's
   assent to the rollover request.
Top   ToC   Page 41
   To create this request object, the client first constructs a
   keyChange object describing the account to be updated and its account
   key:

   account (required, string):  The URL for the account being modified.
      The content of this field MUST be the exact string provided in the
      Location header field in response to the newAccount request that
      created the account.

   oldKey (required, JWK):  The JWK representation of the old key.

   The client then encapsulates the keyChange object in an "inner" JWS,
   signed with the requested new account key.  This "inner" JWS becomes
   the payload for the "outer" JWS that is the body of the ACME request.

   The outer JWS MUST meet the normal requirements for an ACME JWS
   request body (see Section 6.2).  The inner JWS MUST meet the normal
   requirements, with the following differences:

   o  The inner JWS MUST have a "jwk" header parameter, containing the
      public key of the new key pair.

   o  The inner JWS MUST have the same "url" header parameter as the
      outer JWS.

   o  The inner JWS MUST omit the "nonce" header parameter.

   This transaction has signatures from both the old and new keys so
   that the server can verify that the holders of the two keys both
   agree to the change.  The signatures are nested to preserve the
   property that all signatures on POST messages are signed by exactly
   one key.  The "inner" JWS effectively represents a request by the
   holder of the new key to take over the account form the holder of the
   old key.  The "outer" JWS represents the current account holder's
   assent to this request.
Top   ToC   Page 42
   POST /acme/key-change HTTP/1.1
   Host: example.com
   Content-Type: application/jose+json

   {
     "protected": base64url({
       "alg": "ES256",
       "kid": "https://example.com/acme/acct/evOfKhNU60wg",
       "nonce": "S9XaOcxP5McpnTcWPIhYuB",
       "url": "https://example.com/acme/key-change"
     }),
     "payload": base64url({
       "protected": base64url({
         "alg": "ES256",
         "jwk": /* new key */,
         "url": "https://example.com/acme/key-change"
       }),
       "payload": base64url({
         "account": "https://example.com/acme/acct/evOfKhNU60wg",
         "oldKey": /* old key */
       }),
       "signature": "Xe8B94RD30Azj2ea...8BmZIRtcSKPSd8gU"
     }),
     "signature": "5TWiqIYQfIDfALQv...x9C2mg8JGPxl5bI4"
   }

   On receiving a keyChange request, the server MUST perform the
   following steps in addition to the typical JWS validation:

   1.  Validate the POST request belongs to a currently active account,
       as described in Section 6.

   2.  Check that the payload of the JWS is a well-formed JWS object
       (the "inner JWS").

   3.  Check that the JWS protected header of the inner JWS has a "jwk"
       field.

   4.  Check that the inner JWS verifies using the key in its "jwk"
       field.

   5.  Check that the payload of the inner JWS is a well-formed
       keyChange object (as described above).

   6.  Check that the "url" parameters of the inner and outer JWSs are
       the same.
Top   ToC   Page 43
   7.  Check that the "account" field of the keyChange object contains
       the URL for the account matching the old key (i.e., the "kid"
       field in the outer JWS).

   8.  Check that the "oldKey" field of the keyChange object is the same
       as the account key for the account in question.

   9.  Check that no account exists whose account key is the same as the
       key in the "jwk" header parameter of the inner JWS.

   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 (OK).  Otherwise, the server
   responds with an error status code and a problem document describing
   the error.  If there is an existing account with the new key
   provided, then the server SHOULD use status code 409 (Conflict) and
   provide the URL of that account in the Location header field.

   Note that changing the account key for an account SHOULD NOT have any
   other impact on the account.  For example, the server MUST NOT
   invalidate pending orders or authorization transactions based on a
   change of account key.

7.3.6.  Account Deactivation

   A client can deactivate an account by posting a signed update to the
   account URL with a status field of "deactivated".  Clients may wish
   to do this when the account key is compromised or decommissioned.  A
   deactivated account can no longer request certificate issuance or
   access resources related to the account, such as orders or
   authorizations.  If a server receives a POST or POST-as-GET from a
   deactivated account, it MUST return an error response with status
   code 401 (Unauthorized) and type
   "urn:ietf:params:acme:error:unauthorized".
Top   ToC   Page 44
   POST /acme/acct/evOfKhNU60wg HTTP/1.1
   Host: example.com
   Content-Type: application/jose+json

   {
     "protected": base64url({
       "alg": "ES256",
       "kid": "https://example.com/acme/acct/evOfKhNU60wg",
       "nonce": "ntuJWWSic4WVNSqeUmshgg",
       "url": "https://example.com/acme/acct/evOfKhNU60wg"
     }),
     "payload": base64url({
       "status": "deactivated"
     }),
     "signature": "earzVLd3m5M4xJzR...bVTqn7R08AKOVf3Y"
   }

   The server MUST verify that the request is signed by the account key.
   If the server accepts the deactivation request, it replies with a 200
   (OK) status code and the current contents of the account object.

   Once an account is deactivated, the server MUST NOT accept further
   requests authorized by that account's key.  The server SHOULD cancel
   any pending operations authorized by the account's key, such as
   certificate orders.  A server may take a variety of actions in
   response to an account deactivation, e.g., deleting data related to
   that account or sending mail to the account's contacts.  Servers
   SHOULD NOT revoke certificates issued by the deactivated account,
   since this could cause operational disruption for servers using these
   certificates.  ACME does not provide a way to reactivate a
   deactivated account.

7.4.  Applying for Certificate Issuance

   The client begins the certificate issuance process by sending a POST
   request to the server's newOrder resource.  The body of the POST is a
   JWS object whose JSON payload is a subset of the order object defined
   in Section 7.1.3, containing the fields that describe the certificate
   to be issued:

   identifiers (required, array of object):  An array of identifier
      objects that the client wishes to submit an order for.

      type (required, string):  The type of identifier.

      value (required, string):  The identifier itself.
Top   ToC   Page 45
   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].

   POST /acme/new-order HTTP/1.1
   Host: example.com
   Content-Type: application/jose+json

   {
     "protected": base64url({
       "alg": "ES256",
       "kid": "https://example.com/acme/acct/evOfKhNU60wg",
       "nonce": "5XJ1L3lEkMG7tR6pA00clA",
       "url": "https://example.com/acme/new-order"
     }),
     "payload": base64url({
       "identifiers": [
         { "type": "dns", "value": "www.example.org" },
         { "type": "dns", "value": "example.org" }
       ],
       "notBefore": "2016-01-01T00:04:00+04:00",
       "notAfter": "2016-01-08T00:04:00+04:00"
     }),
     "signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g"
   }

   The server MUST return an error if it cannot fulfill the request as
   specified, and it MUST NOT issue a certificate with contents other
   than those requested.  If the server requires the request to be
   modified in a certain way, it should indicate the required changes
   using an appropriate error type and description.

   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.
Top   ToC   Page 46
   HTTP/1.1 201 Created
   Replay-Nonce: MYAuvOpaoIiywTezizk5vw
   Link: <https://example.com/acme/directory>;rel="index"
   Location: https://example.com/acme/order/TOlocE8rfgo

   {
     "status": "pending",
     "expires": "2016-01-05T14:09:07.99Z",

     "notBefore": "2016-01-01T00:00:00Z",
     "notAfter": "2016-01-08T00:00:00Z",

     "identifiers": [
       { "type": "dns", "value": "www.example.org" },
       { "type": "dns", "value": "example.org" }
     ],

     "authorizations": [
       "https://example.com/acme/authz/PAniVnsZcis",
       "https://example.com/acme/authz/r4HqLzrSrpI"
     ],

     "finalize": "https://example.com/acme/order/TOlocE8rfgo/finalize"
   }

   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 be willing to finalize the order upon
   request and issue the requested certificate.  In the order object,
   any authorization referenced 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 Section 7.5).  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.
   Clients MUST NOT make any assumptions about the sort order of
   "identifiers" or "authorizations" elements in the returned order
   object.
Top   ToC   Page 47
   Once the client believes it has fulfilled the server's requirements,
   it should send a POST request to the order resource's finalize URL.
   The POST body MUST include a CSR:

   csr (required, string):  A CSR encoding the parameters for the
      certificate being requested [RFC2986].  The CSR is sent in the
      base64url-encoded version of the DER format.  (Note: Because this
      field uses base64url, and does not include headers, it is
      different from PEM.)

   POST /acme/order/TOlocE8rfgo/finalize HTTP/1.1
   Host: example.com
   Content-Type: application/jose+json

   {
     "protected": base64url({
       "alg": "ES256",
       "kid": "https://example.com/acme/acct/evOfKhNU60wg",
       "nonce": "MSF2j2nawWHPxxkE3ZJtKQ",
       "url": "https://example.com/acme/order/TOlocE8rfgo/finalize"
     }),
     "payload": base64url({
       "csr": "MIIBPTCBxAIBADBFMQ...FS6aKdZeGsysoCo4H9P",
     }),
     "signature": "uOrUfIIk5RyQ...nw62Ay1cl6AB"
   }

   The CSR encodes the client's requests with regard to the content of
   the certificate to be issued.  The CSR MUST indicate the exact same
   set of requested identifiers as the initial newOrder request.
   Identifiers of type "dns" MUST appear either in the commonName
   portion of the requested subject name or in an extensionRequest
   attribute [RFC2985] requesting a subjectAltName extension, or both.
   (These identifiers may appear in any sort order.)  Specifications
   that define new identifier types must specify where in the
   certificate signing request these identifiers can appear.

   A request to finalize an order will result in an error if the CA is
   unwilling to issue a certificate corresponding to the submitted CSR.
   For example:

   o  If the CSR and order identifiers differ

   o  If the account is not authorized for the identifiers indicated in
      the CSR

   o  If the CSR requests extensions that the CA is not willing to
      include
Top   ToC   Page 48
   In such cases, the problem document returned by the server SHOULD use
   error code "badCSR" and describe specific reasons the CSR was
   rejected in its "detail" field.  After returning such an error, the
   server SHOULD leave the order in the "ready" state, to allow the
   client to submit a new finalize request with an amended CSR.

   A request to finalize an order will result in error if the order is
   not in the "ready" state.  In such cases, the server MUST return a
   403 (Forbidden) error with a problem document of type
   "orderNotReady".  The client should then send a POST-as-GET request
   to the order resource to obtain its current state.  The status of the
   order will indicate what action the client should take (see below).

   If a request to finalize an order is successful, the server will
   return a 200 (OK) with an updated order object.  The status of the
   order will indicate what action the client should take:

   o  "invalid": The certificate will not be issued.  Consider this
      order process abandoned.

   o  "pending": The server does not believe that the client has
      fulfilled the requirements.  Check the "authorizations" array for
      entries that are still pending.

   o  "ready": The server agrees that the requirements have been
      fulfilled, and is awaiting finalization.  Submit a finalization
      request.

   o  "processing": The certificate is being issued.  Send a POST-as-GET
      request after the time given in the Retry-After header field of
      the response, if any.

   o  "valid": The server has issued the certificate and provisioned its
      URL to the "certificate" field of the order.  Download the
      certificate.
Top   ToC   Page 49
   HTTP/1.1 200 OK
   Replay-Nonce: CGf81JWBsq8QyIgPCi9Q9X
   Link: <https://example.com/acme/directory>;rel="index"
   Location: https://example.com/acme/order/TOlocE8rfgo

   {
     "status": "valid",
     "expires": "2016-01-20T14:09:07.99Z",

     "notBefore": "2016-01-01T00:00:00Z",
     "notAfter": "2016-01-08T00:00:00Z",

     "identifiers": [
       { "type": "dns", "value": "www.example.org" },
       { "type": "dns", "value": "example.org" }
     ],

     "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"
   }

7.4.1.  Pre-authorization

   The order process described above presumes that authorization objects
   are created reactively, in response to a certificate order.  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
   virtual servers are created and only create a certificate when a
   virtual server starts up.

   In some cases, a CA running an ACME server might have a completely
   external, non-ACME process for authorizing a client to issue
   certificates for an identifier.  In these cases, the CA should
   provision its ACME server with authorization objects corresponding to
   these authorizations and reflect them as already valid in any orders
   submitted by the client.

   If a CA wishes to allow pre-authorization within ACME, it can offer a
   "new authorization" resource in its directory by adding the field
   "newAuthz" with a URL for the newAuthz resource.
Top   ToC   Page 50
   To request authorization for an identifier, the client sends a POST
   request to the newAuthz resource specifying the identifier for which
   authorization is being requested.

   identifier (required, object):  The identifier to appear in the
      resulting authorization object (see Section 7.1.4).

      type (required, string):  The type of identifier.

      value (required, string):  The identifier itself.

   POST /acme/new-authz HTTP/1.1
   Host: example.com
   Content-Type: application/jose+json

   {
     "protected": base64url({
       "alg": "ES256",
       "kid": "https://example.com/acme/acct/evOfKhNU60wg",
       "nonce": "uQpSjlRb4vQVCjVYAyyUWg",
       "url": "https://example.com/acme/new-authz"
     }),
     "payload": base64url({
       "identifier": {
         "type": "dns",
         "value": "example.org"
       }
     }),
     "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps"
   }

   Note that because the identifier in a pre-authorization request is
   the exact identifier to be included in the authorization object, pre-
   authorization cannot be used to authorize issuance of certificates
   containing wildcard domain names.

   Before processing the authorization request, 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 an error with
   status code 403 (Forbidden), with a problem document describing the
   reason for the rejection.
Top   ToC   Page 51
   If the server is willing to proceed, it builds a pending
   authorization object from the inputs submitted by the client:

   o  "identifier" the identifier submitted by the client

   o  "status" MUST be "pending" unless the server has out-of-band
      information about the client's authorization status

   o  "challenges" as selected by the server's policy for this
      identifier

   The server allocates a new URL for this authorization and returns a
   201 (Created) response with the authorization URL in the Location
   header field and the JSON authorization object in the body.  The
   client then follows the process described in Section 7.5 to complete
   the authorization process.

7.4.2.  Downloading the Certificate

   To download the issued certificate, the client simply sends a POST-
   as-GET request to the certificate URL.

   The default format of the certificate is application/pem-certificate-
   chain (see Section 9).

   The server MAY provide one or more link relation header fields
   [RFC8288] with relation "alternate".  Each such field SHOULD express
   an alternative certificate chain starting with the same end-entity
   certificate.  This can be used to express paths to various trust
   anchors.  Clients can fetch these alternates and use their own
   heuristics to decide which is optimal.
Top   ToC   Page 52
   POST /acme/cert/mAt3xBGaobw HTTP/1.1
   Host: example.com
   Content-Type: application/jose+json
   Accept: application/pem-certificate-chain

   {
     "protected": base64url({
       "alg": "ES256",
       "kid": "https://example.com/acme/acct/evOfKhNU60wg",
       "nonce": "uQpSjlRb4vQVCjVYAyyUWg",
       "url": "https://example.com/acme/cert/mAt3xBGaobw"
     }),
     "payload": "",
     "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps"
   }

   HTTP/1.1 200 OK
   Content-Type: application/pem-certificate-chain
   Link: <https://example.com/acme/directory>;rel="index"

   -----BEGIN CERTIFICATE-----
   [End-entity certificate contents]
   -----END CERTIFICATE-----
   -----BEGIN CERTIFICATE-----
   [Issuer certificate contents]
   -----END CERTIFICATE-----
   -----BEGIN CERTIFICATE-----
   [Other certificate contents]
   -----END CERTIFICATE-----

   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.

   Because certificate resources are immutable once issuance is
   complete, the server MAY enable the caching of the resource by adding
   Expires and Cache-Control header fields specifying a point in time in
   the distant future.  These header fields have no relation to the
   certificate's period of validity.

   The ACME client MAY request other formats by including an Accept
   header field [RFC7231] in its request.  For example, the client could
   use the media type "application/pkix-cert" [RFC2585] or "application/
   pkcs7-mime" [RFC5751] to request the end-entity certificate in DER
   format.  Server support for alternate formats is OPTIONAL.  For
   formats that can only express a single certificate, the server SHOULD
Top   ToC   Page 53
   provide one or more "Link: rel="up"" header fields pointing to an
   issuer or issuers so that ACME clients can build a certificate chain
   as defined in TLS (see Section 4.4.2 of [RFC8446]).



(page 53 continued on part 4)

Next Section