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 automatically renewed Orders.
The Order resource is extended with a new "auto-renewal" object that MUST
be present for STAR certificates. The "auto-renewal" object has the following structure:
start-date (optional, string): The earliest date of validity of the first certificate issued, in [RFC 3339] format. When omitted, the start date is as soon as authorization is complete.
end-date (required, string): The latest date of validity of the last certificate issued, in [RFC 3339] format.
lifetime (required, integer): The maximum validity period of each STAR certificate, an integer that denotes a number of seconds. This is a nominal value that does not include any extra validity time due to server or client adjustment (see below).
lifetime-adjust (optional, integer): The amount of "left pad" added to each STAR certificate, an integer that denotes a number of seconds. The default is 0. If present, the value of the notBefore field that would otherwise appear in the STAR certificates is pre-dated by the specified number of seconds. See Section 4.1 for why a client might want to use this control, and Section 3.5 for how the effective certificate lifetime is computed. The value reflected by the server, together with the value of the lifetime attribute, can be used by the client as a hint to configure its polling timer.
allow-certificate-get (optional, boolean): See Section 3.4.
These attributes are included in a POST message when creating the Order as part of the object encoded as "payload". They are returned when the Order has been created. The ACME server MAY
adjust them at will according to its local policy (see also Section 3.2
The optional notBefore and notAfter fields defined in Section 7.1.3
of RFC 8555 MUST NOT
be present in a STAR Order. If they are included, the server MUST
return an error with status code 400 (Bad Request) and type "malformedRequest".
of RFC 8555
defines the following values for the Order resource's status: "pending", "ready", "processing", "valid", and "invalid". In the case of auto-renewal Orders, the status MUST
be "valid" as long as STAR certificates are being issued. This document adds a new status value: "canceled" (see Section 3.1.2
A STAR certificate is by definition a dynamic resource, i.e., it refers to an entity that varies over time. Instead of overloading the semantics of the "certificate" attribute, this document defines a new attribute, "star-certificate", to be used instead of "certificate".
star-certificate (optional, string): A URL for the (rolling) STAR certificate that has been issued in response to this Order.
An important property of the auto-renewal Order is that it can be canceled by the IdO with no need for certificate revocation. To cancel the Order, the ACME client sends a POST to the Order URL as shown in Figure 3
POST /acme/order/ogfr8EcolOT HTTP/1.1
After a successful cancellation, the server MUST NOT
issue any additional certificates for this Order.
When the Order is canceled, the server:
MUST update the status of the Order resource to "canceled" and MUST set an appropriate "expires" date;
MUST respond with 403 (Forbidden) to any requests to the star-certificate endpoint. The response SHOULD provide additional information using a problem document [RFC 7807] with type "urn:ietf:params:acme:error:autoRenewalCanceled".
Issuing a cancellation for an Order that is not in "valid" state is not allowed. A client MUST NOT
send such a request, and a server MUST
return an error response with status code 400 (Bad Request) and type "urn:ietf:params:acme:error:autoRenewalCancellationInvalid".
The state machine described in Section 7.1.6
of RFC 8555
is extended as illustrated in Figure 4
| All authz |
| "valid" |
| Receive |
| finalize |
| request |
| First |
| certificate | Error or
| issued | Authorization failure
| STAR |
| Certificate | Natural
| canceled | Expiration
Explicit certificate revocation using the revokeCert interface (Section 7.6
of RFC 8555
) is not supported for STAR certificates. A server receiving a revocation request for a STAR certificate MUST
return an error response with status code 403 (Forbidden) and type "urn:ietf:params:acme:error:autoRenewalRevocationNotSupported".
In order to support the discovery of STAR capabilities, the "meta" field inside the directory object defined in Section 9.7.6
of RFC 8555
is extended with a new "auto-renewal" object. The "auto-renewal" object MUST
be present if the server supports STAR. Its structure is as follows:
min-lifetime (required, integer): Minimum acceptable value for auto-renewal lifetime, in seconds.
max-duration (required, integer): Maximum allowed delta between the end-date and start-date attributes of the Order's auto-renewal object.
allow-certificate-get (optional, boolean): See Section 3.4.
An example directory object advertising STAR support with one-day min-lifetime and one-year max-duration and supporting certificate fetching with an HTTP GET is shown in Figure 5
The certificate is fetched from the star-certificate endpoint with POST-as-GET as per Section 7.4.2
of RFC 8555
unless the client and server have successfully negotiated the "unauthenticated GET" option described in Section 3.4
. In such case, the client can simply issue a GET to the star-certificate resource without authenticating itself to the server as illustrated in Figure 6
GET /acme/cert/g7m3ZQeTEqa HTTP/1.1
HTTP/1.1 200 OK
Cert-Not-Before: Thu, 3 Oct 2019 00:00:00 GMT
Cert-Not-After: Thu, 10 Oct 2019 00:00:00 GMT
[End-entity certificate contents]
[Issuer certificate contents]
[Other certificate contents]
The server SHOULD
include the "Cert-Not-Before" and "Cert-Not-After" HTTP header fields in the response. When they exist, they MUST
be equal to the respective fields inside the end-entity certificate. Their format is "HTTP-date" as defined in Section 188.8.131.52
of RFC 7231
. Their purpose is to enable client implementations that do not parse the certificate.
The following are further clarifications regarding usage of these header fields as per Section 8.3.1
of RFC 7231
. All apply to both headers.
This header field is a single value, not a list.
The header field is used only in responses to GET, HEAD, and POST-as-GET requests, and only for MIME types that denote public key certificates.
Header field semantics are independent of context.
The header field is not hop-by-hop.
Intermediaries MAY insert or delete the value;
If an intermediary inserts the value, it MUST ensure that the newly added value matches the corresponding value in the certificate.
The header field is not appropriate for a Vary field.
The header field is allowed within message trailers.
The header field is not appropriate within redirects.
The header field does not introduce additional security considerations. It discloses in a simpler form information that is already available inside the certificate.
To improve robustness, the next certificate MUST
be made available by the ACME CA at the URL indicated by "star-certificate" halfway through the lifetime of the currently active certificate at the latest. 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 "next" certificate also expires. To avoid the client accidentally entering a broken state, the notBefore of the "next" certificate MUST
be set so that the certificate is already valid when it is published at the "star-certificate" URL. Note that the server might need to increase the auto-renewal lifetime-adjust value to satisfy the latter requirement. For a detailed description of the renewal scheduling logic, see Section 3.5
. For further rationale on the need for adjusting the certificate validity, see Section 4.1
The server MUST NOT
issue any certificates for this Order with notAfter after the auto-renewal end-date.
For expired Orders, the server MUST
respond with 403 (Forbidden) to any requests to the star-certificate endpoint. The response SHOULD
provide additional information using a problem document [RFC 7807
] with type "urn:ietf:params:acme:error:autoRenewalExpired". Note that the Order resource's state remains "valid", as per the base protocol.
In order to enable the name delegation workflow defined in [STAR-DELEGATION
] and to increase the reliability of the STAR ecosystem (see Section 4.3
for details), this document defines a mechanism that allows a server to advertise support for accessing star-certificate resources via unauthenticated GET (in addition to POST-as-GET), and a client to enable this service with per-Order granularity.
Specifically, a server states its availability to grant unauthenticated access to a client's Order star-certificate by setting the allow-certificate-get attribute to "true" in the auto-renewal object of the meta field inside the directory object:
allow-certificate-get (optional, boolean): If this field is present and set to "true", the server allows GET (and HEAD) requests to star-certificate URLs.
A client states its desire to access the issued star-certificate via unauthenticated GET by adding an allow-certificate-get attribute to the auto-renewal object of the payload of its newOrder request and setting it to "true".
allow-certificate-get (optional, boolean): If this field is present and set to "true", the client requests the server to allow unauthenticated GET (and HEAD) to the star-certificate associated with this Order.
If the server accepts the request, it MUST
reflect the attribute setting in the resulting order object.
Note that even when the use of unauthenticated GET has been agreed upon, the server MUST
also allow POST-as-GET requests to the star-certificate resource.
We define "nominal renewal date" as the point in time when a new short-term certificate for a given STAR Order is due. Its cadence is a multiple of the Order's auto-renewal lifetime that starts with the issuance of the first short-term certificate and is upper-bounded by the Order's auto-renewal end-date (Figure 7
T - STAR Order's auto-renewal lifetime
end - STAR Order's auto-renewal end-date
nrd[i] - nominal renewal date of the i-th STAR certificate
.- T -. .- T -. .- T -. .__.
/ \ / \ / \ / end
nrd nrd nrd nrd
The rules to determine the notBefore and notAfter values of the i-th STAR certificate are as follows:
notAfter = min(nrd[i] + T, end)
notBefore = nrd[i] - max(adjust_client, adjust_server)
Where "adjust_client" is the minimum value between the auto-renewal lifetime-adjust value ("la"), optionally supplied by the client, and the auto-renewal lifetime of each short-term certificate ("T"); "adjust_server" is the amount of padding added by the ACME server to make sure that all certificates being published are valid at the time of publication. The server padding is a fraction (f) of T (i.e., f * T with .5 <= f < 1; see Section 3.3
adjust_client = min(T, la)
adjust_server = f * T
Note that the ACME server MUST NOT
set the notBefore of the first STAR certificate to a date prior to the auto-renewal start-date.
Given a server that intends to publish the next STAR certificate halfway through the lifetime of the previous one, and a STAR Order with the following attributes:
"lifetime": 345600, // 4 days
"lifetime-adjust": 259200 // 3 days
The amount of time that needs to be subtracted from each nominal renewal date is 3 days, i.e., max(min(345600, 259200), 345600 * .5).
The notBefore and notAfter of each short-term certificate are:
The value of the notBefore is also the time at which the client should expect the new certificate to be available from the star-certificate endpoint.