draft-ietf-acme-acme-11.txt   draft-ietf-acme-acme-12.txt 
ACME Working Group R. Barnes ACME Working Group R. Barnes
Internet-Draft Cisco Internet-Draft Cisco
Intended status: Standards Track J. Hoffman-Andrews Intended status: Standards Track J. Hoffman-Andrews
Expires: September 28, 2018 EFF Expires: October 26, 2018 EFF
D. McCarney D. McCarney
Let's Encrypt Let's Encrypt
J. Kasten J. Kasten
University of Michigan University of Michigan
March 27, 2018 April 24, 2018
Automatic Certificate Management Environment (ACME) Automatic Certificate Management Environment (ACME)
draft-ietf-acme-acme-11 draft-ietf-acme-acme-12
Abstract Abstract
Certificates in PKI using X.509 (PKIX) are used for a number of Certificates in PKI using X.509 (PKIX) are used for a number of
purposes, the most significant of which is the authentication of purposes, the most significant of which is the authentication of
domain names. Thus, certificate authorities in the Web PKI are domain names. Thus, certificate authorities in the Web PKI are
trusted to verify that an applicant for a certificate legitimately trusted to verify that an applicant for a certificate legitimately
represents the domain name(s) in the certificate. Today, this represents the domain name(s) in the certificate. Today, this
verification is done through a collection of ad hoc mechanisms. This verification is done through a collection of ad hoc mechanisms. This
document describes a protocol that a certification authority (CA) and document describes a protocol that a certification authority (CA) and
skipping to change at page 2, line 7 skipping to change at page 2, line 7
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on September 28, 2018. This Internet-Draft will expire on October 26, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2018 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 3, line 34 skipping to change at page 3, line 34
9.1. MIME Type: application/pem-certificate-chain . . . . . . 60 9.1. MIME Type: application/pem-certificate-chain . . . . . . 60
9.2. Well-Known URI for the HTTP Challenge . . . . . . . . . . 61 9.2. Well-Known URI for the HTTP Challenge . . . . . . . . . . 61
9.3. Replay-Nonce HTTP Header . . . . . . . . . . . . . . . . 61 9.3. Replay-Nonce HTTP Header . . . . . . . . . . . . . . . . 61
9.4. "url" JWS Header Parameter . . . . . . . . . . . . . . . 61 9.4. "url" JWS Header Parameter . . . . . . . . . . . . . . . 61
9.5. "nonce" JWS Header Parameter . . . . . . . . . . . . . . 62 9.5. "nonce" JWS Header Parameter . . . . . . . . . . . . . . 62
9.6. URN Sub-namespace for ACME (urn:ietf:params:acme) . . . . 62 9.6. URN Sub-namespace for ACME (urn:ietf:params:acme) . . . . 62
9.7. New Registries . . . . . . . . . . . . . . . . . . . . . 62 9.7. New Registries . . . . . . . . . . . . . . . . . . . . . 62
9.7.1. Fields in Account Objects . . . . . . . . . . . . . . 63 9.7.1. Fields in Account Objects . . . . . . . . . . . . . . 63
9.7.2. Fields in Order Objects . . . . . . . . . . . . . . . 64 9.7.2. Fields in Order Objects . . . . . . . . . . . . . . . 64
9.7.3. Fields in Authorization Objects . . . . . . . . . . . 65 9.7.3. Fields in Authorization Objects . . . . . . . . . . . 65
9.7.4. Error Types . . . . . . . . . . . . . . . . . . . . . 65 9.7.4. Error Types . . . . . . . . . . . . . . . . . . . . . 66
9.7.5. Resource Types . . . . . . . . . . . . . . . . . . . 66 9.7.5. Resource Types . . . . . . . . . . . . . . . . . . . 66
9.7.6. Fields in the "meta" Object within a Directory Object 67 9.7.6. Fields in the "meta" Object within a Directory Object 67
9.7.7. Identifier Types . . . . . . . . . . . . . . . . . . 67 9.7.7. Identifier Types . . . . . . . . . . . . . . . . . . 68
9.7.8. Validation Methods . . . . . . . . . . . . . . . . . 68 9.7.8. Validation Methods . . . . . . . . . . . . . . . . . 68
10. Security Considerations . . . . . . . . . . . . . . . . . . . 69 10. Security Considerations . . . . . . . . . . . . . . . . . . . 69
10.1. Threat Model . . . . . . . . . . . . . . . . . . . . . . 69 10.1. Threat Model . . . . . . . . . . . . . . . . . . . . . . 70
10.2. Integrity of Authorizations . . . . . . . . . . . . . . 70 10.2. Integrity of Authorizations . . . . . . . . . . . . . . 71
10.3. Denial-of-Service Considerations . . . . . . . . . . . . 73 10.3. Denial-of-Service Considerations . . . . . . . . . . . . 73
10.4. Server-Side Request Forgery . . . . . . . . . . . . . . 73 10.4. Server-Side Request Forgery . . . . . . . . . . . . . . 74
10.5. CA Policy Considerations . . . . . . . . . . . . . . . . 74 10.5. CA Policy Considerations . . . . . . . . . . . . . . . . 74
11. Operational Considerations . . . . . . . . . . . . . . . . . 75 11. Operational Considerations . . . . . . . . . . . . . . . . . 75
11.1. DNS security . . . . . . . . . . . . . . . . . . . . . . 75 11.1. Key Selection . . . . . . . . . . . . . . . . . . . . . 75
11.2. Token Entropy . . . . . . . . . . . . . . . . . . . . . 75 11.2. DNS security . . . . . . . . . . . . . . . . . . . . . . 76
11.3. Malformed Certificate Chains . . . . . . . . . . . . . . 75 11.3. Token Entropy . . . . . . . . . . . . . . . . . . . . . 76
12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 76 11.4. Malformed Certificate Chains . . . . . . . . . . . . . . 77
13. References . . . . . . . . . . . . . . . . . . . . . . . . . 76 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 77
13.1. Normative References . . . . . . . . . . . . . . . . . . 76 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 78
13.2. Informative References . . . . . . . . . . . . . . . . . 79 13.1. Normative References . . . . . . . . . . . . . . . . . . 78
13.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 80 13.2. Informative References . . . . . . . . . . . . . . . . . 80
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 80 13.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 82
1. Introduction 1. Introduction
Certificates [RFC5280] in the Web PKI are most commonly used to Certificates [RFC5280] in the Web PKI are most commonly used to
authenticate domain names. Thus, certificate authorities in the Web authenticate domain names. Thus, certificate authorities in the Web
PKI are trusted to verify that an applicant for a certificate PKI are trusted to verify that an applicant for a certificate
legitimately represents the domain name(s) in the certificate. legitimately represents the domain name(s) in the certificate.
Different types of certificates reflect different kinds of CA Different types of certificates reflect different kinds of CA
verification of information about the certificate subject. "Domain verification of information about the certificate subject. "Domain
skipping to change at page 10, line 7 skipping to change at page 10, line 7
In most HTTPS transactions used by ACME, the ACME client is the HTTPS In most HTTPS transactions used by ACME, the ACME client is the HTTPS
client and the ACME server is the HTTPS server. The ACME server acts client and the ACME server is the HTTPS server. The ACME server acts
as an HTTP and HTTPS client when validating challenges via HTTP. as an HTTP and HTTPS client when validating challenges via HTTP.
ACME servers SHOULD follow the recommendations of [RFC7525] when ACME servers SHOULD follow the recommendations of [RFC7525] when
configuring their TLS implementations. ACME servers that support TLS configuring their TLS implementations. ACME servers that support TLS
1.3 MAY allow clients to send early data (0-RTT). This is safe 1.3 MAY allow clients to send early data (0-RTT). This is safe
because the ACME protocol itself includes anti-replay protections because the ACME protocol itself includes anti-replay protections
(see Section 6.4). (see Section 6.4).
ACME clients SHOULD send a User-Agent header in accordance with ACME clients MUST send a User-Agent header, in accordance with
[RFC7231], including the name and version of the ACME software in [RFC7231]. This header SHOULD include the name and version of the
addition to the name and version of the underlying HTTP client ACME software in addition to the name and version of the underlying
software. HTTP client software.
ACME clients SHOULD send an Accept-Language header in accordance with ACME clients SHOULD send an Accept-Language header in accordance with
[RFC7231] to enable localization of error messages. [RFC7231] to enable localization of error messages.
ACME servers that are intended to be generally accessible need to use ACME servers that are intended to be generally accessible need to use
Cross-Origin Resource Sharing (CORS) in order to be accessible from Cross-Origin Resource Sharing (CORS) in order to be accessible from
browser-based clients [W3C.CR-cors-20130129]. Such servers SHOULD browser-based clients [W3C.CR-cors-20130129]. Such servers SHOULD
set the Access-Control-Allow-Origin header field to the value "*". set the Access-Control-Allow-Origin header field to the value "*".
Binary fields in the JSON objects used by ACME are encoded using Binary fields in the JSON objects used by ACME are encoded using
skipping to change at page 14, line 51 skipping to change at page 14, line 51
When the server responds with an error status, it SHOULD provide When the server responds with an error status, it SHOULD provide
additional information using a problem document [RFC7807]. To additional information using a problem document [RFC7807]. To
facilitate automatic response to errors, this document defines the facilitate automatic response to errors, this document defines the
following standard tokens for use in the "type" field (within the following standard tokens for use in the "type" field (within the
"urn:ietf:params:acme:error:" namespace): "urn:ietf:params:acme:error:" namespace):
+-------------------------+-----------------------------------------+ +-------------------------+-----------------------------------------+
| Type | Description | | Type | Description |
+-------------------------+-----------------------------------------+ +-------------------------+-----------------------------------------+
| accountDoesNotExist | The request specified an account that |
| | does not exist |
| | |
| badCSR | The CSR is unacceptable (e.g., due to a | | badCSR | The CSR is unacceptable (e.g., due to a |
| | short key) | | | short key) |
| | | | | |
| badNonce | The client sent an unacceptable anti- | | badNonce | The client sent an unacceptable anti- |
| | replay nonce | | | replay nonce |
| | | | | |
| badRevocationReason | The revocation reason provided is not |
| | allowed by the server |
| | |
| badSignatureAlgorithm | The JWS was signed with an algorithm | | badSignatureAlgorithm | The JWS was signed with an algorithm |
| | the server does not support | | | the server does not support |
| | | | | |
| invalidContact | A contact URL for an account was | | caa | Certification Authority Authorization |
| | invalid | | | (CAA) records forbid the CA from |
| | issuing |
| | | | | |
| unsupportedContact | A contact URL for an account used an | | compound | Specific error conditions are indicated |
| | unsupported protocol scheme | | | in the "subproblems" array. |
| | |
| connection | The server could not connect to |
| | validation target |
| | |
| dns | There was a problem with a DNS query |
| | | | | |
| externalAccountRequired | The request must include a value for | | externalAccountRequired | The request must include a value for |
| | the "externalAccountBinding" field | | | the "externalAccountBinding" field |
| | | | | |
| accountDoesNotExist | The request specified an account that | | incorrectResponse | Response received didn't match the |
| | does not exist | | | challenge's requirements |
| | |
| invalidContact | A contact URL for an account was |
| | invalid |
| | | | | |
| malformed | The request message was malformed | | malformed | The request message was malformed |
| | | | | |
| rateLimited | The request exceeds a rate limit | | rateLimited | The request exceeds a rate limit |
| | | | | |
| rejectedIdentifier | The server will not issue for the | | rejectedIdentifier | The server will not issue for the |
| | identifier | | | identifier |
| | | | | |
| serverInternal | The server experienced an internal | | serverInternal | The server experienced an internal |
| | error | | | error |
| | | | | |
| tls | The server received a TLS error during |
| | validation |
| | |
| unauthorized | The client lacks sufficient | | unauthorized | The client lacks sufficient |
| | authorization | | | authorization |
| | | | | |
| unsupportedContact | A contact URL for an account used an |
| | unsupported protocol scheme |
| | |
| unsupportedIdentifier | Identifier is not supported, but may be | | unsupportedIdentifier | Identifier is not supported, but may be |
| | in future | | | in future |
| | | | | |
| userActionRequired | Visit the "instance" URL and take | | userActionRequired | Visit the "instance" URL and take |
| | actions specified there | | | actions specified there |
| | |
| badRevocationReason | The revocation reason provided is not |
| | allowed by the server |
| | |
| caa | Certification Authority Authorization |
| | (CAA) records forbid the CA from |
| | issuing |
| | |
| dns | There was a problem with a DNS query |
| | |
| connection | The server could not connect to |
| | validation target |
| | |
| tls | The server received a TLS error during |
| | validation |
| | |
| incorrectResponse | Response received didn't match the |
| | challenge's requirements |
+-------------------------+-----------------------------------------+ +-------------------------+-----------------------------------------+
This list is not exhaustive. The server MAY return errors whose This list is not exhaustive. The server MAY return errors whose
"type" field is set to a URI other than those defined above. Servers "type" field is set to a URI other than those defined above. Servers
MUST NOT use the ACME URN [RFC3553] namespace for errors other than MUST NOT use the ACME URN [RFC3553] namespace for errors other than
the standard types. Clients SHOULD display the "detail" field of all the standard types. Clients SHOULD display the "detail" field of all
errors. errors.
In the remainder of this document, we use the tokens in the table In the remainder of this document, we use the tokens in the table
above to refer to error types, rather than the full URNs. For above to refer to error types, rather than the full URNs. For
skipping to change at page 19, line 17 skipping to change at page 19, line 17
+--> newNonce +--> newNonce
| |
+----------+----------+-----+-----+------------+ +----------+----------+-----+-----+------------+
| | | | | | | | | |
| | | | | | | | | |
V V V V V V V V V V
newAccount newAuthz newOrder revokeCert keyChange newAccount newAuthz newOrder revokeCert keyChange
| | | | | |
| | | | | |
V | V V | V
account | order -----> finalize account | order --+--> finalize
| | -----> cert | | |
| | | | +--> cert
| V | V
+---> authorizations +---> authorization
| ^ | ^
| | "up" | | "up"
V | V |
challenge challenge
The following table illustrates a typical sequence of requests The following table illustrates a typical sequence of requests
required to establish a new account with the server, prove control of required to establish a new account with the server, prove control of
an identifier, issue a certificate, and fetch an updated certificate an identifier, issue a certificate, and fetch an updated certificate
some time after issuance. The "->" is a mnemonic for a Location some time after issuance. The "->" is a mnemonic for a Location
header pointing to a created resource. header pointing to a created resource.
skipping to change at page 24, line 33 skipping to change at page 24, line 33
notAfter (optional, string): The requested value of the notAfter notAfter (optional, string): The requested value of the notAfter
field in the certificate, in the date format defined in [RFC3339]. field in the certificate, in the date format defined in [RFC3339].
error (optional, object): The error that occurred while processing error (optional, object): The error that occurred while processing
the order, if any. This field is structured as a problem document the order, if any. This field is structured as a problem document
[RFC7807]. [RFC7807].
authorizations (required, array of string): For pending orders, the authorizations (required, array of string): For pending orders, the
authorizations that the client needs to complete before the authorizations that the client needs to complete before the
requested certificate can be issued (see Section 7.5). For final requested certificate can be issued (see Section 7.5). The
orders (in the "valid" or "invalid" state), the authorizations authorizations required are dictated by server policy and there
that were completed. Each entry is a URL from which an may not be a 1:1 relationship between the order identifiers and
authorization can be fetched with a GET request. the authorizations required. For final orders (in the "valid" or
"invalid" state), the authorizations that were completed. Each
entry is a URL from which an authorization can be fetched with a
GET request.
finalize (required, string): A URL that a CSR must be POSTed to once finalize (required, string): A URL that a CSR must be POSTed to once
all of the order's authorizations are satisfied to finalize the all of the order's authorizations are satisfied to finalize the
order. The result of a successful finalization will be the order. The result of a successful finalization will be the
population of the certificate URL for the order. population of the certificate URL for the order.
certificate (optional, string): A URL for the certificate that has certificate (optional, string): A URL for the certificate that has
been issued in response to this order. been issued in response to this order.
{ {
skipping to change at page 26, line 39 skipping to change at page 26, line 39
specified in RFC 3339 [RFC3339]. This field is REQUIRED for specified in RFC 3339 [RFC3339]. This field is REQUIRED for
objects with "valid" in the "status" field. objects with "valid" in the "status" field.
challenges (required, array of objects): For pending authorizations, challenges (required, array of objects): For pending authorizations,
the challenges that the client can fulfill in order to prove the challenges that the client can fulfill in order to prove
possession of the identifier. For final authorizations (in the possession of the identifier. For final authorizations (in the
"valid" or "invalid" state), the challenges that were used. Each "valid" or "invalid" state), the challenges that were used. Each
array entry is an object with parameters required to validate the array entry is an object with parameters required to validate the
challenge. A client should attempt to fulfill one of these challenge. A client should attempt to fulfill one of these
challenges, and a server should consider any one of the challenges challenges, and a server should consider any one of the challenges
sufficient to make the authorization valid. For final sufficient to make the authorization valid.
authorizations, it contains the challenges that were successfully
completed.
wildcard (optional, boolean): For authorizations created as a result wildcard (optional, boolean): For authorizations created as a result
of a newOrder request containing a DNS identifier with a value of a newOrder request containing a DNS identifier with a value
that contained a wildcard prefix this field MUST be present, and that contained a wildcard prefix this field MUST be present, and
true. true.
The only type of identifier defined by this specification is a fully- The only type of identifier defined by this specification is a fully-
qualified domain name (type: "dns"). If a domain name contains non- qualified domain name (type: "dns"). If a domain name contains non-
ASCII Unicode characters it MUST be encoded using the rules defined ASCII Unicode characters it MUST be encoded using the rules defined
in [RFC3492]. Servers MUST verify any identifier values that begin in [RFC3492]. Servers MUST verify any identifier values that begin
skipping to change at page 35, line 24 skipping to change at page 35, line 24
"instance": "https://example.com/acme/agreement/?token=W8Ih3PswD-8" "instance": "https://example.com/acme/agreement/?token=W8Ih3PswD-8"
} }
7.3.5. External Account Binding 7.3.5. External Account Binding
The server MAY require a value for the "externalAccountBinding" field The server MAY require a value for the "externalAccountBinding" field
to be present in "newAccount" requests. This can be used to to be present in "newAccount" requests. This can be used to
associate an ACME account with an existing account in a non-ACME associate an ACME account with an existing account in a non-ACME
system, such as a CA customer database. system, such as a CA customer database.
To enable ACME account binding, a CA needs to provide the ACME client To enable ACME account binding, the CA operating the ACME server
with a MAC key and a key identifier, using some mechanism outside of needs to provide the ACME client with a MAC key and a key identifier,
ACME. The key identifier MUST be an ASCII string. The MAC key using some mechanism outside of ACME. The key identifier MUST be an
SHOULD be provided in base64url-encoded form, to maximize ASCII string. The MAC key SHOULD be provided in base64url-encoded
compatibility between non-ACME provisioning systems and ACME clients. form, to maximize compatibility between non-ACME provisioning systems
and ACME clients.
The ACME client then computes a binding JWS to indicate the external The ACME client then computes a binding JWS to indicate the external
account holder's approval of the ACME account key. The payload of account holder's approval of the ACME account key. The payload of
this JWS is the account key being registered, in JWK form. The this JWS is the account key being registered, in JWK form. The
protected header of the JWS MUST meet the following criteria: protected header of the JWS MUST meet the following criteria:
o The "alg" field MUST indicate a MAC-based algorithm 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 "kid" field MUST contain the key identifier provided by the CA
skipping to change at page 42, line 39 skipping to change at page 42, line 39
The order object returned by the server represents a promise that if The order object returned by the server represents a promise that if
the client fulfills the server's requirements before the "expires" the client fulfills the server's requirements before the "expires"
time, then the server will be willing to finalize the order upon time, then the server will be willing to finalize the order upon
request and issue the requested certificate. In the order object, request and issue the requested certificate. In the order object,
any authorization referenced in the "authorizations" array whose any authorization referenced in the "authorizations" array whose
status is "pending" represents an authorization transaction that the status is "pending" represents an authorization transaction that the
client must complete before the server will issue the certificate client must complete before the server will issue the certificate
(see Section 7.5). If the client fails to complete the required (see Section 7.5). If the client fails to complete the required
actions before the "expires" time, then the server SHOULD change the actions before the "expires" time, then the server SHOULD change the
status of the order to "invalid" and MAY delete the order resource. status of the order to "invalid" and MAY delete the order resource.
Clients SHOULD NOT make any assumptions about the sort order of
"identifiers" or "authorizations" elements in the returned order
object.
Once the client believes it has fulfilled the server's requirements, Once the client believes it has fulfilled the server's requirements,
it should send a POST request to the order resource's finalize URL. it should send a POST request to the order resource's finalize URL.
The POST body MUST include a CSR: The POST body MUST include a CSR:
csr (required, string): A CSR encoding the parameters for the csr (required, string): A CSR encoding the parameters for the
certificate being requested [RFC2986]. The CSR is sent in the certificate being requested [RFC2986]. The CSR is sent in the
base64url-encoded version of the DER format. (Note: Because this base64url-encoded version of the DER format. (Note: Because this
field uses base64url, and does not include headers, it is field uses base64url, and does not include headers, it is
different from PEM.). different from PEM.).
skipping to change at page 61, line 8 skipping to change at page 61, line 8
replace draft-ietf-acme-acme above with the RFC number assigned to replace draft-ietf-acme-acme above with the RFC number assigned to
this ]] this ]]
Applications which use this media type: Any MIME-compliant transport Applications which use this media type: Any MIME-compliant transport
Additional information: Additional information:
File contains one or more certificates encoded with the PEM textual File contains one or more certificates encoded with the PEM textual
encoding, according to RFC 7468 [RFC7468]. In order to provide easy encoding, according to RFC 7468 [RFC7468]. In order to provide easy
interoperation with TLS, the first certificate MUST be an end-entity interoperation with TLS, the first certificate MUST be an end-entity
certificate. Each following certificate SHOULD directly certify one certificate. Each following certificate SHOULD directly certify the
preceding it. Because certificate validation requires that trust one preceding it. Because certificate validation requires that trust
anchors be distributed independently, a certificate that specifies a anchors be distributed independently, a certificate that specifies a
trust anchor MAY be omitted from the chain, provided that supported trust anchor MAY be omitted from the chain, provided that supported
peers are known to possess any omitted certificates. peers are known to possess any omitted certificates.
9.2. Well-Known URI for the HTTP Challenge 9.2. Well-Known URI for the HTTP Challenge
The "Well-Known URIs" registry should be updated with the following The "Well-Known URIs" registry should be updated with the following
additional value (using the template from [RFC5785]): additional value (using the template from [RFC5785]):
URI suffix: acme-challenge URI suffix: acme-challenge
skipping to change at page 62, line 52 skipping to change at page 62, line 52
for registries of ACME parameters. ]] for registries of ACME parameters. ]]
9.7. New Registries 9.7. New Registries
This document requests that IANA create the following new registries: This document requests that IANA create the following new registries:
1. ACME Account Object Fields (Section 9.7.1) 1. ACME Account Object Fields (Section 9.7.1)
2. ACME Order Object Fields (Section 9.7.2) 2. ACME Order Object Fields (Section 9.7.2)
3. ACME Error Types (Section 9.7.4) 3. ACME Authorization Object Fields (Section 9.7.3)
4. ACME Resource Types (Section 9.7.5) 4. ACME Error Types (Section 9.7.4)
5. ACME Directory Metadata Fields (Section 9.7.6) 5. ACME Resource Types (Section 9.7.5)
6. ACME Identifier Types (Section 9.7.7) 6. ACME Directory Metadata Fields (Section 9.7.6)
7. ACME Validation Methods (Section 9.7.8) 7. ACME Identifier Types (Section 9.7.7)
8. ACME Validation Methods (Section 9.7.8)
All of these registries are under a heading of "Automated Certificate All of these registries are under a heading of "Automated Certificate
Management Environment (ACME) Protocol" and are administered under a Management Environment (ACME) Protocol" and are administered under a
Specification Required policy [RFC8126]. Specification Required policy [RFC8126].
9.7.1. Fields in Account Objects 9.7.1. Fields in Account Objects
This registry lists field names that are defined for use in ACME This registry lists field names that are defined for use in ACME
account objects. Fields marked as "configurable" may be included in account objects. Fields marked as "configurable" may be included in
a new-account request. a new-account request.
skipping to change at page 68, line 43 skipping to change at page 69, line 24
Initial Contents Initial Contents
+------------+-----------------+------+-----------+ +------------+-----------------+------+-----------+
| Label | Identifier Type | ACME | Reference | | Label | Identifier Type | ACME | Reference |
+------------+-----------------+------+-----------+ +------------+-----------------+------+-----------+
| http-01 | dns | Y | RFC XXXX | | http-01 | dns | Y | RFC XXXX |
| | | | | | | | | |
| dns-01 | dns | Y | RFC XXXX | | dns-01 | dns | Y | RFC XXXX |
| | | | | | | | | |
| tls-sni-01 | RESERVED | N | N/A | | tls-sni-01 | RESERVED | N | RFC XXXX |
| | | | | | | | | |
| tls-sni-02 | RESERVED | N | N/A | | tls-sni-02 | RESERVED | N | RFC XXXX |
+------------+-----------------+------+-----------+ +------------+-----------------+------+-----------+
When evaluating a request for an assignment in this registry, the When evaluating a request for an assignment in this registry, the
designated expert should ensure that the method being registered has designated expert should ensure that the method being registered has
a clear, interoperable definition and does not overlap with existing a clear, interoperable definition and does not overlap with existing
validation methods. That is, it should not be possible for a client validation methods. That is, it should not be possible for a client
and server to follow the same set of actions to fulfill two different and server to follow the same set of actions to fulfill two different
validation methods. validation methods.
Validation methods do not have to be compatible with ACME in order to Validation methods do not have to be compatible with ACME in order to
skipping to change at page 75, line 11 skipping to change at page 75, line 34
CAs using ACME to allow clients to agree to terms of service should CAs using ACME to allow clients to agree to terms of service should
keep in mind that ACME clients can automate this agreement, possibly keep in mind that ACME clients can automate this agreement, possibly
not involving a human user. not involving a human user.
11. Operational Considerations 11. Operational Considerations
There are certain factors that arise in operational reality that There are certain factors that arise in operational reality that
operators of ACME-based CAs will need to keep in mind when operators of ACME-based CAs will need to keep in mind when
configuring their services. For example: configuring their services. For example:
11.1. DNS security 11.1. Key Selection
ACME relies on two different classes of key pair:
o Account key pairs, which are used to authenticate account holders
o Certificate key pairs, which are used to sign and verify CSRs (and
whose public keys are included in certificates)
Compromise of the private key of an account key pair has more serious
consequences than compromise of a private key corresponding to a
certificate. While the compromise of a certificate key pair allows
the attacker to impersonate the entities named in the certificate for
the lifetime of the certificate, the compromise of an account key
pair allows the attacker to take full control of the victim's ACME
account, and take any action that the legitimate account holder could
take within the scope of ACME:
1. Issuing certificates using existing authorizations
2. Revoking existing certificates
3. Accessing and changing account information (e.g., contacts)
4. Changing the account key pair for the account, locking out the
legitimate account holder
For this reason, it is RECOMMENDED that account key pairs be used for
no other purpose besides ACME authentication. For example, the
public key of an account key pair SHOULD NOT be included in a
certificate. ACME clients and servers SHOULD verify that a CSR
submitted in a finalize request does not contain a public key for any
known account key pair. In particular, when a server receives a
finalize request, it MUST verify that the public key in a CSR is not
the same as the public key of the account key pair used to
authenticate that request.
11.2. DNS security
As noted above, DNS forgery attacks against the ACME server can As noted above, DNS forgery attacks against the ACME server can
result in the server making incorrect decisions about domain control result in the server making incorrect decisions about domain control
and thus mis-issuing certificates. Servers SHOULD perform DNS and thus mis-issuing certificates. Servers SHOULD perform DNS
queries over TCP, which provides better resistance to some forgery queries over TCP, which provides better resistance to some forgery
attacks than DNS over UDP. attacks than DNS over UDP.
An ACME-based CA will often need to make DNS queries, e.g., to An ACME-based CA will often need to make DNS queries, e.g., to
validate control of DNS names. Because the security of such validate control of DNS names. Because the security of such
validations ultimately depends on the authenticity of DNS data, every validations ultimately depends on the authenticity of DNS data, every
skipping to change at page 75, line 35 skipping to change at page 76, line 45
provides additional protection to domains which choose to make use of provides additional protection to domains which choose to make use of
DNSSEC. DNSSEC.
An ACME-based CA must use only a resolver if it trusts the resolver An ACME-based CA must use only a resolver if it trusts the resolver
and every component of the network route by which it is accessed. It and every component of the network route by which it is accessed. It
is therefore RECOMMENDED that ACME-based CAs operate their own is therefore RECOMMENDED that ACME-based CAs operate their own
DNSSEC-validating resolvers within their trusted network and use DNSSEC-validating resolvers within their trusted network and use
these resolvers both for both CAA record lookups and all record these resolvers both for both CAA record lookups and all record
lookups in furtherance of a challenge scheme (A, AAAA, TXT, etc.). lookups in furtherance of a challenge scheme (A, AAAA, TXT, etc.).
11.2. Token Entropy 11.3. Token Entropy
The http-01, and dns-01 validation methods mandate the usage of a The http-01, and dns-01 validation methods mandate the usage of a
random token value to uniquely identify the challenge. The value of random token value to uniquely identify the challenge. The value of
the token is required to contain at least 128 bits of entropy for the the token is required to contain at least 128 bits of entropy for the
following security properties. First, the ACME client should not be following security properties. First, the ACME client should not be
able to influence the ACME server's choice of token as this may allow able to influence the ACME server's choice of token as this may allow
an attacker to reuse a domain owner's previous challenge responses an attacker to reuse a domain owner's previous challenge responses
for a new validation request. Secondly, the entropy requirement for a new validation request. Secondly, the entropy requirement
prevents ACME clients from implementing a "naive" validation server prevents ACME clients from implementing a "naive" validation server
that automatically replies to challenges without participating in the that automatically replies to challenges without participating in the
creation of the initial authorization request. creation of the initial authorization request.
11.3. Malformed Certificate Chains 11.4. Malformed Certificate Chains
ACME provides certificate chains in the widely-used format known ACME provides certificate chains in the widely-used format known
colloquially as PEM (though it may diverge from the actual Privacy colloquially as PEM (though it may diverge from the actual Privacy
Enhanced Mail specifications [RFC1421], as noted in [RFC7468]). Some Enhanced Mail specifications [RFC1421], as noted in [RFC7468]). Some
current software will allow the configuration of a private key and a current software will allow the configuration of a private key and a
certificate in one PEM file, by concatenating the textual encodings certificate in one PEM file, by concatenating the textual encodings
of the two objects. In the context of ACME, such software might be of the two objects. In the context of ACME, such software might be
vulnerable to "key replacement" attacks. A malicious ACME server vulnerable to "key replacement" attacks. A malicious ACME server
could cause a client to use a private key of its choosing by could cause a client to use a private key of its choosing by
including the key in the PEM file returned in response to a query for including the key in the PEM file returned in response to a query for
 End of changes. 34 change blocks. 
74 lines changed or deleted 121 lines changed or added

This html diff was produced by rfcdiff 1.46. The latest version is available from http://tools.ietf.org/tools/rfcdiff/