draft-ietf-acme-acme-16.txt   draft-ietf-acme-acme-17.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: April 15, 2019 EFF Expires: June 20, 2019 EFF
D. McCarney D. McCarney
Let's Encrypt Let's Encrypt
J. Kasten J. Kasten
University of Michigan University of Michigan
October 12, 2018 December 17, 2018
Automatic Certificate Management Environment (ACME) Automatic Certificate Management Environment (ACME)
draft-ietf-acme-acme-16 draft-ietf-acme-acme-17
Abstract Abstract
Public Key Infrastructure X.509 (PKIX) certificates are used for a Public Key Infrastructure X.509 (PKIX) certificates are used for a
number of purposes, the most significant of which is the number of purposes, the most significant of which is the
authentication of domain names. Thus, certification authorities authentication of domain names. Thus, certification authorities
(CAs) in the Web PKI are trusted to verify that an applicant for a (CAs) in the Web 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. Today, this verification is done through a collection certificate. Today, this verification is done through a collection
of ad hoc mechanisms. This document describes a protocol that a CA of ad hoc mechanisms. This document describes a protocol that a CA
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 April 15, 2019. This Internet-Draft will expire on June 20, 2019.
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 2, line 38 skipping to change at page 2, line 38
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 7 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 7
4. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 7 4. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 7
5. Character Encoding . . . . . . . . . . . . . . . . . . . . . 10 5. Character Encoding . . . . . . . . . . . . . . . . . . . . . 10
6. Message Transport . . . . . . . . . . . . . . . . . . . . . . 10 6. Message Transport . . . . . . . . . . . . . . . . . . . . . . 10
6.1. HTTPS Requests . . . . . . . . . . . . . . . . . . . . . 10 6.1. HTTPS Requests . . . . . . . . . . . . . . . . . . . . . 10
6.2. Request Authentication . . . . . . . . . . . . . . . . . 11 6.2. Request Authentication . . . . . . . . . . . . . . . . . 11
6.3. GET and POST-as-GET Requests . . . . . . . . . . . . . . 12 6.3. GET and POST-as-GET Requests . . . . . . . . . . . . . . 12
6.4. Request URL Integrity . . . . . . . . . . . . . . . . . . 13 6.4. Request URL Integrity . . . . . . . . . . . . . . . . . . 13
6.4.1. "url" (URL) JWS Header Parameter . . . . . . . . . . 14 6.4.1. "url" (URL) JWS Header Parameter . . . . . . . . . . 14
6.5. Replay protection . . . . . . . . . . . . . . . . . . . . 14 6.5. Replay protection . . . . . . . . . . . . . . . . . . . . 14
6.5.1. Replay-Nonce . . . . . . . . . . . . . . . . . . . . 14 6.5.1. Replay-Nonce . . . . . . . . . . . . . . . . . . . . 15
6.5.2. "nonce" (Nonce) JWS Header Parameter . . . . . . . . 15 6.5.2. "nonce" (Nonce) JWS Header Parameter . . . . . . . . 15
6.6. Rate Limits . . . . . . . . . . . . . . . . . . . . . . . 15 6.6. Rate Limits . . . . . . . . . . . . . . . . . . . . . . . 15
6.7. Errors . . . . . . . . . . . . . . . . . . . . . . . . . 15 6.7. Errors . . . . . . . . . . . . . . . . . . . . . . . . . 16
6.7.1. Subproblems . . . . . . . . . . . . . . . . . . . . . 17 6.7.1. Subproblems . . . . . . . . . . . . . . . . . . . . . 18
7. Certificate Management . . . . . . . . . . . . . . . . . . . 18 7. Certificate Management . . . . . . . . . . . . . . . . . . . 19
7.1. Resources . . . . . . . . . . . . . . . . . . . . . . . . 19 7.1. Resources . . . . . . . . . . . . . . . . . . . . . . . . 19
7.1.1. Directory . . . . . . . . . . . . . . . . . . . . . . 21 7.1.1. Directory . . . . . . . . . . . . . . . . . . . . . . 22
7.1.2. Account Objects . . . . . . . . . . . . . . . . . . . 23 7.1.2. Account Objects . . . . . . . . . . . . . . . . . . . 24
7.1.3. Order Objects . . . . . . . . . . . . . . . . . . . . 24 7.1.3. Order Objects . . . . . . . . . . . . . . . . . . . . 25
7.1.4. Authorization Objects . . . . . . . . . . . . . . . . 27 7.1.4. Authorization Objects . . . . . . . . . . . . . . . . 28
7.1.5. Challenge Objects . . . . . . . . . . . . . . . . . . 29 7.1.5. Challenge Objects . . . . . . . . . . . . . . . . . . 30
7.1.6. Status Changes . . . . . . . . . . . . . . . . . . . 29 7.1.6. Status Changes . . . . . . . . . . . . . . . . . . . 30
7.2. Getting a Nonce . . . . . . . . . . . . . . . . . . . . . 31 7.2. Getting a Nonce . . . . . . . . . . . . . . . . . . . . . 32
7.3. Account Creation . . . . . . . . . . . . . . . . . . . . 32 7.3. Account Management . . . . . . . . . . . . . . . . . . . 33
7.3.1. Finding an Account URL Given a Key . . . . . . . . . 34 7.3.1. Finding an Account URL Given a Key . . . . . . . . . 35
7.3.2. Account Update . . . . . . . . . . . . . . . . . . . 35 7.3.2. Account Update . . . . . . . . . . . . . . . . . . . 36
7.3.3. Changes of Terms of Service . . . . . . . . . . . . . 35 7.3.3. Changes of Terms of Service . . . . . . . . . . . . . 36
7.3.4. External Account Binding . . . . . . . . . . . . . . 36 7.3.4. External Account Binding . . . . . . . . . . . . . . 37
7.3.5. Account Key Roll-over . . . . . . . . . . . . . . . . 38 7.3.5. Account Key Roll-over . . . . . . . . . . . . . . . . 39
7.3.6. Account Deactivation . . . . . . . . . . . . . . . . 41 7.3.6. Account Deactivation . . . . . . . . . . . . . . . . 42
7.4. Applying for Certificate Issuance . . . . . . . . . . . . 42 7.4. Applying for Certificate Issuance . . . . . . . . . . . . 43
7.4.1. Pre-Authorization . . . . . . . . . . . . . . . . . . 46 7.4.1. Pre-Authorization . . . . . . . . . . . . . . . . . . 47
7.4.2. Downloading the Certificate . . . . . . . . . . . . . 48 7.4.2. Downloading the Certificate . . . . . . . . . . . . . 49
7.5. Identifier Authorization . . . . . . . . . . . . . . . . 50 7.5. Identifier Authorization . . . . . . . . . . . . . . . . 51
7.5.1. Responding to Challenges . . . . . . . . . . . . . . 52 7.5.1. Responding to Challenges . . . . . . . . . . . . . . 53
7.5.2. Deactivating an Authorization . . . . . . . . . . . . 54 7.5.2. Deactivating an Authorization . . . . . . . . . . . . 55
7.6. Certificate Revocation . . . . . . . . . . . . . . . . . 55 7.6. Certificate Revocation . . . . . . . . . . . . . . . . . 56
8. Identifier Validation Challenges . . . . . . . . . . . . . . 57 8. Identifier Validation Challenges . . . . . . . . . . . . . . 58
8.1. Key Authorizations . . . . . . . . . . . . . . . . . . . 59 8.1. Key Authorizations . . . . . . . . . . . . . . . . . . . 60
8.2. Retrying Challenges . . . . . . . . . . . . . . . . . . . 59 8.2. Retrying Challenges . . . . . . . . . . . . . . . . . . . 60
8.3. HTTP Challenge . . . . . . . . . . . . . . . . . . . . . 60 8.3. HTTP Challenge . . . . . . . . . . . . . . . . . . . . . 61
8.4. DNS Challenge . . . . . . . . . . . . . . . . . . . . . . 62 8.4. DNS Challenge . . . . . . . . . . . . . . . . . . . . . . 64
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 64 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 65
9.1. MIME Type: application/pem-certificate-chain . . . . . . 64 9.1. MIME Type: application/pem-certificate-chain . . . . . . 65
9.2. Well-Known URI for the HTTP Challenge . . . . . . . . . . 65 9.2. Well-Known URI for the HTTP Challenge . . . . . . . . . . 67
9.3. Replay-Nonce HTTP Header . . . . . . . . . . . . . . . . 66 9.3. Replay-Nonce HTTP Header . . . . . . . . . . . . . . . . 67
9.4. "url" JWS Header Parameter . . . . . . . . . . . . . . . 66 9.4. "url" JWS Header Parameter . . . . . . . . . . . . . . . 67
9.5. "nonce" JWS Header Parameter . . . . . . . . . . . . . . 66 9.5. "nonce" JWS Header Parameter . . . . . . . . . . . . . . 68
9.6. URN Sub-namespace for ACME (urn:ietf:params:acme) . . . . 67 9.6. URN Sub-namespace for ACME (urn:ietf:params:acme) . . . . 68
9.7. New Registries . . . . . . . . . . . . . . . . . . . . . 67 9.7. New Registries . . . . . . . . . . . . . . . . . . . . . 68
9.7.1. Fields in Account Objects . . . . . . . . . . . . . . 68 9.7.1. Fields in Account Objects . . . . . . . . . . . . . . 69
9.7.2. Fields in Order Objects . . . . . . . . . . . . . . . 68 9.7.2. Fields in Order Objects . . . . . . . . . . . . . . . 70
9.7.3. Fields in Authorization Objects . . . . . . . . . . . 69 9.7.3. Fields in Authorization Objects . . . . . . . . . . . 71
9.7.4. Error Types . . . . . . . . . . . . . . . . . . . . . 70 9.7.4. Error Types . . . . . . . . . . . . . . . . . . . . . 72
9.7.5. Resource Types . . . . . . . . . . . . . . . . . . . 71 9.7.5. Resource Types . . . . . . . . . . . . . . . . . . . 72
9.7.6. Fields in the "meta" Object within a Directory Object 71 9.7.6. Fields in the "meta" Object within a Directory Object 73
9.7.7. Identifier Types . . . . . . . . . . . . . . . . . . 72 9.7.7. Identifier Types . . . . . . . . . . . . . . . . . . 74
9.7.8. Validation Methods . . . . . . . . . . . . . . . . . 73 9.7.8. Validation Methods . . . . . . . . . . . . . . . . . 74
10. Security Considerations . . . . . . . . . . . . . . . . . . . 74 10. Security Considerations . . . . . . . . . . . . . . . . . . . 76
10.1. Threat Model . . . . . . . . . . . . . . . . . . . . . . 74 10.1. Threat Model . . . . . . . . . . . . . . . . . . . . . . 76
10.2. Integrity of Authorizations . . . . . . . . . . . . . . 76 10.2. Integrity of Authorizations . . . . . . . . . . . . . . 78
10.3. Denial-of-Service Considerations . . . . . . . . . . . . 79 10.3. Denial-of-Service Considerations . . . . . . . . . . . . 81
10.4. Server-Side Request Forgery . . . . . . . . . . . . . . 80 10.4. Server-Side Request Forgery . . . . . . . . . . . . . . 82
10.5. CA Policy Considerations . . . . . . . . . . . . . . . . 80 10.5. CA Policy Considerations . . . . . . . . . . . . . . . . 82
11. Operational Considerations . . . . . . . . . . . . . . . . . 82 11. Operational Considerations . . . . . . . . . . . . . . . . . 84
11.1. Key Selection . . . . . . . . . . . . . . . . . . . . . 82 11.1. Key Selection . . . . . . . . . . . . . . . . . . . . . 84
11.2. DNS security . . . . . . . . . . . . . . . . . . . . . . 83 11.2. DNS security . . . . . . . . . . . . . . . . . . . . . . 85
11.3. Token Entropy . . . . . . . . . . . . . . . . . . . . . 83 11.3. Token Entropy . . . . . . . . . . . . . . . . . . . . . 85
11.4. Malformed Certificate Chains . . . . . . . . . . . . . . 83 11.4. Malformed Certificate Chains . . . . . . . . . . . . . . 86
12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 84 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 86
13. References . . . . . . . . . . . . . . . . . . . . . . . . . 84 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 87
13.1. Normative References . . . . . . . . . . . . . . . . . . 85 13.1. Normative References . . . . . . . . . . . . . . . . . . 87
13.2. Informative References . . . . . . . . . . . . . . . . . 88 13.2. Informative References . . . . . . . . . . . . . . . . . 90
13.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 89 13.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 89 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 92
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, certification authorities (CAs) in authenticate domain names. Thus, certification authorities (CAs) in
the Web PKI are trusted to verify that an applicant for a certificate the Web 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 7, line 32 skipping to change at page 7, line 32
An ACME client authenticates to the server by means of an "account An ACME client authenticates to the server by means of an "account
key pair". The client uses the private key of this key pair to sign key pair". The client uses the private key of this key pair to sign
all messages sent to the server. The server uses the public key to all messages sent to the server. The server uses the public key to
verify the authenticity and integrity of messages from the client. verify the authenticity and integrity of messages from the client.
4. Protocol Overview 4. Protocol Overview
ACME allows a client to request certificate management actions using ACME allows a client to request certificate management actions using
a set of JavaScript Object Notation (JSON) messages carried over a set of JavaScript Object Notation (JSON) messages carried over
HTTPS. Issuance using ACME resembles a traditional CA's issuance HTTPS [RFC7159] [RFC2818]. Issuance using ACME resembles a
process, in which a user creates an account, requests a certificate, traditional CA's issuance process, in which a user creates an
and proves control of the domain(s) in that certificate in order for account, requests a certificate, and proves control of the domain(s)
the CA to issue the requested certificate. in that certificate in order for the CA to issue the requested
certificate.
The first phase of ACME is for the client to request an account with The first phase of ACME is for the client to request an account with
the ACME server. The client generates an asymmetric key pair and the ACME server. The client generates an asymmetric key pair and
requests a new account, optionally providing contact information, requests a new account, optionally providing contact information,
agreeing to terms of service, and/or associating the account with an agreeing to terms of service, and/or associating the account with an
existing account in another system. The creation request is signed existing account in another system. The creation request is signed
with the generated private key to prove that the client controls it. with the generated private key to prove that the client controls it.
Client Server Client Server
skipping to change at page 9, line 22 skipping to change at page 9, line 22
Signature -------> Signature ------->
<~~~~~~~~Validation~~~~~~~~> <~~~~~~~~Validation~~~~~~~~>
[CSR] [CSR]
Signature -------> Signature ------->
<------- Acknowledgement <------- Acknowledgement
<~~~~~~Await issuance~~~~~~> <~~~~~~Await issuance~~~~~~>
GET request -------> POST-as-GET request ------->
<------- Certificate <------- Certificate
[] Information covered by request signatures [] Information covered by request signatures
Certificate Issuance Certificate Issuance
To revoke a certificate, the client sends a signed revocation request To revoke a certificate, the client sends a signed revocation request
indicating the certificate to be revoked: indicating the certificate to be revoked:
Client Server Client Server
skipping to change at page 14, line 38 skipping to change at page 14, line 38
MUST verify that the value of the "nonce" header is a value that the MUST verify that the value of the "nonce" header is a value that the
server previously provided in a Replay-Nonce header field. Once a server previously provided in a Replay-Nonce header field. Once a
nonce value has appeared in an ACME request, the server MUST consider nonce value has appeared in an ACME request, the server MUST consider
it invalid, in the same way as a value it had never issued. it invalid, in the same way as a value it had never issued.
When a server rejects a request because its nonce value was When a server rejects a request because its nonce value was
unacceptable (or not present), it MUST provide HTTP status code 400 unacceptable (or not present), it MUST provide HTTP status code 400
(Bad Request), and indicate the ACME error type (Bad Request), and indicate the ACME error type
"urn:ietf:params:acme:error:badNonce". An error response with the "urn:ietf:params:acme:error:badNonce". An error response with the
"badNonce" error type MUST include a Replay-Nonce header with a fresh "badNonce" error type MUST include a Replay-Nonce header with a fresh
nonce. On receiving such a response, a client SHOULD retry the nonce that the server will accept in a retry of the original query
request using the new nonce. (and possibly in other requests, according to the server's nonce
scoping policy). On receiving such a response, a client SHOULD retry
the request using the new nonce.
The precise method used to generate and track nonces is up to the The precise method used to generate and track nonces is up to the
server. For example, the server could generate a random 128-bit server. For example, the server could generate a random 128-bit
value for each response, keep a list of issued nonces, and strike value for each response, keep a list of issued nonces, and strike
nonces from this list as they are used. nonces from this list as they are used.
Other than the constraint above with regard to nonces issued in
"badNonce" responses, ACME does not constrain how servers scope
nonces. Clients MAY assume that nonces have broad scope, e.g., by
having a single pool of nonces used for all requests. However, when
retrying in response to a "badNonce" error, the client MUST use the
nonce provided in the error response. Servers should scope nonces
broadly enough that retries are not needed very often.
6.5.1. Replay-Nonce 6.5.1. Replay-Nonce
The "Replay-Nonce" header field includes a server-generated value The "Replay-Nonce" header field includes a server-generated value
that the server can use to detect unauthorized replay in future that the server can use to detect unauthorized replay in future
client requests. The server MUST generate the value provided in client requests. The server MUST generate the value provided in
Replay-Nonce in such a way that they are unique to each message, with Replay-Nonce in such a way that they are unique to each message, with
high probability, and unpredictable to anyone besides the server. high probability, and unpredictable to anyone besides the server.
For instance, it is acceptable to generate Replay-Nonces randomly. For instance, it is acceptable to generate Replay-Nonces randomly.
The value of the Replay-Nonce field MUST be an octet string encoded The value of the Replay-Nonce field MUST be an octet string encoded
skipping to change at page 21, line 20 skipping to change at page 22, line 20
| Get nonce | HEAD newNonce | 200 | | Get nonce | HEAD newNonce | 200 |
| | | | | | | |
| Create account | POST newAccount | 201 -> | | Create account | POST newAccount | 201 -> |
| | | account | | | | account |
| | | | | | | |
| Submit order | POST newOrder | 201 -> order | | Submit order | POST newOrder | 201 -> order |
| | | | | | | |
| Fetch challenges | POST-as-GET order's | 200 | | Fetch challenges | POST-as-GET order's | 200 |
| | authorization urls | | | | authorization urls | |
| | | | | | | |
| Respond to | POST-as-GET authorization | 200 | | Respond to | POST authorization challenge | 200 |
| challenges | challenge urls | | | challenges | urls | |
| | | | | | | |
| Poll for status | POST-as-GET order | 200 | | Poll for status | POST-as-GET order | 200 |
| | | | | | | |
| Finalize order | POST order's finalize url | 200 | | Finalize order | POST order's finalize url | 200 |
| | | | | | | |
| Poll for status | POST-as-GET order | 200 | | Poll for status | POST-as-GET order | 200 |
| | | | | | | |
| Download | POST-as-GET order's | 200 | | Download | POST-as-GET order's | 200 |
| certificate | certificate url | | | certificate | certificate url | |
+-------------------+--------------------------------+--------------+ +-------------------+--------------------------------+--------------+
skipping to change at page 32, line 27 skipping to change at page 33, line 27
HTTP/1.1 200 OK HTTP/1.1 200 OK
Replay-Nonce: oFvnlFP1wIhRlYS2jTaXbA Replay-Nonce: oFvnlFP1wIhRlYS2jTaXbA
Cache-Control: no-store Cache-Control: no-store
Proxy caching of responses from the new-nonce resource can cause Proxy caching of responses from the new-nonce resource can cause
clients receive the same nonce repeatedly, leading to badNonce clients receive the same nonce repeatedly, leading to badNonce
errors. The server MUST include a Cache-Control header field with errors. The server MUST include a Cache-Control header field with
the "no-store" directive in responses for the new-nonce resource, in the "no-store" directive in responses for the new-nonce resource, in
order to prevent caching of this resource. order to prevent caching of this resource.
7.3. Account Creation 7.3. Account Management
In this section, we describe how an ACME client can create an account
on an ACME server, and perform some modifications to the account
after it has been created.
A client creates a new account with the server by sending a POST A client creates a new account with the server by sending a POST
request to the server's new-account URL. The body of the request is request to the server's new-account URL. The body of the request is
a stub account object optionally containing the "contact" and a stub account object containing some subset of the following fields:
"termsOfServiceAgreed" fields, and optionally the
"onlyReturnExisting" and "externalAccountBinding" fields.
contact (optional, array of string): Same meaning as the contact (optional, array of string): Same meaning as the
corresponding server field defined in Section 7.1.2 corresponding server field defined in Section 7.1.2
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
skipping to change at page 34, line 20 skipping to change at page 35, line 20
set to "true". Clients SHOULD NOT automatically agree to terms by set to "true". Clients SHOULD NOT automatically agree to terms by
default. Rather, they SHOULD require some user interaction for default. Rather, they SHOULD require some user interaction for
agreement to terms. agreement to terms.
The server creates an account and stores the public key used to The server creates an account and stores the public key used to
verify the JWS (i.e., the "jwk" element of the JWS header) to verify the JWS (i.e., the "jwk" element of the JWS header) to
authenticate future requests from the account. The server returns authenticate future requests from the account. The server returns
this account object in a 201 (Created) response, with the account URL this account object in a 201 (Created) response, with the account URL
in a Location header field. The account URL is used as the "kid" in a Location header field. The account URL is used as the "kid"
value in the JWS authenticating subsequent requests by this account value in the JWS authenticating subsequent requests by this account
(See Section 6.2). (see Section 6.2). The account URL is also used for requests for
management actions on this account, as described below.
HTTP/1.1 201 Created HTTP/1.1 201 Created
Content-Type: application/json Content-Type: application/json
Replay-Nonce: D8s4D2mLs8Vn-goWuPQeKA Replay-Nonce: D8s4D2mLs8Vn-goWuPQeKA
Location: https://example.com/acme/acct/evOfKhNU60wg Location: https://example.com/acme/acct/evOfKhNU60wg
Link: <https://example.com/acme/some-directory>;rel="index" Link: <https://example.com/acme/some-directory>;rel="index"
{ {
"status": "valid", "status": "valid",
skipping to change at page 44, line 30 skipping to change at page 45, line 30
"csr": "MIIBPTCBxAIBADBFMQ...FS6aKdZeGsysoCo4H9P", "csr": "MIIBPTCBxAIBADBFMQ...FS6aKdZeGsysoCo4H9P",
}), }),
"signature": "uOrUfIIk5RyQ...nw62Ay1cl6AB" "signature": "uOrUfIIk5RyQ...nw62Ay1cl6AB"
} }
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. set of requested identifiers as the initial new-order request.
Identifiers of type "dns" MUST appear either in the commonName Identifiers of type "dns" MUST appear either in the commonName
portion of the requested subject name, or in an extensionRequest portion of the requested subject name, or in an extensionRequest
attribute [RFC2985] requesting a subjectAltName extension. (These attribute [RFC2985] requesting a subjectAltName extension, or both.
identifiers may appear in any sort order.) Specifications that (These identifiers may appear in any sort order.) Specifications
define new identifier types must specify where in the certificate that define new identifier types must specify where in the
signing request these identifiers can appear. certificate signing request these identifiers can appear.
A request to finalize an order will result in error if the CA is A request to finalize an order will result in error if the CA is
unwilling to issue a certificate corresponding to the submitted CSR. unwilling to issue a certificate corresponding to the submitted CSR.
For example: For example:
o If the order indicated does not have status "ready" o If the order indicated does not have status "ready"
o If the CSR and order identifiers differ o If the CSR and order identifiers differ
o If the account is not authorized for the identifiers indicated in o If the account is not authorized for the identifiers indicated in
skipping to change at page 49, line 35 skipping to change at page 50, line 35
-----BEGIN CERTIFICATE----- -----BEGIN CERTIFICATE-----
[End-entity certificate contents] [End-entity certificate contents]
-----END CERTIFICATE----- -----END CERTIFICATE-----
-----BEGIN CERTIFICATE----- -----BEGIN CERTIFICATE-----
[Issuer certificate contents] [Issuer certificate contents]
-----END CERTIFICATE----- -----END CERTIFICATE-----
-----BEGIN CERTIFICATE----- -----BEGIN CERTIFICATE-----
[Other certificate contents] [Other certificate contents]
-----END CERTIFICATE----- -----END CERTIFICATE-----
An ACME client MAY attempt to fetch the certificate with a GET
request. If the server does not allow GET requests for certificate
resources, then it will return an error as described in Section 6.3.
On receiving such an error, the client SHOULD fall back to a POST-as-
GET request.
A certificate resource represents a single, immutable certificate. A certificate resource represents a single, immutable certificate.
If the client wishes to obtain a renewed certificate, the client If the client wishes to obtain a renewed certificate, the client
initiates a new order process to request one. initiates a new order process to request one.
Because certificate resources are immutable once issuance is Because certificate resources are immutable once issuance is
complete, the server MAY enable the caching of the resource by adding complete, the server MAY enable the caching of the resource by adding
Expires and Cache-Control header fields specifying a point in time in Expires and Cache-Control header fields specifying a point in time in
the distant future. These header fields have no relation to the the distant future. These header fields have no relation to the
certificate's period of validity. certificate's period of validity.
The ACME client MAY request other formats by including an Accept The ACME client MAY request other formats by including an Accept
header field [RFC7231] in its request. For example, the client could header field [RFC7231] in its request. For example, the client could
use the media type "application/pkix-cert" [RFC2585] or "applicaiton/ use the media type "application/pkix-cert" [RFC2585] or "application/
pkcs7-mime" [RFC5751] to request the end-entity certificate in DER pkcs7-mime" [RFC5751] to request the end-entity certificate in DER
format. Server support for alternate formats is OPTIONAL. For format. Server support for alternate formats is OPTIONAL. For
formats that can only express a single certificate, the server SHOULD formats that can only express a single certificate, the server SHOULD
provide one or more "Link: rel="up"" header fields pointing to an provide one or more "Link: rel="up"" header fields pointing to an
issuer or issuers so that ACME clients can build a certificate chain issuer or issuers so that ACME clients can build a certificate chain
as defined in TLS [RFC8446]. as defined in TLS (see Section 4.4.2 of [RFC8446]).
7.5. Identifier Authorization 7.5. Identifier Authorization
The identifier authorization process establishes the authorization of The identifier authorization process establishes the authorization of
an account to manage certificates for a given identifier. This an account to manage certificates for a given identifier. This
process assures the server of two things: process assures the server of two things:
1. That the client controls the private key of the account key pair, 1. That the client controls the private key of the account key pair,
and and
skipping to change at page 61, line 36 skipping to change at page 62, line 36
Content-Type: application/octet-stream Content-Type: application/octet-stream
LoqXcYV8...jxAjEuX0.9jg46WB3...fm21mqTI LoqXcYV8...jxAjEuX0.9jg46WB3...fm21mqTI
(In the above, "..." indicates that the token and the JWK thumbprint (In the above, "..." indicates that the token and the JWK thumbprint
in the key authorization have been truncated to fit on the page.) in the key authorization have been truncated to fit on the page.)
A client responds with an empty object ({}) to acknowledge that the A client responds with an empty object ({}) to acknowledge that the
challenge can be validated by the server. challenge can be validated by the server.
POST /acme/authz/PAniVnsZcis/0 POST /acme/chall/prV_B7yEyA4
Host: example.com Host: example.com
Content-Type: application/jose+json Content-Type: application/jose+json
{ {
"protected": base64url({ "protected": base64url({
"alg": "ES256", "alg": "ES256",
"kid": "https://example.com/acme/acct/evOfKhNU60wg", "kid": "https://example.com/acme/acct/evOfKhNU60wg",
"nonce": "UQI1PoRi5OuXzxuX7V7wL0", "nonce": "UQI1PoRi5OuXzxuX7V7wL0",
"url": "https://example.com/acme/chall/prV_B7yEyA4" "url": "https://example.com/acme/chall/prV_B7yEyA4"
}), }),
skipping to change at page 62, line 44 skipping to change at page 63, line 44
Section 10.2 for security considerations related to redirects. Section 10.2 for security considerations related to redirects.
If all of the above verifications succeed, then the validation is If all of the above verifications succeed, then the validation is
successful. If the request fails, or the body does not pass these successful. If the request fails, or the body does not pass these
checks, then it has failed. checks, then it has failed.
The client SHOULD de-provision the resource provisioned for this The client SHOULD de-provision the resource provisioned for this
challenge once the challenge is complete, i.e., once the "status" challenge once the challenge is complete, i.e., once the "status"
field of the challenge has the value "valid" or "invalid". field of the challenge has the value "valid" or "invalid".
Note that becuase the token appears both in the request sent by the
ACME server and in the key authorization in the response, it is
possible to build clients that copy the token from request to
response. Clients should avoid this behavior, because it can lead to
cross-site scripting vulnerabilities; instead, clients should be
explicitly configured on a per-challenge basis. A client that does
copy tokens from requests to responses MUST validate that the token
in the request matches the token syntax above (e.g., that it includes
only characters from the base64url alphabet).
8.4. DNS Challenge 8.4. DNS Challenge
When the identifier being validated is a domain name, the client can When the identifier being validated is a domain name, the client can
prove control of that domain by provisioning a TXT resource record prove control of that domain by provisioning a TXT resource record
containing a designated value for a specific validation domain name. containing a designated value for a specific validation domain name.
type (required, string): The string "dns-01" type (required, string): The string "dns-01"
token (required, string): A random value that uniquely identifies token (required, string): A random value that uniquely identifies
the challenge. This value MUST have at least 128 bits of entropy. the challenge. This value MUST have at least 128 bits of entropy.
It MUST NOT contain any characters outside the base64url alphabet, It MUST NOT contain any characters outside the base64url alphabet,
including padding characters ("="). See [RFC4086] for additional including padding characters ("="). See [RFC4086] for additional
information on randomness requirements. information on randomness requirements.
{ {
"type": "dns-01", "type": "dns-01",
"url": "https://example.com/acme/chall/Rg5dV14Gh1Q", "url": "https://example.com/acme/chall/Rg5dV14Gh1Q",
"status": "pending", "status": "pending",
skipping to change at page 68, line 19 skipping to change at page 69, line 30
a new-account request. a new-account request.
Template: Template:
o Field name: The string to be used as a field name in the JSON o Field name: The string to be used as a field name in the JSON
object object
o Field type: The type of value to be provided, e.g., string, o Field type: The type of value to be provided, e.g., string,
boolean, array of string boolean, array of string
o Client configurable: Boolean indicating whether the server should o Requests: Either the value "none" or a list of types of requests
accept values provided by the client where the field is allowed in a request object, taken from the
following values:
* "new" - Requests to the "newAccount" URL
* "account" - Requests to an account URL
o Reference: Where this field is defined o Reference: Where this field is defined
Initial contents: The fields and descriptions defined in Initial contents: The fields and descriptions defined in
Section 7.1.2. Section 7.1.2.
+------------------------+---------------+--------------+-----------+ +------------------------+---------------+--------------+-----------+
| Field Name | Field Type | Configurable | Reference | | Field Name | Field Type | Requests | Reference |
+------------------------+---------------+--------------+-----------+ +------------------------+---------------+--------------+-----------+
| status | string | false | RFC XXXX | | status | string | new, account | RFC XXXX |
| | | | | | | | | |
| contact | array of | true | RFC XXXX | | contact | array of | new, account | RFC XXXX |
| | string | | | | | string | | |
| | | | | | | | | |
| externalAccountBinding | object | true | RFC XXXX | | externalAccountBinding | object | new | RFC XXXX |
| | | | | | | | | |
| termsOfServiceAgreed | boolean | true | RFC XXXX | | termsOfServiceAgreed | boolean | new | RFC XXXX |
| | | | | | | | | |
| orders | string | false | RFC XXXX | | orders | string | none | RFC XXXX |
+------------------------+---------------+--------------+-----------+ +------------------------+---------------+--------------+-----------+
[[ 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.
skipping to change at page 82, line 44 skipping to change at page 84, line 44
1. Issuing certificates using existing authorizations 1. Issuing certificates using existing authorizations
2. Revoking existing certificates 2. Revoking existing certificates
3. Accessing and changing account information (e.g., contacts) 3. Accessing and changing account information (e.g., contacts)
4. Changing the account key pair for the account, locking out the 4. Changing the account key pair for the account, locking out the
legitimate account holder legitimate account holder
For this reason, it is RECOMMENDED that account key pairs be used for For this reason, it is RECOMMENDED that each account key pair be used
no other purpose besides ACME authentication. For example, the only for authentication of a single ACME account. For example, the
public key of an account key pair SHOULD NOT be included in a public key of an account key pair MUST NOT be included in a
certificate. ACME clients and servers SHOULD verify that a CSR certificate. If an ACME client receives a request from a user for
submitted in a finalize request does not contain a public key for any account creation or key roll-over using an account key that the
known account key pair. In particular, when a server receives a client knows to be used elsewhere, then the client MUST return an
finalize request, it MUST verify that the public key in a CSR is not error. Clients that manage account keys on behalf of users SHOULD
the same as the public key of the account key pair used to generate a fresh account key for every account creation or roll-over
authenticate that request. This assures that vulnerabilities in the operation. Note that given the requirements of Section 7.3.1,
protocols with which the certificate is used (e.g., signing oracles servers will not create accounts with reused keys anyway.
in TLS [JSS15]) do not result in compromise of the ACME account.
Because ACME accounts are uniquely identified by their account key ACME clients and servers MUST verify that a CSR submitted in a
pair (see Section 7.3.1) the server MUST not allow account key pair finalize request does not contain a public key for any known account
reuse across multiple accounts. 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.
This assures that vulnerabilities in the protocols with which the
certificate is used (e.g., signing oracles in TLS [JSS15]) do not
result in compromise of the ACME account. Because ACME accounts are
uniquely identified by their account key pair (see Section 7.3.1) the
server MUST not allow account key pair reuse across multiple
accounts.
11.2. DNS security 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
skipping to change at page 83, line 44 skipping to change at page 86, line 4
11.3. 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 makes it more difficult for ACME clients to implement a "naive"
that automatically replies to challenges by predicting the token. validation server that automatically replies to challenges without
being configured per-challenge.
11.4. 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
a certificate URL. a certificate URL.
When processing an file of type "application/pem-certificate-chain", When processing a file of type "application/pem-certificate-chain", a
a client SHOULD verify that the file contains only encoded client SHOULD verify that the file contains only encoded
certificates. If anything other than a certificate is found (i.e., certificates. If anything other than a certificate is found (i.e.,
if the string "-----BEGIN" is ever followed by anything other than if the string "-----BEGIN" is ever followed by anything other than
"CERTIFICATE"), then the client MUST reject the file as invalid. "CERTIFICATE"), then the client MUST reject the file as invalid.
12. Acknowledgements 12. Acknowledgements
In addition to the editors listed on the front page, this document In addition to the editors listed on the front page, this document
has benefited from contributions from a broad set of contributors, has benefited from contributions from a broad set of contributors,
all the way back to its inception. all the way back to its inception.
 End of changes. 32 change blocks. 
120 lines changed or deleted 153 lines changed or added

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