| ACME Working Group | Y. Sheffer |
| Internet-Draft | Intuit |
| Intended status: Standards Track | D. Lopez |
| Expires: May 16, 2018 | O. Gonzalez de Dios |
| A. Pastor Perales | |
| Telefonica I+D | |
| T. Fossati | |
| Nokia | |
| November 12, 2017 |
Support for Short-Term, Automatically-Renewed (STAR) Certificates in Automated Certificate Management Environment (ACME)
draft-ietf-acme-star-01
This memo proposes an ACME extension to enable the issuance of short-term and automatically renewed certificates.
[RFC Editor: please remove before publication]
While the draft is being developed, the editor’s version can be found at https://github.com/yaronf/I-D/tree/master/STAR.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on May 16, 2018.
Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
The ACME protocol [I-D.ietf-acme-acme] automates the process of issuing a certificate to a Domain Name Owner (DNO). However, if the DNO wishes to obtain a string of short-term certificates originating from the same private key (see [Topalovic] for the rationale), she must go through the whole ACME protocol each time a new short-term certificate is needed - e.g., every 2-3 days. If done this way, the process would involve frequent interactions between the registration function of the ACME Certification Authority (CA) and the user’s backing infrastructure (e.g.: DNS, web servers), therefore making the issuance of short-term certificates exceedingly dependent on the reliability of both.
This document presents an extension of the ACME protocol that optimizes this process by making short-term certificates first class objects in the ACME ecosystem. Once the order for a string of short-term certificates is accepted, the CA is responsible for publishing the next certificate at an agreed upon URL before the previous one expires. The DNO can terminate the automatic renewal before the natural deadline, if needed - e.g., on key compromise.
For a more generic treatment of STAR certificates, readers are referred to [I-D.nir-saag-star].
The proposed mechanism can be used as a building block of an efficient name-delegation protocol, for example one that exists between a CDN or a cloud provider and its users [I-D.sheffer-acme-star-request], in a way that makes the delegator (i.e., the DNO) in full control of the delegation by simply instructing the CA to stop the automatic renewal and letting the currently active certificate expire shortly thereafter.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].
The following subsections describe the three main phases of the protocol:
This diagram presents the entities that are (or may be) involved in the protocol and their interactions during the different phases.
Refresh
. . . . . . . . . . . . . . . . . . . .
. ' ` v
.-----. Bootstrap / Terminate .---------.
| DNO |------------------------------------->| ACME CA |
`-----' `---------'
^ .- - -. ^
` . . . . . . . . : NDC : . . . . . . . . . '
Request `- - -' Refresh
Delegation
Note that there might be a distinct NDC entity (e.g., a CDN edge cache) that uses a separate channel to request the DNO to set up a name delegation. The protocol described in [I-D.sheffer-acme-star-request] might be used for this purpose.
The DNO, in its role as an ACME client, requests the CA to issue a STAR certificate, i.e., one that:
Other than that, the ACME protocol flows as normal between DNO and CA. In particular, DNO is responsible for satisfying the requested ACME challenges until the CA is willing to issue the requested certificate. Per normal ACME processing, the DNO is given back an Order ID for the issued STAR certificate to be used in subsequent interaction with the CA (e.g., if the certificate needs to be terminated.)
The bootstrap phase ends when the DNO obtains the OK from the ACME CA.
The CA automatically re-issues the certificate using the same CSR (and therefore the same name and public key) before it expires and publishes it to the URL that was returned to the DNO at the end of the bootstrap phase. The certificate user, which could be either the DNO itself or a delegated third party, as described in [I-D.sheffer-acme-star-request], obtains the certificate and uses it.
The refresh process (Figure 1) goes on until either:
Certificate ACME/STAR
User Server
| Retrieve cert | [...]
|---------------------->| |
| +------. /
| | | /
| | Automatic renewal :
| | | \
| |<-----' \
| Retrieve cert | |
|---------------------->| 72 hours
| | |
| +------. /
| | | /
| | Automatic renewal :
| | | \
| |<-----' \
| Retrieve cert | |
|---------------------->| 72 hours
| | |
| +------. /
| | | /
| | Automatic renewal :
| | | \
| |<-----' \
| | |
| [...] | [...]
Figure 1: Auto renewal
The DNO may request early termination of the STAR certificate by including the Order ID in a certificate termination request to the ACME interface, defined below. After the CA receives and verifies the request, it shall:
Note that it is not necessary to explicitly revoke the short-term certificate.
STAR STAR ACME/STAR
Client Proxy Server
| | |
| | Terminate Order ID |
| +---------------------->|
| | +-------.
| | | |
| | | End auto renewal
| | | Remove cert link
| | | etc.
| | | |
| | Done |<------'
| |<----------------------+
| | |
| |
| Retrieve cert |
+---------------------------------------------->|
| Error: terminated |
|<----------------------------------------------+
| |
Figure 2: Termination
This section describes the protocol details, namely the extensions to the ACME protocol required to issue STAR certificates.
This protocol extends the ACME protocol, to allow for recurrent orders.
The Order resource is extended with the following attributes:
{
"recurrent": true,
"recurrent-start-date": "2016-01-01T00:00:00Z",
"recurrent-end-date": "2017-01-01T00:00:00Z",
"recurrent-certificate-validity": 604800
}
These attributes are included in a POST message when creating the order, as part of the “payload” encoded object. They are returned when the order has been created, and the ACME server MAY adjust them at will, according to its local policy.
ACME defines the following values for the Order resource’s status: “invalid”, “pending”, “processing”, “valid”. In the case of recurrent orders, the status MUST be “valid” as long as STAR certificates are being issued. We add a new status value, “canceled”, see below.
An important property of the recurrent Order is that it can be canceled by the DNO, with no need for certificate revocation. To cancel the Order, the ACME client sends a POST:
POST /acme/order/1 HTTP/1.1
Host: acme-server.example.org
Content-Type: application/jose+json
{
"protected": base64url({
"alg": "ES256",
"kid": "https://example.com/acme/acct/1",
"nonce": "5XJ1L3lEkMG7tR6pA00clA",
"url": "https://example.com/acme/order/1"
}),
"payload": base64url({
"status": "canceled"
}),
"signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g"
}
The server MUST NOT issue any additional certificates for this Order, beyond the certificate that is available for collection at the time of deletion. Immediately after the Order is canceled, the server SHOULD respond with 403 (Forbidden) to any requests to the certificate endpoint. The response SHOULD provide additional information using a problem document [RFC7807] with type “urn:ietf:params:acme:error:recurrentOrderCanceled”.
ACME supports sending arbitrary extensions when creating an Order, and as a result, there is no need to explicitly indicate support of this extension. The DNO MUST verify that the “recurrent” attribute was understood, as indicated by the “recurrent” attribute included by the CA in the created Order. Since the standard ACME protocol does not allow to explicitly cancel a pending Order (the POST operation in Section 3.1.2 is an extension), a DNO that encounters an non-supporting server will probably let the Order expire instead of following through with the authorization process.
The certificate is fetched from the certificate endpoint, as per [I-D.ietf-acme-acme], Section 7.4.2.
GET /acme/cert/asdf HTTP/1.1 Host: acme-server.example.org Accept: application/pkix-cert HTTP/1.1 200 OK Content-Type: application/pem-certificate-chain Link: <https://example.com/acme/some-directory>;rel="index" Not-Before: Mon, 1 Feb 2016 00:00:00 GMT Not-After: Mon, 8 Feb 2016 00:00:00 GMT -----BEGIN CERTIFICATE----- [End-entity certificate contents] -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- [Issuer certificate contents] -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- [Other certificate contents] -----END CERTIFICATE-----
The Server SHOULD include the “Not-Before” and “Not-After” headers. When they exist, they MUST be equal to the respective fields inside the certificate. Their format is “HTTP-date” as defined in Section 7.1.1.2 of [RFC7231]. Their purpose is to enable client implementations that do not parse the certificate.
To improve robustness, the next certificate MUST be made available by the ACME CA at the latest halfway through the lifetime of the currently active certificate. It is worth noting that this has an implication in case of cancellation: in fact, from the time the next certificate is made available, the cancellation is not completely effective until the latter also expires.
The server MUST NOT issue any additional certificates for this Order beyond its recurrent-end-date.
Immediately after the Order expires, the server SHOULD respond with 403 (Forbidden) to any requests to the certificate endpoint. The response SHOULD provide additional information using a problem document [RFC7807] with type “urn:ietf:params:acme:error:recurrentOrderExpired”.
TBD: larger logs and how to deal with them.
Note to RFC Editor: please remove this section before publication, including the reference to [RFC7942].
This section records the status of known implementations of the protocol defined by this specification at the time of posting of this Internet-Draft, and is based on a proposal described in [RFC7942]. The description of implementations in this section is intended to assist the IETF in its decision processes in progressing drafts to RFCs. Please note that the listing of any individual implementation here does not imply endorsement by the IETF. Furthermore, no effort has been spent to verify the information presented here that was supplied by IETF contributors. This is not intended as, and must not be construed to be, a catalog of available implementations or their features. Readers are advised to note that other implementations may exist.
According to [RFC7942], “this will allow reviewers and working groups to assign due consideration to documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature. It is up to the individual working groups to use this information as they see fit”.
The implementation is constructed around 3 elements: Client STAR for NDC, Proxy STAR for DNO and Server ACME for CA. The communication between them is over an IP network and the HTTPS protocol.
The software of the implementation is available at: https://github.com/mami-project/lurk
The following subsections offer a basic description, detailed information is available in https://github.com/mami-project/lurk/blob/master/proxySTAR_v1/README.md
This is a fork of the Let’s Encrypt Boulder project that implements an ACME compliant CA. It includes modifications to extend the ACME protocol as it is specified in this draft, to support recurrent orders and cancelling orders.
The implementation understands the new “recurrent” attributes as part of the Certificate issuance in the POST request for a new resource. An additional process “renewalManager.go” has been included in parallel that reads the details of each recurrent request, automatically produces a “cron” Linux based task that issues the recurrent certificates, until the lifetime ends or the order is canceled. This process is also in charge of maintaining a fixed URI to enable the NDC to download certificates, unlike Boulder’s regular process of producing a unique URI per certificate.
The Proxy STAR, has a double role as ACME client and STAR Server. The former is a fork of the EFF Certbot project that implements an ACME compliant client with the STAR extension. The latter is a basic HTTP REST API server.
The proxy STAR understands the basic API request with a server. The current implementation of the API is defined in draft-sheffer-acme-star-request-00. Registration or order cancellation triggers the modified Certbot client that requests, or cancels, the recurrent generation of certificates using the STAR extension over ACME protocol. The URI with the location of the recurrent certificate is delivered to the STAR client as a response.
This is a prototype.
Client STAR is not included in this implementation, but done by direct HTTP request with any open HTTP REST API tool. This is expected to be covered as part of [I-D.sheffer-acme-star-request] implementation.
This implementation completely covers Proxy STAR and Server ACME with STAR extension
The implementation is compatible with version draft-ietf-acme-star-00. The implementation is based on the Boulder and Certbot code release from 7-Aug-2017.
This implementation inherits the Boulder license (Mozilla Public License 2.0) and Certbot license (Apache License Version 2.0 ).
To prove the concept all the implementation has been done with a self-signed CA, to avoid impact on real domains. To be able to do it we use the FAKE_DNS property of Boulder and static /etc/hosts entries with domains names. Nonetheless this implementation should run with real domains.
Most of the implementation has been made to avoid deep changes inside of Boulder or Certbot, for example, the recurrent certificates issuance by the CA is based on an external process that auto-configures the standard Linux “cron” daemon in the ACME CA server.
The reference setup recommended is one physical host with 3 virtual machines, one for each of the 3 components (client, proxy and server) and the connectivity based on host bridge.
No security is enabled (iptables default policies are “accept” and all rules removed) in this implementation to simplify and test the protocol.
See author details below.
[[RFC Editor: please replace XXXX below by the RFC number.]]
This document adds the following entry to the ACME Error Type registry:
| Type | Description | Reference |
|---|---|---|
| recurrentOrderCanceled | The short-term certificate is no longer available because the recurrent order has been explicitly canceled by the DNO | RFC XXXX |
| recurrentOrderExpired | The short-term certificate is no longer available because the recurrent order has expired | RFC XXXX |
This document adds the following entries to the ACME Order Object Fields registry:
| Field Name | Field Type | Configurable | Reference |
|---|---|---|---|
| recurrent | string | true | RFC XXXX |
| recurrent-start-date | string | true | RFC XXXX |
| recurrent-end-date | string | true | RFC XXXX |
| recurrent-certificate-validity | string | true | RFC XXXX |
TBD
This work is partially supported by the European Commission under Horizon 2020 grant agreement no. 688421 Measurement and Architecture for a Middleboxed Internet (MAMI). This support does not imply endorsement.
| [I-D.ietf-acme-acme] | Barnes, R., Hoffman-Andrews, J. and J. Kasten, "Automatic Certificate Management Environment (ACME)", Internet-Draft draft-ietf-acme-acme-08, October 2017. |
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997. |
| [RFC3339] | Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002. |
| [RFC7231] | Fielding, R. and J. Reschke, "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 10.17487/RFC7231, June 2014. |
| [RFC7807] | Nottingham, M. and E. Wilde, "Problem Details for HTTP APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016. |
| [I-D.nir-saag-star] | Nir, Y., Fossati, T. and Y. Sheffer, "Considerations For Using Short Term Certificates", Internet-Draft draft-nir-saag-star-00, October 2017. |
| [I-D.sheffer-acme-star-request] | Sheffer, Y., Lopez, D., Dios, O., Pastor, A. and T. Fossati, "Generating Certificate Requests for Short-Term, Automatically-Renewed (STAR) Certificates", Internet-Draft draft-sheffer-acme-star-request-01, June 2017. |
| [RFC7942] | Sheffer, Y. and A. Farrel, "Improving Awareness of Running Code: The Implementation Status Section", BCP 205, RFC 7942, DOI 10.17487/RFC7942, July 2016. |
| [Topalovic] | Topalovic, E., Saeta, B., Huang, L., Jackson, C. and D. Boneh, "Towards Short-Lived Certificates", 2012. |
[[Note to RFC Editor: please remove before publication.]]