draft-ietf-acme-acme-10.txt   draft-ietf-acme-acme-11.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 6, 2018 EFF Expires: September 28, 2018 EFF
D. McCarney D. McCarney
Let's Encrypt Let's Encrypt
J. Kasten J. Kasten
University of Michigan University of Michigan
March 05, 2018 March 27, 2018
Automatic Certificate Management Environment (ACME) Automatic Certificate Management Environment (ACME)
draft-ietf-acme-acme-10 draft-ietf-acme-acme-11
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 6, 2018. This Internet-Draft will expire on September 28, 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 . . . . . . . . . . . . . . . . . . . . . 66 9.7.4. Error Types . . . . . . . . . . . . . . . . . . . . . 65
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 . . . . . . . . . . . . . . . . . . 68 9.7.7. Identifier Types . . . . . . . . . . . . . . . . . . 67
9.7.8. Validation Methods . . . . . . . . . . . . . . . . . 68 9.7.8. Validation Methods . . . . . . . . . . . . . . . . . 68
10. Security Considerations . . . . . . . . . . . . . . . . . . . 69 10. Security Considerations . . . . . . . . . . . . . . . . . . . 69
10.1. Threat Model . . . . . . . . . . . . . . . . . . . . . . 70 10.1. Threat Model . . . . . . . . . . . . . . . . . . . . . . 69
10.2. Integrity of Authorizations . . . . . . . . . . . . . . 71 10.2. Integrity of Authorizations . . . . . . . . . . . . . . 70
10.3. Denial-of-Service Considerations . . . . . . . . . . . . 73 10.3. Denial-of-Service Considerations . . . . . . . . . . . . 73
10.4. Server-Side Request Forgery . . . . . . . . . . . . . . 74 10.4. Server-Side Request Forgery . . . . . . . . . . . . . . 73
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. DNS security . . . . . . . . . . . . . . . . . . . . . . 75
11.2. Token Entropy . . . . . . . . . . . . . . . . . . . . . 76 11.2. Token Entropy . . . . . . . . . . . . . . . . . . . . . 75
11.3. Malformed Certificate Chains . . . . . . . . . . . . . . 76 11.3. Malformed Certificate Chains . . . . . . . . . . . . . . 75
12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 76 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 76
13. References . . . . . . . . . . . . . . . . . . . . . . . . . 77 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 76
13.1. Normative References . . . . . . . . . . . . . . . . . . 77 13.1. Normative References . . . . . . . . . . . . . . . . . . 76
13.2. Informative References . . . . . . . . . . . . . . . . . 80 13.2. Informative References . . . . . . . . . . . . . . . . . 79
13.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 81 13.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 80
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 50 skipping to change at page 10, line 50
o The JWS MUST NOT have multiple signatures o The JWS MUST NOT have multiple signatures
o The JWS Unencoded Payload Option [RFC7797] MUST NOT be used o The JWS Unencoded Payload Option [RFC7797] MUST NOT be used
o The JWS Unprotected Header [RFC7515] MUST NOT be used o The JWS Unprotected Header [RFC7515] MUST NOT be used
o The JWS MUST NOT have a Message Authentication Code (MAC)-based o The JWS MUST NOT have a Message Authentication Code (MAC)-based
algorithm in its "alg" field algorithm in its "alg" field
o The JWS The JWS Payload MUST NOT be detached o The JWS Payload MUST NOT be detached
o The JWS Protected Header MUST include the following fields: o The JWS Protected Header MUST include the following fields:
* "alg" (Algorithm) * "alg" (Algorithm)
* "jwk" (JSON Web Key, for all requests not signed using an * "jwk" (JSON Web Key, for all requests not signed using an
existing account, e.g. newAccount) existing account, e.g. newAccount)
* "kid" (Key ID, for all requests signed using an existing * "kid" (Key ID, for all requests signed using an existing
account) account)
skipping to change at page 20, line 21 skipping to change at page 20, line 21
| | | | | | | |
| Create account | POST newAccount | 201 -> account | | Create account | POST newAccount | 201 -> account |
| | | | | | | |
| Submit order | POST newOrder | 201 -> order | | Submit order | POST newOrder | 201 -> order |
| | | | | | | |
| Fetch challenges | GET order | 200 | | Fetch challenges | GET order | 200 |
| | authorizations | | | | authorizations | |
| | | | | | | |
| Respond to challenges | POST challenge urls | 200 | | Respond to challenges | POST challenge urls | 200 |
| | | | | | | |
| Poll for status | GET order | 200 |
| | | |
| Finalize order | POST order finalize | 200 | | Finalize order | POST order finalize | 200 |
| | | | | | | |
| Poll for status | GET order | 200 | | Poll for status | GET order | 200 |
| | | | | | | |
| Download certificate | GET order cert | 200 | | Download certificate | GET order certificate | 200 |
+-----------------------+--------------------------+----------------+ +-----------------------+--------------------------+----------------+
The remainder of this section provides the details of how these The remainder of this section provides the details of how these
resources are structured and how the ACME protocol makes use of them. resources are structured and how the ACME protocol makes use of them.
7.1.1. Directory 7.1.1. Directory
In order to help clients configure themselves with the right URLs for In order to help clients configure themselves with the right URLs for
each ACME operation, ACME servers provide a directory object. This each ACME operation, ACME servers provide a directory object. This
should be the only URL needed to configure clients. It is a JSON should be the only URL needed to configure clients. It is a JSON
skipping to change at page 23, line 32 skipping to change at page 23, line 32
orders created by the account can be fetched via GET request. The orders created by the account can be fetched via GET request. The
result of the GET request MUST be a JSON object whose "orders" field result of the GET request MUST be a JSON object whose "orders" field
is an array of URLs, each identifying an order belonging to the is an array of URLs, each identifying an order belonging to the
account. The server SHOULD include pending orders, and SHOULD NOT account. The server SHOULD include pending orders, and SHOULD NOT
include orders that are invalid in the array of URLs. The server MAY include orders that are invalid in the array of URLs. The server MAY
return an incomplete list, along with a Link header with a "next" return an incomplete list, along with a Link header with a "next"
link relation indicating where further entries can be acquired. link relation indicating where further entries can be acquired.
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Link: <https://example.com/acme/acct/1/orders?cursor=2>, rel="next" Link: <https://example.com/acme/acct/1/orders?cursor=2>;rel="next"
{ {
"orders": [ "orders": [
"https://example.com/acme/acct/1/order/1", "https://example.com/acme/acct/1/order/1",
"https://example.com/acme/acct/1/order/2", "https://example.com/acme/acct/1/order/2",
/* 47 more URLs not shown for example brevity */ /* 47 more URLs not shown for example brevity */
"https://example.com/acme/acct/1/order/50" "https://example.com/acme/acct/1/order/50"
] ]
} }
skipping to change at page 26, line 25 skipping to change at page 26, line 25
identifier (required, object): The identifier that the account is identifier (required, object): The identifier that the account is
authorized to represent authorized to represent
type (required, string): The type of identifier. type (required, string): The type of identifier.
value (required, string): The identifier itself. value (required, string): The identifier itself.
status (required, string): The status of this authorization. status (required, string): The status of this authorization.
Possible values are: "pending", "valid", "invalid", "deactivated", Possible values are: "pending", "valid", "invalid", "deactivated",
and "revoked". "expired", and "revoked".
expires (optional, string): The timestamp after which the server expires (optional, string): The timestamp after which the server
will consider this authorization invalid, encoded in the format will consider this authorization invalid, encoded in the format
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
skipping to change at page 31, line 24 skipping to change at page 31, line 24
termsOfServiceAgreed (optional, boolean): Same meaning as the termsOfServiceAgreed (optional, boolean): Same meaning as the
corresponding server field defined in Section 7.1.2 corresponding server field defined in Section 7.1.2
onlyReturnExisting (optional, boolean): If this field is present onlyReturnExisting (optional, boolean): If this field is present
with the value "true", then the server MUST NOT create a new with the value "true", then the server MUST NOT create a new
account if one does not already exist. This allows a client to account if one does not already exist. This allows a client to
look up an account URL based on an account key (see look up an account URL based on an account key (see
Section 7.3.1). Section 7.3.1).
externalAccountBinding (optional, object): An optional field for
binding the new account with an existing non-ACME account (see
Section 7.3.5).
POST /acme/new-account HTTP/1.1 POST /acme/new-account HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/jose+json Content-Type: application/jose+json
{ {
"protected": base64url({ "protected": base64url({
"alg": "ES256", "alg": "ES256",
"jwk": {...}, "jwk": {...},
"nonce": "6S8IqOGY7eL2lsGoTZYifg", "nonce": "6S8IqOGY7eL2lsGoTZYifg",
"url": "https://example.com/acme/new-account" "url": "https://example.com/acme/new-account"
skipping to change at page 33, line 17 skipping to change at page 33, line 17
Replay-Nonce: D8s4D2mLs8Vn-goWuPQeKA Replay-Nonce: D8s4D2mLs8Vn-goWuPQeKA
Location: https://example.com/acme/acct/1 Location: https://example.com/acme/acct/1
Link: <https://example.com/acme/some-directory>;rel="index" Link: <https://example.com/acme/some-directory>;rel="index"
{ {
"status": "valid", "status": "valid",
"contact": [ "contact": [
"mailto:cert-admin@example.com", "mailto:cert-admin@example.com",
"mailto:admin@example.com" "mailto:admin@example.com"
] ],
"orders": "https://example.com/acme/acct/1/orders"
} }
7.3.1. Finding an Account URL Given a Key 7.3.1. Finding an Account URL Given a Key
If the server already has an account registered with the provided If the server already has an account registered with the provided
account key, then it MUST return a response with a 200 (OK) status account key, then it MUST return a response with a 200 (OK) status
code and provide the URL of that account in the Location header code and provide the URL of that account in the Location header
field. This allows a client that has an account key but not the field. This allows a client that has an account key but not the
corresponding account URL to recover the account URL. corresponding account URL to recover the account URL.
skipping to change at page 41, line 23 skipping to change at page 41, line 23
Content-Type: application/jose+json Content-Type: application/jose+json
{ {
"protected": base64url({ "protected": base64url({
"alg": "ES256", "alg": "ES256",
"kid": "https://example.com/acme/acct/1", "kid": "https://example.com/acme/acct/1",
"nonce": "5XJ1L3lEkMG7tR6pA00clA", "nonce": "5XJ1L3lEkMG7tR6pA00clA",
"url": "https://example.com/acme/new-order" "url": "https://example.com/acme/new-order"
}), }),
"payload": base64url({ "payload": base64url({
"identifiers": [{"type:"dns","value":"example.com"}], "identifiers": [
{ "type": "dns", "value": "example.com" }
],
"notBefore": "2016-01-01T00:00:00Z", "notBefore": "2016-01-01T00:00:00Z",
"notAfter": "2016-01-08T00:00:00Z" "notAfter": "2016-01-08T00:00:00Z"
}), }),
"signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g" "signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g"
} }
The server MUST return an error if it cannot fulfill the request as The server MUST return an error if it cannot fulfill the request as
specified, and MUST NOT issue a certificate with contents other than specified, and MUST NOT issue a certificate with contents other than
those requested. If the server requires the request to be modified those requested. If the server requires the request to be modified
in a certain way, it should indicate the required changes using an in a certain way, it should indicate the required changes using an
skipping to change at page 42, line 17 skipping to change at page 42, line 17
Location: https://example.com/acme/order/asdf Location: https://example.com/acme/order/asdf
{ {
"status": "pending", "status": "pending",
"expires": "2016-01-01T00:00:00Z", "expires": "2016-01-01T00:00:00Z",
"notBefore": "2016-01-01T00:00:00Z", "notBefore": "2016-01-01T00:00:00Z",
"notAfter": "2016-01-08T00:00:00Z", "notAfter": "2016-01-08T00:00:00Z",
"identifiers": [ "identifiers": [
{ "type:"dns", "value":"example.com" }, { "type": "dns", "value": "example.com" },
{ "type:"dns", "value":"www.example.com" } { "type": "dns", "value": "www.example.com" }
], ],
"authorizations": [ "authorizations": [
"https://example.com/acme/authz/1234", "https://example.com/acme/authz/1234",
"https://example.com/acme/authz/2345" "https://example.com/acme/authz/2345"
], ],
"finalize": "https://example.com/acme/order/asdf/finalize" "finalize": "https://example.com/acme/order/asdf/finalize"
} }
skipping to change at page 43, line 30 skipping to change at page 43, line 30
} }
The CSR encodes the client's requests with regard to the content of The CSR encodes the client's requests with regard to the content of
the certificate to be issued. The CSR MUST indicate the exact same the certificate to be issued. The CSR MUST indicate the exact same
set of requested identifiers as the initial new-order request, either set of requested identifiers as the initial new-order request, either
in the commonName portion of the requested subject name, or in an in the commonName portion of the requested subject name, or in an
extensionRequest attribute [RFC2985] requesting a subjectAltName extensionRequest attribute [RFC2985] requesting a subjectAltName
extension. extension.
A request to finalize an order will result in error if the order A request to finalize an order will result in error if the order
indicated does not have status "pending", if the CSR and order indicated does not have status "ready", if the CSR and order
identifiers differ, or if the account is not authorized for the identifiers differ, or if the account is not authorized for the
identifiers indicated in the CSR. identifiers indicated in the CSR.
A valid request to finalize an order will return the order to be A valid request to finalize an order will return the order to be
finalized. The client should begin polling the order by sending a finalized. The client should begin polling the order by sending a
GET request to the order resource to obtain its current state. The GET request to the order resource to obtain its current state. The
status of the order will indicate what action the client should take: status of the order will indicate what action the client should take:
o "invalid": The certificate will not be issued. Consider this o "invalid": The certificate will not be issued. Consider this
order process abandoned. order process abandoned.
skipping to change at page 44, line 21 skipping to change at page 44, line 21
Location: https://example.com/acme/order/asdf Location: https://example.com/acme/order/asdf
{ {
"status": "valid", "status": "valid",
"expires": "2016-01-01T00:00:00Z", "expires": "2016-01-01T00:00:00Z",
"notBefore": "2016-01-01T00:00:00Z", "notBefore": "2016-01-01T00:00:00Z",
"notAfter": "2016-01-08T00:00:00Z", "notAfter": "2016-01-08T00:00:00Z",
"identifiers": [ "identifiers": [
{ "type:"dns", "value":"example.com" }, { "type": "dns", "value": "example.com" },
{ "type:"dns", "value":"www.example.com" } { "type": "dns", "value": "www.example.com" }
], ],
"authorizations": [ "authorizations": [
"https://example.com/acme/authz/1234", "https://example.com/acme/authz/1234",
"https://example.com/acme/authz/2345" "https://example.com/acme/authz/2345"
], ],
"finalize": "https://example.com/acme/order/asdf/finalize", "finalize": "https://example.com/acme/order/asdf/finalize",
"certificate": "https://example.com/acme/cert/asdf" "certificate": "https://example.com/acme/cert/asdf"
skipping to change at page 64, line 17 skipping to change at page 63, line 50
+------------------------+---------------+--------------+-----------+ +------------------------+---------------+--------------+-----------+
| status | string | false | RFC XXXX | | status | string | false | RFC XXXX |
| | | | | | | | | |
| contact | array of | true | RFC XXXX | | contact | array of | true | RFC XXXX |
| | string | | | | | string | | |
| | | | | | | | | |
| externalAccountBinding | object | true | RFC XXXX | | externalAccountBinding | object | true | RFC XXXX |
| | | | | | | | | |
| termsOfServiceAgreed | boolean | true | RFC XXXX | | termsOfServiceAgreed | boolean | true | RFC XXXX |
| | | | | | | | | |
| orders | array of | false | RFC XXXX | | orders | string | false | RFC XXXX |
| | string | | |
+------------------------+---------------+--------------+-----------+ +------------------------+---------------+--------------+-----------+
[[ RFC EDITOR: Please replace XXXX above with the RFC number assigned [[ RFC EDITOR: Please replace XXXX above with the RFC number assigned
to this document ]] to this document ]]
9.7.2. Fields in Order Objects 9.7.2. Fields in Order 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
order objects. Fields marked as "configurable" may be included in a order objects. Fields marked as "configurable" may be included in a
new-order request. new-order request.
 End of changes. 22 change blocks. 
29 lines changed or deleted 38 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/