idnits 2.17.1
draft-friel-acme-subdomains-02.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
No issues found here.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
-- The document date (March 06, 2020) is 1505 days in the past. Is this
intentional?
Checking references for intended status: Proposed Standard
----------------------------------------------------------------------------
(See RFCs 3967 and 4897 for information about using normative references
to lower-maturity documents in RFCs)
No issues found here.
Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Network Working Group O. Friel
3 Internet-Draft R. Barnes
4 Intended status: Standards Track Cisco
5 Expires: September 7, 2020 T. Hollebeek
6 DigiCert
7 M. Richardson
8 Sandelman Software Works
9 March 06, 2020
11 ACME for Subdomains
12 draft-friel-acme-subdomains-02
14 Abstract
16 This document outlines how ACME can be used by a client to obtain a
17 certificate for a subdomain identifier from a certificate authority.
18 The client has fulfilled a challenge against a parent domain but does
19 not need to fulfil a challenge against the explicit subdomain as
20 certificate authority policy allows issuance of the subdomain
21 certificate without explicit subdomain ownership proof.
23 Status of This Memo
25 This Internet-Draft is submitted in full conformance with the
26 provisions of BCP 78 and BCP 79.
28 Internet-Drafts are working documents of the Internet Engineering
29 Task Force (IETF). Note that other groups may also distribute
30 working documents as Internet-Drafts. The list of current Internet-
31 Drafts is at https://datatracker.ietf.org/drafts/current/.
33 Internet-Drafts are draft documents valid for a maximum of six months
34 and may be updated, replaced, or obsoleted by other documents at any
35 time. It is inappropriate to use Internet-Drafts as reference
36 material or to cite them other than as "work in progress."
38 This Internet-Draft will expire on September 7, 2020.
40 Copyright Notice
42 Copyright (c) 2020 IETF Trust and the persons identified as the
43 document authors. All rights reserved.
45 This document is subject to BCP 78 and the IETF Trust's Legal
46 Provisions Relating to IETF Documents
47 (https://trustee.ietf.org/license-info) in effect on the date of
48 publication of this document. Please review these documents
49 carefully, as they describe your rights and restrictions with respect
50 to this document. Code Components extracted from this document must
51 include Simplified BSD License text as described in Section 4.e of
52 the Trust Legal Provisions and are provided without warranty as
53 described in the Simplified BSD License.
55 Table of Contents
57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
58 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2
59 3. ACME Workflow and Identifier Requirements . . . . . . . . . . 3
60 4. ACME Issuance of Subdomain Certificates . . . . . . . . . . . 4
61 4.1. Pre-Authorization . . . . . . . . . . . . . . . . . . . . 4
62 4.2. Illustrative Call Flow . . . . . . . . . . . . . . . . . 5
63 4.3. newOrder and newAuthz Handling . . . . . . . . . . . . . 6
64 4.4. Examples . . . . . . . . . . . . . . . . . . . . . . . . 7
65 5. Resource Enhancements . . . . . . . . . . . . . . . . . . . . 8
66 5.1. Authorization Object . . . . . . . . . . . . . . . . . . 8
67 5.2. Directory Object Metadata . . . . . . . . . . . . . . . . 8
68 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
69 6.1. Authorization Object Fields Registry . . . . . . . . . . 8
70 6.2. Directory Object Metadata Fields Registry . . . . . . . . 8
71 7. Security Considerations . . . . . . . . . . . . . . . . . . . 9
72 8. Informative References . . . . . . . . . . . . . . . . . . . 9
73 Appendix A. ACME Server Policy Considerations . . . . . . . . . 9
74 A.1. CA Browser Forum Baseline Requirements Extracts . . . . . 10
75 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10
77 1. Introduction
79 ACME [RFC8555] defines a protocol that a certificate authority (CA)
80 and an applicant can use to automate the process of domain name
81 ownership validation and X.509 (PKIX) certificate issuance. This
82 document outlines how ACME can be used to issue subdomain
83 certificates, without requiring the ACME client to explicitly fulfil
84 an ownership challenge against the subdomain identifiers - the ACME
85 client need only fulfil an ownership challenge against a parent
86 domain identifier.
88 2. Terminology
90 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
91 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
92 "OPTIONAL" in this document are to be interpreted as described in BCP
93 14 [RFC2119] [RFC8174] when, and only when, they appear in all
94 capitals, as shown here.
96 The following terms are used in this document:
98 o CA: Certificate Authority
100 o CSR: Certificate Signing Request
102 o FQDN: Fully Qualified Domain Name
104 3. ACME Workflow and Identifier Requirements
106 A typical ACME workflow for issuance of certificates is as follows:
108 1. client POSTs a newOrder request that contains a set of
109 "identifiers"
111 2. server replies with a set of "authorizations" and a "finalize"
112 URI
114 3. client sends POST-as-GET requests to retrieve the
115 "authorizations", with the downloaded "authorization" object(s)
116 containing the "identifier" that the client must prove control of
118 4. client proves control over the "identifier" in the
119 "authorization" object by completing the specified challenge, for
120 example, by publishing a DNS TXT record
122 5. client POSTs a CSR to the "finalize" API
124 6. server replies with an updated order object that includes a
125 "certificate" URI
127 7. client sends POST-as-GET request to the "certificate" URI to
128 download the certificate
130 ACME places the following restrictions on "identifiers":
132 o section 7.1.4: the only type of "identifier" defined by the ACME
133 specification is a fully qualified domain name: "The only type of
134 identifier defined by this specification is a fully qualified
135 domain name (type: "dns"). The domain name MUST be encoded in the
136 form in which it would appear in a certificate."
138 o Section 7.4: the "identifier" in the CSR request must match the
139 "identifier" in the newOrder request: "The CSR MUST indicate the
140 exact same set of requested identifiers as the initial newOrder
141 request."
143 o Sections 8.3: the "identifier", or FQDN, in the "authorization"
144 object must be used when fulfilling challenges via HTTP:
146 "Construct a URL by populating the URL template ... where the
147 domain field is set to the domain name being verified"
149 o Section 8.4: the "identifier", or FQDN, in the "authorization"
150 object must be used when fulfilling challenges via DNS: "The
151 client constructs the validation domain name by prepending the
152 label "_acme-challenge" to the domain name being validated."
154 ACME does not mandate that the "identifier" in a newOrder request
155 matches the "identifier" in "authorization" objects.
157 4. ACME Issuance of Subdomain Certificates
159 As noted in the previous section, ACME does not mandate that the
160 "identifier" in a newOrder request matches the "identifier" in
161 "authorization" objects. This means that the ACME specification does
162 not preclude an ACME server processing newOrder requests and issuing
163 certificates for a subdomain without requiring a challenge to be
164 fulfilled against that explicit subdomain.
166 ACME server policy could allow issuance of certificates for a
167 subdomain to a client where the client only has to fulfil an
168 authorization challenge for a parent domain of that subdomain. This
169 allows a flow where a client proves ownership of, for example,
170 "example.com" and then successfully obtains a certificate for
171 "sub.example.com".
173 ACME server policy is out of scope of this document, however some
174 commentary is provided in Appendix A.
176 4.1. Pre-Authorization
178 The standard ACME workflow has authorization objects created
179 reactively in response to a certificate order. ACME also allows for
180 pre-authorization, where clients obtain authorization for an
181 identifier proactively, outside of the context of a specific
182 issuance. This document allows for both workflows, and Section 4.3
183 outlines how the ACME server handles newOrder and newAuthz requests
184 for both workflows.
186 It may make sense to use the ACME pre-authorization flow for the
187 subdomain use case, however, that is an operator implementation and
188 deployment decision. With the ACME pre-authorization flow, the
189 client could pre-authorize for the parent domain once, and then issue
190 multiple newOrder requests for certificates for multiple subdomains.
192 4.2. Illustrative Call Flow
194 The call flow illustrated here uses the ACME pre-authorization flow.
195 The call flow also illustrates the DNS-based proof of ownership
196 mechanism, but the subdomain workflow is equally valid for HTTP based
197 proof of ownership.
199 +--------+ +------+ +-----+
200 | Client | | ACME | | DNS |
201 +--------+ +------+ +-----+
202 | | |
203 STEP 1: Pre-Authorization of parent domain
204 | | |
205 | POST /newAuthz | |
206 | "example.com" | |
207 |--------------------->| |
208 | | |
209 | 201 authorizations | |
210 |<---------------------| |
211 | | |
212 | Publish DNS TXT | |
213 | "example.com" | |
214 |--------------------------------->|
215 | | |
216 | POST /challenge | |
217 |--------------------->| |
218 | | Verify |
219 | |---------->|
220 | 200 status=valid | |
221 |<---------------------| |
222 | | |
223 | Delete DNS TXT | |
224 | "example.com" | |
225 |--------------------------------->|
226 | | |
227 STEP 2: Place order for subdomain
228 | | |
229 | POST /newOrder | |
230 | "sub.example.com" | |
231 |--------------------->| |
232 | | |
233 | 201 status=ready | |
234 |<---------------------| |
235 | | |
236 | POST /finalize | |
237 | CSR "sub.example.com"| |
238 |--------------------->| |
239 | | |
240 | 200 OK status=valid | |
241 |<---------------------| |
242 | | |
243 | POST /certificate | |
244 |--------------------->| |
245 | | |
246 | 200 OK | |
247 | PKI "sub.example.com"| |
248 |<---------------------| |
250 4.3. newOrder and newAuthz Handling
252 Servers may consider validation of a parent domain sufficient
253 authorization for a subdomain. If a server has such a policy and a
254 client is already authorized for the parent domain then:
256 o If the client submits a newAuthz request for a subdomain: The
257 server MUST return status 200 (OK) response. The response body is
258 the existing authorization object for the parent domain with
259 status set to "valid".
261 o If the client submits a newOrder request for a subdomain: The
262 server MUST return a 201 (Created) response. The response body is
263 an order object with status set to "ready" and links to the
264 unexpired authorizations against the parent domain.
266 If a server has such a policy and a client is not authorized for the
267 parent domain then:
269 o If the client submits a newAuthz request for a subdomain: The
270 server MUST return a status 201 (Created) response. The response
271 body is a newly created authorization object for the parent domain
272 with status set to "pending".
274 o If the client submits a newOrder request for a subdomain: The
275 server MUST return a status 201 (Created) response. The response
276 body is an order object with status set to "pending" and links to
277 newly created authorizations objects against the parent domain.
279 [[ TODO: This section documents a change from RFC8555 section 7.4.1
280 which states "Note that because the identifier in a pre-authorization
281 request is the exact identifier to be included in the authorization
282 object, pre-authorization cannot be used to authorize issuance of
283 certificates containing wildcard domain names."
285 Additionally, 200 response code is used here in one scenario instead
286 of a 201 response. However, this is arguably an under-specification
287 in RFC8555, and has been reported in https://www.rfc-
288 editor.org/errata/eid5861.
290 These two items need a review. ]]
292 4.4. Examples
294 In order to illustrate subdomain behaviour, let us assume that a
295 client wishes to get certificates for subdomain identifiers
296 "sub0.example.com", "sub1.example.com" and "sub2.example.com" under
297 parent domain "example.com", and CA policy allows certificate
298 issuance of these subdomain identifiers while only requiring the
299 client to fulfil an ownership challenge for parent domain
300 "example.com". Let us also assume that the client has not yet proven
301 ownership of parent domain "example.com".
303 1. The client POSTs a newOrder request for identifier
304 "sub0.example.com"
306 The server creates an authorization object for identifier
307 "example.com". The server replies with a 201 (Created) response.
308 The response body is an order object with status set to "pending"
309 and a link to newly created authorization object against the
310 parent domain "example.com". Therefore, the server is
311 instructing the client to fulfil a challenge against domain
312 identifier "example.com" in order to obtain a certificate
313 including identifier "sub0.example.com".
315 The client completes the challenge for "example.com", POSTs a CSR
316 to the order finalize URI, and downloads the certificate.
318 2. The client POSTs a newOrder request for identifier
319 "sub1.example.com"
321 The server replies with a 201 (Created) response. The response
322 body is an order object with status set to "ready" and a link to
323 the unexpired authorization against the parent domain
324 "example.com".
326 The client POSTs a CSR to the order finalize URI, and downloads
327 the certificate.
329 3. The client POSTs a newAuthz request for identifier
330 "sub2.example.com"
332 The server replies with a 200 (OK) response. The response body
333 is the previously created authorization object for "example.com"
334 with status set to "valid".
336 5. Resource Enhancements
338 This document defines enhancements to the authorization and directory
339 objects.
341 5.1. Authorization Object
343 If an ACME server allows issuance of certificates for subdomains of a
344 parent domain, then the authorization object for the parent domain
345 MUST include the optional "basedomain" field, with a value of true.
347 The structure of an ACME authorization resource is enhanced to
348 include the following optional field:
350 basedomain (optional, boolean): This field MUST be present and true
351 for authorizations where ACME server policy allows certificates to to
352 be issued for subdomains of the identifier in the authorization
353 object without explicit authorization of the subdomain
355 5.2. Directory Object Metadata
357 An ACME server can advertise support of issuance of subdomain
358 certificates by including the boolean field
359 "implicitSubdomainAuthorization" in its "ACME Directory Metadata
360 Fields" registry. If not specified, then no default value is
361 assumed. If an ACME server supports issuance of subdomain
362 certificates, it can indicate this by including this field with a
363 value of "true".
365 6. IANA Considerations
367 6.1. Authorization Object Fields Registry
369 The following field is added to the "ACME Authorization Object
370 Fields" registry defined in ACME [RFC8555].
372 +------------+-----------------+--------------+-----------+
373 | Field Name | Field Type | Configurable | Reference |
374 +------------+-----------------+--------------+-----------+
375 | basedomain | boolean | false | RFC XXXX |
376 +------------+-----------------+--------------+-----------+
378 6.2. Directory Object Metadata Fields Registry
380 The following field is added to the "ACME Directory Metadata Fields"
381 registry defined in ACME [RFC8555].
382 +---------------------+--------+-------+ | Field Name | Field Type |
383 Reference | +---------------------+--------+-------+ |
384 implicitSubdomainAuthorization | boolean | RFC XXXX |
385 +---------------------+--------+-------+
387 7. Security Considerations
389 [[TODO]]
391 8. Informative References
393 [CAB] CA/Browser Forum, "Baseline Requirements for the Issuance
394 and Management of Publicly-Trusted Certificates", n.d.,
395 .
397 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
398 Requirement Levels", BCP 14, RFC 2119,
399 DOI 10.17487/RFC2119, March 1997,
400 .
402 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
403 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
404 May 2017, .
406 [RFC8555] Barnes, R., Hoffman-Andrews, J., McCarney, D., and J.
407 Kasten, "Automatic Certificate Management Environment
408 (ACME)", RFC 8555, DOI 10.17487/RFC8555, March 2019,
409 .
411 Appendix A. ACME Server Policy Considerations
413 The ACME specification does not mandate any specific ACME server or
414 CA policies, or any specific use cases for issuance of certificates.
415 For example, an ACME server could be used:
417 o to issue Web PKI certificates where the ACME server must comply
418 with CA/Browser [CAB] Baseline Requirements.
420 o as a Private CA for issuance of certificates within an
421 organisation. The organisation could enforce whatever policies
422 they desire on the ACME server.
424 o for issuance of IoT device certificates. There are currently no
425 IoT device certificate policies that are generally enforced across
426 the industry. Organsations issuing IoT device certificates can
427 enforce whatever policies they desire on the ACME server.
429 ACME server policy could specify whether:
431 o issuance of subdomain certificates is allowed based on proof of
432 ownership of a parent domain
434 o whether DNS based proof of ownership, or HTTP based proof of
435 ownership, or both, are allowed
437 ACME server policy specification is exlpicitly out of scope of this
438 document.
440 A.1. CA Browser Forum Baseline Requirements Extracts
442 The CA/Browser Forum Baseline Requirements [CAB] allow issuance of
443 subdomain certificates where authorization is only required for a
444 parent domain. Baseline Requirements version 1.6.5 states:
446 o Section: "1.6.1 Definitions": Authorization Domain Name: The
447 Domain Name used to obtain authorization for certificate issuance
448 for a given FQDN. The CA may use the FQDN returned from a DNS
449 CNAME lookup as the FQDN for the purposes of domain validation.
450 If the FQDN contains a wildcard character, then the CA MUST remove
451 all wildcard labels from the left most portion of requested FQDN.
452 The CA may prune zero or more labels from left to right until
453 encountering a Base Domain Name and may use any one of the
454 intermediate values for the purpose of domain validation.
456 o Section: "3.2.2.4.7 DNS Change": Once the FQDN has been validated
457 using this method, the CA MAY also issue Certificates for other
458 FQDNs that end with all the labels of the validated FQDN. This
459 method is suitable for validating Wildcard Domain Names.
461 Authors' Addresses
463 Owen Friel
464 Cisco
466 Email: ofriel@cisco.com
468 Richard Barnes
469 Cisco
471 Email: rlb@ipv.sx
473 Tim Hollebeek
474 DigiCert
476 Email: tim.hollebeek@digicert.com
477 Michael Richardson
478 Sandelman Software Works
480 Email: mcr+ietf@sandelman.ca