rfc9773v1.txt		rfc9773.txt
	skipping to change at line 52 ¶		skipping to change at line 52 ¶
	include Revised BSD License text as described in Section 4.e of the		include Revised BSD License text as described in Section 4.e of the
	Trust Legal Provisions and are provided without warranty as described		Trust Legal Provisions and are provided without warranty as described
	in the Revised BSD License.		in the Revised BSD License.
	Table of Contents		Table of Contents
	1. Introduction		1. Introduction
	2. Conventions and Definitions		2. Conventions and Definitions
	3. Extensions to the Directory Object		3. Extensions to the Directory Object
	4. Getting Renewal Information		4. Getting Renewal Information
	4.1. The "renewalInfo" Resource		4.1. The RenewalInfo Resource
	4.2. RenewalInfo Objects		4.2. RenewalInfo Objects
	4.3. Schedule for Checking the RenewalInfo Resource		4.3. Schedule for Checking the RenewalInfo Resource
	4.3.1. Server Choice of Retry-After		4.3.1. Server Choice of Retry-After
	4.3.2. Client Handling of Retry-After		4.3.2. Client Handling of Retry-After
	4.3.3. Error Handling		4.3.3. Error Handling
	5. Extensions to the Order Object		5. Extensions to the Order Object
	6. Security Considerations		6. Security Considerations
	7. IANA Considerations		7. IANA Considerations
	7.1. ACME Resource Type		7.1. ACME Resource Type
	7.2. ACME Renewal Info Object Fields		7.2. ACME RenewalInfo Object Fields
	7.3. ACME Order Object Fields		7.3. ACME Order Object Fields
	7.4. ACME Error Types		7.4. ACME Error Types
	8. References		8. References
	8.1. Normative References		8.1. Normative References
	8.2. Informative References		8.2. Informative References
	Appendix A. Example Certificate		Appendix A. Example Certificate
	Acknowledgments		Acknowledgments
	Author's Address		Author's Address
	1. Introduction		1. Introduction
	skipping to change at line 128 ¶		skipping to change at line 128 ¶
	"Modification" as defined in [RFC3647].		"Modification" as defined in [RFC3647].
	This document assumes that the certificates being issued by the ACME		This document assumes that the certificates being issued by the ACME
	server are in compliance with [RFC5280] and, in particular, contain		server are in compliance with [RFC5280] and, in particular, contain
	the Authority Key Identifier extension and the keyIdentifier field		the Authority Key Identifier extension and the keyIdentifier field
	within that extension.		within that extension.
	3. Extensions to the Directory Object		3. Extensions to the Directory Object
	An ACME server that wishes to provide renewal information MUST		An ACME server that wishes to provide renewal information MUST
	include a new field, renewalInfo, in its directory object.		include a new field, "renewalInfo", in its directory object.
	+=============+==============+		+=============+=====================+
	| Field | URL in Value |		| Field | URL in Value |
	+=============+==============+		+=============+=====================+
	| renewalInfo | Renewal info |		| renewalInfo | Renewal information |
	+-------------+--------------+		+-------------+---------------------+
	Table 1		Table 1
	HTTP/1.1 200 OK		HTTP/1.1 200 OK
	Content-Type: application/json		Content-Type: application/json
	{		{
	"newNonce": "https://acme.example.com/new-nonce",		"newNonce": "https://acme.example.com/new-nonce",
	"newAccount": "https://acme.example.com/new-account",		"newAccount": "https://acme.example.com/new-account",
	"newOrder": "https://acme.example.com/new-order",		"newOrder": "https://acme.example.com/new-order",
	"newAuthz": "https://acme.example.com/new-authz",		"newAuthz": "https://acme.example.com/new-authz",
	"revokeCert": "https://acme.example.com/revoke-cert",		"revokeCert": "https://acme.example.com/revoke-cert",
	skipping to change at line 159 ¶		skipping to change at line 159 ¶
	"meta": {		"meta": {
	"termsOfService": "https://example.com/acme/terms",		"termsOfService": "https://example.com/acme/terms",
	"website": "https://example.com/acme/docs",		"website": "https://example.com/acme/docs",
	"caaIdentities": ["example.com"],		"caaIdentities": ["example.com"],
	"externalAccountRequired": false		"externalAccountRequired": false
	}		}
	}		}
	4. Getting Renewal Information		4. Getting Renewal Information
	4.1. The "renewalInfo" Resource		4.1. The RenewalInfo Resource
	The "renewalInfo" resource is a new resource type introduced to the		The RenewalInfo resource is a new resource type introduced to the
	ACME protocol. This new resource allows clients to query the server		ACME protocol. This new resource allows clients to query the server
	for suggestions on when they should renew certificates.		for suggestions on when they should renew certificates.
	To request the suggested renewal information for a certificate, the		To request the suggested renewal information for a certificate, the
	client sends an unauthenticated GET request to a path under the		client sends an unauthenticated GET request to a path under the
	server's renewalInfo URL.		server's renewalInfo URL.
	The path component is a unique identifier for the certificate in		The path component is a unique identifier for the certificate in
	question. The unique identifier is constructed by concatenating the		question. The unique identifier is constructed by concatenating the
	base64url-encoding [RFC4648] of the keyIdentifier field of the		base64url encoding [RFC4648] of the keyIdentifier field of the
	certificate's Authority Key Identifier (AKI) [RFC5280] extension, the		certificate's Authority Key Identifier (AKI) [RFC5280] extension, the
	period character ".", and the base64url-encoding of the DER-encoded		period character ".", and the base64url encoding of the DER-encoded
	Serial Number field (without the tag and length bytes). All trailing		Serial Number field (without the tag and length bytes). All trailing
	"=" characters MUST be stripped from both parts of the unique		"=" characters MUST be stripped from both parts of the unique
	identifier.		identifier.
	Thus, the full request URL is constructed as follows (split onto		Thus, the full request URL is constructed as follows (split onto
	multiple lines for readability), where the "||" operator indicates		multiple lines for readability), where the "||" operator indicates
	string concatenation and the renewalInfo URL is taken from the		string concatenation and the renewalInfo URL is taken from the
	Directory object:		Directory object:
	url = renewalInfo || '/' ||		url = renewalInfo || '/' ||
	skipping to change at line 212 ¶		skipping to change at line 212 ¶
	the separator, the unique identifier is therefore		the separator, the unique identifier is therefore
	aYhba4dGQEHhs3uEe6CuLN4ByNQ.AIdlQyE, and the client makes the		aYhba4dGQEHhs3uEe6CuLN4ByNQ.AIdlQyE, and the client makes the
	request:		request:
	GET /renewal-info/aYhba4dGQEHhs3uEe6CuLN4ByNQ.AIdlQyE HTTP/1.1		GET /renewal-info/aYhba4dGQEHhs3uEe6CuLN4ByNQ.AIdlQyE HTTP/1.1
	Host: acme.example.com		Host: acme.example.com
	Accept: application/json		Accept: application/json
	4.2. RenewalInfo Objects		4.2. RenewalInfo Objects
	The structure of an ACME renewalInfo resource is as follows:		The structure of an ACME RenewalInfo object is as follows:
	suggestedWindow (object, required):		suggestedWindow (object, required):
	A JSON object with two keys, "start" and "end", whose values are		A JSON object with two keys, "start" and "end", whose values are
	timestamps, encoded in the format specified in [RFC3339], which		timestamps, encoded in the format specified in [RFC3339], which
	bound the window of time in which the CA recommends renewing the		bound the window of time in which the CA recommends renewing the
	certificate.		certificate.
	explanationURL (string, optional):		explanationURL (string, optional):
	A URL pointing to a page that may explain why the suggested		A URL pointing to a page that may explain why the suggested
	renewal window has its current value. For example, it may be a		renewal window has its current value. For example, it may be a
	skipping to change at line 244 ¶		skipping to change at line 244 ¶
	"start": "2025-01-02T04:00:00Z",		"start": "2025-01-02T04:00:00Z",
	"end": "2025-01-03T04:00:00Z"		"end": "2025-01-03T04:00:00Z"
	},		},
	"explanationURL": "https://acme.example.com/docs/ari"		"explanationURL": "https://acme.example.com/docs/ari"
	}		}
	Clients MUST attempt renewal at a time of their choosing based on the		Clients MUST attempt renewal at a time of their choosing based on the
	suggested renewal window. The following algorithm is RECOMMENDED for		suggested renewal window. The following algorithm is RECOMMENDED for
	choosing a renewal time:		choosing a renewal time:
	1. Query the renewalInfo resource to get a suggested renewal window.		1. Make a renewalInfo request to get a suggested renewal window.
	2. Select a uniform random time within the suggested window.		2. Select a uniform random time within the suggested window.
	3. If the selected time is in the past, attempt renewal immediately.		3. If the selected time is in the past, attempt renewal immediately.
	4. Otherwise, if the client can schedule itself to attempt renewal		4. Otherwise, if the client can schedule itself to attempt renewal
	at exactly the selected time, do so.		at exactly the selected time, do so.
	5. Otherwise, if the selected time is before the next time that the		5. Otherwise, if the selected time is before the next time that the
	client would wake up normally, attempt renewal immediately.		client would wake up normally, attempt renewal immediately.
	skipping to change at line 302 ¶		skipping to change at line 302 ¶
	RenewalInfo after they consider the certificate to be replaced (for		RenewalInfo after they consider the certificate to be replaced (for
	instance, after a new certificate for the same identifiers has been		instance, after a new certificate for the same identifiers has been
	received and configured).		received and configured).
	4.3.1. Server Choice of Retry-After		4.3.1. Server Choice of Retry-After
	Servers set the Retry-After header based on their requirements on how		Servers set the Retry-After header based on their requirements on how
	quickly to perform a revocation. For instance, a server that needs		quickly to perform a revocation. For instance, a server that needs
	to revoke certificates within 24 hours of notification of a problem		to revoke certificates within 24 hours of notification of a problem
	might choose to reserve twelve hours for investigation, six hours for		might choose to reserve twelve hours for investigation, six hours for
	clients to fetch RenewalInfo, and six hours for clients to perform a		clients to fetch updated RenewalInfo objects, and six hours for
	renewal. Setting a small value for Retry-After means that clients		clients to perform a renewal. Setting a small value for Retry-After
	can respond more quickly but also incurs more load on the server.		means that clients can respond more quickly but also incurs more load
	Servers should estimate their expected load based on the number of		on the server. Servers should estimate their expected load based on
	clients, keeping in mind that third parties may also monitor		the number of clients, keeping in mind that third parties may also
	RenewalInfo endpoints.		monitor renewalInfo endpoints.
	4.3.2. Client Handling of Retry-After		4.3.2. Client Handling of Retry-After
	After an initial fetch of a certificate's RenewalInfo, clients MUST		After an initial fetch of a certificate's RenewalInfo, clients MUST
	fetch it again as soon as possible after the time indicated in the		fetch it again as soon as possible after the time indicated in the
	Retry-After header (backoff on errors takes priority, though).		Retry-After header (backoff on errors takes priority, though).
	Clients MUST set reasonable limits on their checking interval. For		Clients MUST set reasonable limits on their checking interval. For
	example, values under one minute could be treated as if they were one		example, values under one minute could be treated as if they were one
	minute, and values over one day could be treated as if they were one		minute, and values over one day could be treated as if they were one
	day.		day.
	skipping to change at line 339 ¶		skipping to change at line 339 ¶
	MUST treat the request as a long-term error.		MUST treat the request as a long-term error.
	Examples of long-term errors include:		Examples of long-term errors include:
	* Retry-After is invalid or not present		* Retry-After is invalid or not present
	* RenewalInfo object is invalid		* RenewalInfo object is invalid
	* DNS lookup failure		* DNS lookup failure
	* Connection refused		* Connection refused
	* Non-5xx HTTP error		* Non-5xx HTTP error
	On receiving a long-term error, clients MUST perform the next		On receiving a long-term error, clients MUST make the next
	RenewalInfo fetch as soon as possible after six hours have passed (or		renewalInfo request as soon as possible after six hours have passed
	some other locally configured default).		(or some other locally configured default).
	5. Extensions to the Order Object		5. Extensions to the Order Object
	In order to convey information regarding which certificate requests		In order to convey information regarding which certificate requests
	represent renewals of previous certificates, a new field is added to		represent renewals of previous certificates, a new field is added to
	the Order object:		the Order object:
	replaces (string, optional):		replaces (string, optional):
	A string uniquely identifying a previously issued certificate that		A string uniquely identifying a previously issued certificate that
	this order is intended to replace. This unique identifier is		this order is intended to replace. This unique identifier is
	constructed in the same way as the path component for GET requests		constructed in the same way as the path component for GET requests
	described above.		described above.
	Clients SHOULD include this field in New Order requests if there is a		Clients SHOULD include this field in newOrder requests if there is a
	clear predecessor certificate, as is the case for most certificate		clear predecessor certificate, as is the case for most certificate
	renewals. Clients SHOULD NOT include this field if the ACME Server		renewals. Clients SHOULD NOT include this field if the ACME server
	has not indicated that it supports this protocol by advertising the		has not indicated that it supports this protocol by advertising the
	renewalInfo resource in its Directory.		renewalInfo resource in its Directory.
	POST /new-order HTTP/1.1		POST /new-order HTTP/1.1
	Host: acme.example.com		Host: acme.example.com
	Content-Type: application/jose+json		Content-Type: application/jose+json
	{		{
	"protected": base64url({		"protected": base64url({
	"alg": "ES256",		"alg": "ES256",
	skipping to change at line 381 ¶		skipping to change at line 381 ¶
	}),		}),
	"payload": base64url({		"payload": base64url({
	"identifiers": [		"identifiers": [
	{ "type": "dns", "value": "acme.example.com" }		{ "type": "dns", "value": "acme.example.com" }
	],		],
	"replaces": "aYhba4dGQEHhs3uEe6CuLN4ByNQ.AIdlQyE"		"replaces": "aYhba4dGQEHhs3uEe6CuLN4ByNQ.AIdlQyE"
	}),		}),
	"signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g"		"signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g"
	}		}
	Servers SHOULD check that the identified certificate and the New		Servers SHOULD check that the identified certificate and the newOrder
	Order request correspond to the same ACME Account, that they share at		request correspond to the same ACME Account, that they share at least
	least one identifier, and that the identified certificate has not		one identifier, and that the identified certificate has not already
	already been marked as replaced by a different Order that is not		been marked as replaced by a different Order that is not "invalid".
	"invalid". Correspondence checks beyond this (such as requiring		Correspondence checks beyond this (such as requiring exact identifier
	exact identifier matching) are left up to Server policy. If any of		matching) are left up to server policy. If any of these checks fail,
	these checks fail, the Server SHOULD reject the new-order request.		the server SHOULD reject the newOrder request. If the server rejects
	If the Server rejects the request because the identified certificate		the request because the identified certificate has already been
	has already been marked as replaced, it MUST return an HTTP 409		marked as replaced, it MUST return an HTTP 409 (Conflict) with a
	(Conflict) with a problem document of type "alreadyReplaced" (see		problem document of type "alreadyReplaced" (see Section 7.4).
	Section 7.4).
	If the Server accepts a new-order request with a "replaces" field, it		If the server accepts a newOrder request with a "replaces" field, it
	MUST reflect that field in the response and in subsequent requests		MUST reflect that field in the response and in subsequent requests
	for the corresponding Order object.		for the corresponding Order object.
	This replacement information may serve many purposes, including but		This replacement information may serve many purposes, including but
	not limited to:		not limited to:
	* granting New Order requests that arrive during the suggested		* granting newOrder requests that arrive during the suggested
	renewal window of their identified predecessor certificate higher		renewal window of their identified predecessor certificate higher
	priority or allowing them to bypass rate limits, if the Server's		priority or allowing them to bypass rate limits, if the server's
	policy uses such;		policy uses such;
	* tracking the replacement of certificates that have been affected		* tracking the replacement of certificates that have been affected
	by a compliance incident, so that they can be revoked immediately		by a compliance incident, so that they can be revoked immediately
	after they are replaced; and		after they are replaced; and
	* tying together certificates issued under the same contract with an		* tying together certificates issued under the same contract with an
	entity identified by External Account Binding.		entity identified by External Account Binding.
	6. Security Considerations		6. Security Considerations
	The extensions to the ACME protocol described in this document build		The extensions to the ACME protocol described in this document build
	upon the security considerations and threat model defined in		upon the security considerations and threat model defined in
	Section 10.1 of [RFC8555].		Section 10.1 of [RFC8555].
	This document specifies that renewalInfo resources are exposed and		This document specifies that RenewalInfo resources are exposed and
	accessed via unauthenticated GET requests, a departure from the		accessed via unauthenticated GET requests, a departure from the
	requirement in RFC 8555 that clients send POST-as-GET requests to		requirement in RFC 8555 that clients send POST-as-GET requests to
	fetch resources from the server. This is because the information		fetch resources from the server. This is because the information
	contained in renewalInfo resources is not considered confidential and		contained in RenewalInfo resources is not considered confidential and
	because allowing renewalInfo to be easily cached is advantageous to		because allowing RenewalInfo resources to be easily cached is
	shed the load from clients that do not respect the Retry-After		advantageous to shed the load from clients that do not respect the
	header. As always, servers should take measures to ensure that		Retry-After header. As always, servers should take measures to
	unauthenticated requests for renewal information cannot result in		ensure that unauthenticated requests for renewal information cannot
	denial-of-service attacks. These measures might include ensuring		result in denial-of-service attacks. These measures might include
	that a cache does not include superfluous request headers or query		ensuring that a cache does not include superfluous request headers or
	parameters in its cache key, instituting IP-based rate limits, or		query parameters in its cache key, instituting IP-based rate limits,
	other general best-practice measures.		or other general best-practice measures.
	Note that this protocol could exhibit undesired behavior in the		Note that this protocol could exhibit undesired behavior in the
	presence of significant clock skew between the ACME client and		presence of significant clock skew between the ACME client and
	server. For example, if a server places the suggested renewal window		server. For example, if a server places the suggested renewal window
	wholly in the past to encourage a client to renew immediately, a		wholly in the past to encourage a client to renew immediately, a
	client with a sufficiently slow clock might nonetheless see the		client with a sufficiently slow clock might nonetheless see the
	window as being in the future. Similarly, a server that wishes to		window as being in the future. Similarly, a server that wishes to
	schedule renewals very precisely may have difficulty doing so if some		schedule renewals very precisely may have difficulty doing so if some
	clients have skewed clocks (or do no implement ARI at all). Server		clients have skewed clocks (or do no implement ARI at all). Server
	operators should take this concern into account when setting		operators should take this concern into account when setting
	skipping to change at line 454 ¶		skipping to change at line 453 ¶
	7. IANA Considerations		7. IANA Considerations
	7.1. ACME Resource Type		7.1. ACME Resource Type
	IANA has added the following entry to the "ACME Resource Types"		IANA has added the following entry to the "ACME Resource Types"
	registry within the "Automated Certificate Management Environment		registry within the "Automated Certificate Management Environment
	(ACME) Protocol" registry group at <https://www.iana.org/assignments/		(ACME) Protocol" registry group at <https://www.iana.org/assignments/
	acme>:		acme>:
	+=============+=====================+===============+		+=============+====================+===============+
	| Field Name | Resource Type | Reference |		| Field Name | Resource Type | Reference |
	+=============+=====================+===============+		+=============+====================+===============+
	| renewalInfo | Renewal Info object | This document |		| renewalInfo | RenewalInfo object | This document |
	+-------------+---------------------+---------------+		+-------------+--------------------+---------------+
	Table 2		Table 2
	7.2. ACME Renewal Info Object Fields		7.2. ACME RenewalInfo Object Fields
	IANA has added the following new registry to the "Automated		IANA has added the following new registry to the "Automated
	Certificate Management Environment (ACME) Protocol" registry group at		Certificate Management Environment (ACME) Protocol" registry group at
	<https://www.iana.org/assignments/acme>:		<https://www.iana.org/assignments/acme>:
	Registry Name:		Registry Name:
	ACME Renewal Info Object Fields		ACME RenewalInfo Object Fields
	Registration Procedure:		Registration Procedure:
	Specification Required (see [RFC8126]). The designated expert		Specification Required (see [RFC8126]). The designated expert
	should ensure that any new fields added to this registry carry		should ensure that any new fields added to this registry carry
	useful and unique information that does not better belong		useful and unique information that does not better belong
	elsewhere in the ACME protocol.		elsewhere in the ACME protocol.
	Template:		Template:
	Field name: The string to be used as a field name in the JSON		Field name: The string to be used as a field name in the JSON
	object		object
End of changes. 25 change blocks.
	58 lines changed or deleted		57 lines changed or added
This html diff was produced by rfcdiff 1.48.