draft-ietf-acme-acme-09.txt   draft-ietf-acme-acme-10.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: June 17, 2018 EFF Expires: September 6, 2018 EFF
D. McCarney D. McCarney
Let's Encrypt Let's Encrypt
J. Kasten J. Kasten
University of Michigan University of Michigan
December 14, 2017 March 05, 2018
Automatic Certificate Management Environment (ACME) Automatic Certificate Management Environment (ACME)
draft-ietf-acme-acme-09 draft-ietf-acme-acme-10
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 June 17, 2018. This Internet-Draft will expire on September 6, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2017 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
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
skipping to change at page 2, line 34 skipping to change at page 2, line 34
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Deployment Model and Operator Experience . . . . . . . . . . 5 2. Deployment Model and Operator Experience . . . . . . . . . . 5
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6
4. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 7 4. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 7
5. Character Encoding . . . . . . . . . . . . . . . . . . . . . 9 5. Character Encoding . . . . . . . . . . . . . . . . . . . . . 9
6. Message Transport . . . . . . . . . . . . . . . . . . . . . . 9 6. Message Transport . . . . . . . . . . . . . . . . . . . . . . 9
6.1. HTTPS Requests . . . . . . . . . . . . . . . . . . . . . 9 6.1. HTTPS Requests . . . . . . . . . . . . . . . . . . . . . 9
6.2. Request Authentication . . . . . . . . . . . . . . . . . 10 6.2. Request Authentication . . . . . . . . . . . . . . . . . 10
6.3. Request URL Integrity . . . . . . . . . . . . . . . . . . 11 6.3. Request URL Integrity . . . . . . . . . . . . . . . . . . 12
6.3.1. "url" (URL) JWS Header Parameter . . . . . . . . . . 12 6.3.1. "url" (URL) JWS Header Parameter . . . . . . . . . . 12
6.4. Replay protection . . . . . . . . . . . . . . . . . . . . 12 6.4. Replay protection . . . . . . . . . . . . . . . . . . . . 12
6.4.1. Replay-Nonce . . . . . . . . . . . . . . . . . . . . 12 6.4.1. Replay-Nonce . . . . . . . . . . . . . . . . . . . . 13
6.4.2. "nonce" (Nonce) JWS Header Parameter . . . . . . . . 13 6.4.2. "nonce" (Nonce) JWS Header Parameter . . . . . . . . 14
6.5. Rate Limits . . . . . . . . . . . . . . . . . . . . . . . 13 6.5. Rate Limits . . . . . . . . . . . . . . . . . . . . . . . 14
6.6. Errors . . . . . . . . . . . . . . . . . . . . . . . . . 13 6.6. Errors . . . . . . . . . . . . . . . . . . . . . . . . . 14
6.6.1. Subproblems . . . . . . . . . . . . . . . . . . . . . 15 6.6.1. Subproblems . . . . . . . . . . . . . . . . . . . . . 16
7. Certificate Management . . . . . . . . . . . . . . . . . . . 16 7. Certificate Management . . . . . . . . . . . . . . . . . . . 17
7.1. Resources . . . . . . . . . . . . . . . . . . . . . . . . 17 7.1. Resources . . . . . . . . . . . . . . . . . . . . . . . . 17
7.1.1. Directory . . . . . . . . . . . . . . . . . . . . . . 19 7.1.1. Directory . . . . . . . . . . . . . . . . . . . . . . 20
7.1.2. Account Objects . . . . . . . . . . . . . . . . . . . 21 7.1.2. Account Objects . . . . . . . . . . . . . . . . . . . 22
7.1.3. Order Objects . . . . . . . . . . . . . . . . . . . . 22 7.1.3. Order Objects . . . . . . . . . . . . . . . . . . . . 23
7.1.4. Authorization Objects . . . . . . . . . . . . . . . . 24 7.1.4. Authorization Objects . . . . . . . . . . . . . . . . 26
7.2. Getting a Nonce . . . . . . . . . . . . . . . . . . . . . 26 7.1.5. Challenge Objects . . . . . . . . . . . . . . . . . . 27
7.3. Account Creation . . . . . . . . . . . . . . . . . . . . 27 7.1.6. Status Changes . . . . . . . . . . . . . . . . . . . 27
7.3.1. Finding an Account URL Given a Key . . . . . . . . . 29 7.2. Getting a Nonce . . . . . . . . . . . . . . . . . . . . . 30
7.3.2. Account Update . . . . . . . . . . . . . . . . . . . 29 7.3. Account Creation . . . . . . . . . . . . . . . . . . . . 31
7.3.3. Account Information . . . . . . . . . . . . . . . . . 30 7.3.1. Finding an Account URL Given a Key . . . . . . . . . 33
7.3.4. Changes of Terms of Service . . . . . . . . . . . . . 30 7.3.2. Account Update . . . . . . . . . . . . . . . . . . . 33
7.3.5. External Account Binding . . . . . . . . . . . . . . 30 7.3.3. Account Information . . . . . . . . . . . . . . . . . 34
7.3.6. Account Key Roll-over . . . . . . . . . . . . . . . . 33 7.3.4. Changes of Terms of Service . . . . . . . . . . . . . 34
7.3.7. Account Deactivation . . . . . . . . . . . . . . . . 35 7.3.5. External Account Binding . . . . . . . . . . . . . . 35
7.4. Applying for Certificate Issuance . . . . . . . . . . . . 36 7.3.6. Account Key Roll-over . . . . . . . . . . . . . . . . 37
7.4.1. Pre-Authorization . . . . . . . . . . . . . . . . . . 40 7.3.7. Account Deactivation . . . . . . . . . . . . . . . . 39
7.4.2. Downloading the Certificate . . . . . . . . . . . . . 42 7.4. Applying for Certificate Issuance . . . . . . . . . . . . 40
7.5. Identifier Authorization . . . . . . . . . . . . . . . . 43 7.4.1. Pre-Authorization . . . . . . . . . . . . . . . . . . 44
7.5.1. Responding to Challenges . . . . . . . . . . . . . . 44 7.4.2. Downloading the Certificate . . . . . . . . . . . . . 46
7.5.2. Deactivating an Authorization . . . . . . . . . . . . 46 7.5. Identifier Authorization . . . . . . . . . . . . . . . . 47
7.6. Certificate Revocation . . . . . . . . . . . . . . . . . 47 7.5.1. Responding to Challenges . . . . . . . . . . . . . . 48
8. Identifier Validation Challenges . . . . . . . . . . . . . . 49 7.5.2. Deactivating an Authorization . . . . . . . . . . . . 50
8.1. Key Authorizations . . . . . . . . . . . . . . . . . . . 51 7.6. Certificate Revocation . . . . . . . . . . . . . . . . . 51
8.2. Retrying Challenges . . . . . . . . . . . . . . . . . . . 51 8. Identifier Validation Challenges . . . . . . . . . . . . . . 53
8.3. HTTP Challenge . . . . . . . . . . . . . . . . . . . . . 52 8.1. Key Authorizations . . . . . . . . . . . . . . . . . . . 55
8.4. TLS with Server Name Indication (TLS SNI) Challenge . . . 54 8.2. Retrying Challenges . . . . . . . . . . . . . . . . . . . 55
8.5. DNS Challenge . . . . . . . . . . . . . . . . . . . . . . 57 8.3. HTTP Challenge . . . . . . . . . . . . . . . . . . . . . 56
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 58 8.4. DNS Challenge . . . . . . . . . . . . . . . . . . . . . . 58
9.1. MIME Type: application/pem-certificate-chain . . . . . . 58 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 60
9.2. Well-Known URI for the HTTP Challenge . . . . . . . . . . 59 9.1. MIME Type: application/pem-certificate-chain . . . . . . 60
9.3. Replay-Nonce HTTP Header . . . . . . . . . . . . . . . . 59 9.2. Well-Known URI for the HTTP Challenge . . . . . . . . . . 61
9.4. "url" JWS Header Parameter . . . . . . . . . . . . . . . 60 9.3. Replay-Nonce HTTP Header . . . . . . . . . . . . . . . . 61
9.5. "nonce" JWS Header Parameter . . . . . . . . . . . . . . 60 9.4. "url" JWS Header Parameter . . . . . . . . . . . . . . . 61
9.6. URN Sub-namespace for ACME (urn:ietf:params:acme) . . . . 60 9.5. "nonce" JWS Header Parameter . . . . . . . . . . . . . . 62
9.7. New Registries . . . . . . . . . . . . . . . . . . . . . 61 9.6. URN Sub-namespace for ACME (urn:ietf:params:acme) . . . . 62
9.7.1. Fields in Account Objects . . . . . . . . . . . . . . 61 9.7. New Registries . . . . . . . . . . . . . . . . . . . . . 62
9.7.2. Fields in Order Objects . . . . . . . . . . . . . . . 62 9.7.1. Fields in Account Objects . . . . . . . . . . . . . . 63
9.7.3. Fields in Authorization Objects . . . . . . . . . . . 63 9.7.2. Fields in Order Objects . . . . . . . . . . . . . . . 64
9.7.4. Error Types . . . . . . . . . . . . . . . . . . . . . 64 9.7.3. Fields in Authorization Objects . . . . . . . . . . . 65
9.7.5. Resource Types . . . . . . . . . . . . . . . . . . . 64 9.7.4. Error Types . . . . . . . . . . . . . . . . . . . . . 66
9.7.6. Fields in the "meta" Object within a Directory Object 65 9.7.5. Resource Types . . . . . . . . . . . . . . . . . . . 66
9.7.7. Identifier Types . . . . . . . . . . . . . . . . . . 66 9.7.6. Fields in the "meta" Object within a Directory Object 67
9.7.8. Validation Methods . . . . . . . . . . . . . . . . . 66 9.7.7. Identifier Types . . . . . . . . . . . . . . . . . . 68
10. Security Considerations . . . . . . . . . . . . . . . . . . . 67 9.7.8. Validation Methods . . . . . . . . . . . . . . . . . 68
10.1. Threat Model . . . . . . . . . . . . . . . . . . . . . . 68 10. Security Considerations . . . . . . . . . . . . . . . . . . . 69
10.2. Integrity of Authorizations . . . . . . . . . . . . . . 69 10.1. Threat Model . . . . . . . . . . . . . . . . . . . . . . 70
10.3. Denial-of-Service Considerations . . . . . . . . . . . . 71 10.2. Integrity of Authorizations . . . . . . . . . . . . . . 71
10.4. Server-Side Request Forgery . . . . . . . . . . . . . . 72 10.3. Denial-of-Service Considerations . . . . . . . . . . . . 73
10.5. CA Policy Considerations . . . . . . . . . . . . . . . . 72 10.4. Server-Side Request Forgery . . . . . . . . . . . . . . 74
11. Operational Considerations . . . . . . . . . . . . . . . . . 73 10.5. CA Policy Considerations . . . . . . . . . . . . . . . . 74
11.1. DNS security . . . . . . . . . . . . . . . . . . . . . . 73 11. Operational Considerations . . . . . . . . . . . . . . . . . 75
11.2. Default Virtual Hosts . . . . . . . . . . . . . . . . . 74 11.1. DNS security . . . . . . . . . . . . . . . . . . . . . . 75
11.3. Token Entropy . . . . . . . . . . . . . . . . . . . . . 75 11.2. Token Entropy . . . . . . . . . . . . . . . . . . . . . 76
11.4. Malformed Certificate Chains . . . . . . . . . . . . . . 75 11.3. Malformed Certificate Chains . . . . . . . . . . . . . . 76
12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 75 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 76
13. References . . . . . . . . . . . . . . . . . . . . . . . . . 76 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 77
13.1. Normative References . . . . . . . . . . . . . . . . . . 76 13.1. Normative References . . . . . . . . . . . . . . . . . . 77
13.2. Informative References . . . . . . . . . . . . . . . . . 78 13.2. Informative References . . . . . . . . . . . . . . . . . 80
13.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 80 13.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 80 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 81
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 4, line 41 skipping to change at page 4, line 41
o Cut-and-paste the CSR into a CA web page. o Cut-and-paste the CSR into a CA web page.
o Prove ownership of the domain by one of the following methods: o Prove ownership of the domain by one of the following methods:
* Put a CA-provided challenge at a specific place on the web * Put a CA-provided challenge at a specific place on the web
server. server.
* Put a CA-provided challenge in a DNS record corresponding to * Put a CA-provided challenge in a DNS record corresponding to
the target domain. the target domain.
* Receive CA-provided challenge at a (hopefully) administrator- * Receive a CA-provided challenge at a (hopefully) administrator-
controlled email address corresponding to the domain and then controlled email address corresponding to the domain and then
respond to it on the CA's web page. respond to it on the CA's web page.
o Download the issued certificate and install it on their Web o Download the issued certificate and install it on their Web
Server. Server.
With the exception of the CSR itself and the certificates that are With the exception of the CSR itself and the certificates that are
issued, these are all completely ad hoc procedures and are issued, these are all completely ad hoc procedures and are
accomplished by getting the human user to follow interactive natural- accomplished by getting the human user to follow interactive natural-
language instructions from the CA rather than by machine-implemented language instructions from the CA rather than by machine-implemented
skipping to change at page 5, line 31 skipping to change at page 5, line 31
validating domain names for purposes of issuing certificates in the validating domain names for purposes of issuing certificates in the
Web PKI, ACME supports extensions for uses with other identifiers in Web PKI, ACME supports extensions for uses with other identifiers in
other PKI contexts. For example, as of this writing, there is other PKI contexts. For example, as of this writing, there is
ongoing work to use ACME for issuance of WebPKI certificates ongoing work to use ACME for issuance of WebPKI certificates
attesting to IP addresses [I-D.ietf-acme-ip] and STIR certificates attesting to IP addresses [I-D.ietf-acme-ip] and STIR certificates
attesting to telephone numbers [I-D.ietf-acme-telephone]. attesting to telephone numbers [I-D.ietf-acme-telephone].
ACME can also be used to automate some aspects of certificate ACME can also be used to automate some aspects of certificate
management even where non-automated processes are still needed. For management even where non-automated processes are still needed. For
example, the external account binding feature (see Section 7.3.5) can example, the external account binding feature (see Section 7.3.5) can
be used to associate authorizations with an account that were not allow an ACME account to use authorizations that have been granted to
validated through the ACME authorization process. This allows ACME an external, non-ACME account. This allows ACME to address issuance
to address issuance scenarios that cannot yet be fully automated, scenarios that cannot yet be fully automated, such as the issuance of
such as the issuance of Extended Validation certificates. Extended Validation certificates.
2. Deployment Model and Operator Experience 2. Deployment Model and Operator Experience
The guiding use case for ACME is obtaining certificates for websites The guiding use case for ACME is obtaining certificates for websites
(HTTPS [RFC2818]). In this case, the user's web server is intended (HTTPS [RFC2818]). In this case, the user's web server is intended
to speak for one or more domains, and the process of certificate to speak for one or more domains, and the process of certificate
issuance is intended to verify that this web server actually speaks issuance is intended to verify that this web server actually speaks
for the domain(s). for the domain(s).
DV certificate validation commonly checks claims about properties DV certificate validation commonly checks claims about properties
skipping to change at page 7, line 21 skipping to change at page 7, line 21
An ACME client is represented by an "account key pair". The client An ACME client is represented by an "account key pair". The client
uses the private key of this key pair to sign all messages sent to uses the private key of this key pair to sign all messages sent to
the server. The server uses the public key to verify the the server. The server uses the public key to verify the
authenticity and integrity of messages from the client. 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. HTTPS. Issuance using ACME resembles a traditional CA's issuance
Issuance using ACME resembles a traditional CA's issuance process, in process, in which a user creates an account, requests a certificate,
which a user creates an account, requests a certificate, and proves and proves control of the domain(s) in that certificate in order for
control of the domains in that certificate in order for the CA to the CA to sign the requested certificate.
sign 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
Contact Information Contact Information
ToS Agreement ToS Agreement
Additional Data Additional Data
Signature -------> Signature ------->
<------- Account <------- Account
Once an account is registered, there are three major steps the client Once an account is registered, there are four major steps the client
needs to take to get a certificate: needs to take to get a certificate:
1. Submit an order for a certificate to be issued 1. Submit an order for a certificate to be issued
2. Prove control of any identifiers requested in the certificate 2. Prove control of any identifiers requested in the certificate
3. Await issuance and download the issued certificate 3. Finalize the order by submitting a CSR
4. Await issuance and download the issued certificate
The client's order for a certificate describes the desired The client's order for a certificate describes the desired
certificate using a PKCS#10 Certificate Signing Request (CSR) plus a identifiers plus a few additional fields that capture semantics that
few additional fields that capture semantics that are not supported are not supported in the CSR format. If the server is willing to
in the CSR format. If the server is willing to consider issuing such consider issuing such a certificate, it responds with a list of
a certificate, it responds with a list of requirements that the requirements that the client must satisfy before the certificate will
client must satisfy before the certificate will be issued. be issued.
For example, in most cases, the server will require the client to For example, in most cases, the server will require the client to
demonstrate that it controls the identifiers in the requested demonstrate that it controls the identifiers in the requested
certificate. Because there are many different ways to validate certificate. Because there are many different ways to validate
possession of different types of identifiers, the server will choose possession of different types of identifiers, the server will choose
from an extensible set of challenges that are appropriate for the from an extensible set of challenges that are appropriate for the
identifier being claimed. The client responds with a set of identifier being claimed. The client responds with a set of
responses that tell the server which challenges the client has responses that tell the server which challenges the client has
completed. The server then validates that the client has completed completed. The server then validates that the client has completed
the challenges. the challenges.
Once the validation process is complete and the server is satisfied Once the validation process is complete and the server is satisfied
that the client has met its requirements, the server will issue the that the client has met its requirements, the client finalizes the
requested certificate and make it available to the client. order by submitting a PKCS#10 Certificate Signing Request (CSR). The
server will issue the requested certificate and make it available to
the client.
Client Server
Order Order
Signature -------> Signature ------->
<------- Required Authorizations <------- Required Authorizations
Responses Responses
Signature -------> Signature ------->
<~~~~~~~~Validation~~~~~~~~> <~~~~~~~~Validation~~~~~~~~>
CSR
Signature ------->
<~~~~~~Await issuance~~~~~~>
<------- Certificate <------- Certificate
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
Revocation request Revocation request
Signature --------> Signature -------->
skipping to change at page 9, line 38 skipping to change at page 9, line 52
[RFC2818][RFC7159]. Use of HTTPS is REQUIRED. Each subsection of [RFC2818][RFC7159]. Use of HTTPS is REQUIRED. Each subsection of
Section 7 below describes the message formats used by the function Section 7 below describes the message formats used by the function
and the order in which messages are sent. and the order in which messages are sent.
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 (0xRTT). 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 SHOULD send a User-Agent header in accordance with
[RFC7231], including the name and version of the ACME software in [RFC7231], including the name and version of the ACME software in
addition to the name and version of the underlying HTTP client addition to the name and version of the underlying HTTP client
software. 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.
skipping to change at page 10, line 24 skipping to change at page 10, line 37
All ACME requests with a non-empty body MUST encapsulate their All ACME requests with a non-empty body MUST encapsulate their
payload in a JSON Web Signature (JWS) [RFC7515] object, signed using payload in a JSON Web Signature (JWS) [RFC7515] object, signed using
the account's private key unless otherwise specified. The server the account's private key unless otherwise specified. The server
MUST verify the JWS before processing the request. Encapsulating MUST verify the JWS before processing the request. Encapsulating
request bodies in JWS provides authentication of requests. request bodies in JWS provides authentication of requests.
JWS objects sent in ACME requests MUST meet the following additional JWS objects sent in ACME requests MUST meet the following additional
criteria: criteria:
o The JWS MUST be in the Flattened JSON Serialization [RFC7515]
o The JWS MUST NOT have the value "none" in its "alg" field o The JWS MUST NOT have the value "none" in its "alg" field
o The JWS MUST NOT have multiple signatures
o The JWS Unencoded Payload Option [RFC7797] 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 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, only for requests to new-account and * "jwk" (JSON Web Key, for all requests not signed using an
revoke-cert resources) existing account, e.g. newAccount)
* "kid" (Key ID, for all other requests) * "kid" (Key ID, for all requests signed using an existing
account)
* "nonce" (defined in Section 6.4 below) * "nonce" (defined in Section 6.4 below)
* "url" (defined in Section 6.3 below) * "url" (defined in Section 6.3 below)
The "jwk" and "kid" fields are mutually exclusive. Servers MUST The "jwk" and "kid" fields are mutually exclusive. Servers MUST
reject requests that contain both. reject requests that contain both.
For new-account requests, and for revoke-cert requests authenticated For newAccount requests, and for revokeCert requests authenticated by
by certificate key, there MUST be a "jwk" field. certificate key, there MUST be a "jwk" field. This field MUST
contain the public key corresponding to the private key used to sign
the JWS.
For all other requests, there MUST be a "kid" field. This field must For all other requests, the request is signed using an existing
contain the account URL received by POSTing to the new-account account and there MUST be a "kid" field. This field MUST contain the
resource. account URL received by POSTing to the newAccount resource.
Note that authentication via signed JWS request bodies implies that Note that authentication via signed JWS request bodies implies that
GET requests are not authenticated. Servers MUST NOT respond to GET GET requests are not authenticated. Servers MUST NOT respond to GET
requests for resources that might be considered sensitive. Account requests for resources that might be considered sensitive. Account
resources are the only sensitive resources defined in this resources are the only sensitive resources defined in this
specification. specification.
If the client sends a JWS signed with an algorithm that the server If the client sends a JWS signed with an algorithm that the server
does not support, then the server MUST return an error with status does not support, then the server MUST return an error with status
code 400 (Bad Request) and type code 400 (Bad Request) and type
"urn:ietf:params:acme:error:badSignatureAlgorithm". The problem "urn:ietf:params:acme:error:badSignatureAlgorithm". The problem
document returned with the error MUST include an "algorithms" field document returned with the error MUST include an "algorithms" field
with an array of supported "alg" values. with an array of supported "alg" values.
In the examples below, JWS objects are shown in the JSON or flattened Because client requests in ACME carry JWS objects in the Flattened
JSON serialization, with the protected header and payload expressed JSON Serialization, they must have the "Content-Type" header field
as base64url(content) instead of the actual base64-encoded value, so set to "application/jose+json". If a request does not meet this
that the content is readable. requirement, then the server MUST return a response with status code
415 (Unsupported Media Type).
6.3. Request URL Integrity 6.3. Request URL Integrity
It is common in deployment for the entity terminating TLS for HTTPS It is common in deployment for the entity terminating TLS for HTTPS
to be different from the entity operating the logical HTTPS server, to be different from the entity operating the logical HTTPS server,
with a "request routing" layer in the middle. For example, an ACME with a "request routing" layer in the middle. For example, an ACME
CA might have a content delivery network terminate TLS connections CA might have a content delivery network terminate TLS connections
from clients so that it can inspect client requests for denial-of- from clients so that it can inspect client requests for denial-of-
service protection. service protection.
skipping to change at page 18, line 12 skipping to change at page 19, line 7
The "index" link relation is present on all resources other than the The "index" link relation is present on all resources other than the
directory and indicates the URL of the directory. directory and indicates the URL of the directory.
The following diagram illustrates the relations between resources on The following diagram illustrates the relations between resources on
an ACME server. For the most part, these relations are expressed by an ACME server. For the most part, these relations are expressed by
URLs provided as strings in the resources' JSON representations. URLs provided as strings in the resources' JSON representations.
Lines with labels in quotes indicate HTTP link relations. Lines with labels in quotes indicate HTTP link relations.
directory directory
| |
+--> new-nonce +--> 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 -----> cert account | order -----> finalize
| | | | -----> cert
| | | |
| V | V
+------> authz +---> authorizations
| ^ | ^
| | "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.
+----------------------+---------------------+----------------+ +-----------------------+--------------------------+----------------+
| Action | Request | Response | | Action | Request | Response |
+----------------------+---------------------+----------------+ +-----------------------+--------------------------+----------------+
| Get a nonce | HEAD newNonce | 204 | | Get directory | GET directory | 200 |
| | | | | | | |
| Create account | POST newAccount | 201 -> account | | Get nonce | HEAD newNonce | 200 |
| | | | | | | |
| Submit an order | POST newOrder | 201 -> order | | Create account | POST newAccount | 201 -> account |
| | | | | | | |
| Fetch challenges | GET authz | 200 | | Submit order | POST newOrder | 201 -> order |
| | | | | | | |
| Respond to challenge | POST challenge | 200 | | Fetch challenges | GET order | 200 |
| | | | | | authorizations | |
| Finalize order | POST order finalize | 200 | | | | |
| | | | | Respond to challenges | POST challenge urls | 200 |
| Poll for status | GET authz | 200 | | | | |
| | | | | Finalize order | POST order finalize | 200 |
| Check for new cert | GET cert | 200 | | | | |
+----------------------+---------------------+----------------+ | Poll for status | GET order | 200 |
| | | |
| Download certificate | GET order cert | 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
object, whose field names are drawn from the following table and object, whose field names are drawn from the following table and
skipping to change at page 20, line 16 skipping to change at page 21, line 32
should be different from the other ACME server resources' URLs, and should be different from the other ACME server resources' URLs, and
that it should not clash with other services. For instance: that it should not clash with other services. For instance:
o a host which functions as both an ACME and a Web server may want o a host which functions as both an ACME and a Web server may want
to keep the root path "/" for an HTML "front page", and place the to keep the root path "/" for an HTML "front page", and place the
ACME directory under the path "/acme". ACME directory under the path "/acme".
o a host which only functions as an ACME server could place the o a host which only functions as an ACME server could place the
directory under the path "/". directory under the path "/".
If the ACME server does not implement pre-authorization
(Section 7.4.1) it MUST omit the "newAuthz" field of the directory.
The object MAY additionally contain a field "meta". If present, it The object MAY additionally contain a field "meta". If present, it
MUST be a JSON object; each field in the object is an item of MUST be a JSON object; each field in the object is an item of
metadata relating to the service provided by the ACME server. metadata relating to the service provided by the ACME server.
The following metadata items are defined, all of which are OPTIONAL: The following metadata items are defined, all of which are OPTIONAL:
termsOfService (optional, string): A URL identifying the current termsOfService (optional, string): A URL identifying the current
terms of service. terms of service.
website (optional, string): An HTTP or HTTPS URL locating a website website (optional, string): An HTTP or HTTPS URL locating a website
skipping to change at page 22, line 48 skipping to change at page 24, line 6
7.1.3. Order Objects 7.1.3. Order Objects
An ACME order object represents a client's request for a certificate An ACME order object represents a client's request for a certificate
and is used to track the progress of that order through to issuance. and is used to track the progress of that order through to issuance.
Thus, the object contains information about the requested Thus, the object contains information about the requested
certificate, the authorizations that the server requires the client certificate, the authorizations that the server requires the client
to complete, and any certificates that have resulted from this order. to complete, and any certificates that have resulted from this order.
status (required, string): The status of this order. Possible status (required, string): The status of this order. Possible
values are: "pending", "processing", "valid", and "invalid". values are: "pending", "ready", "processing", "valid", and
"invalid".
expires (optional, string): The timestamp after which the server expires (optional, string): The timestamp after which the server
will consider this order invalid, encoded in the format specified will consider this order invalid, encoded in the format specified
in RFC 3339 [RFC3339]. This field is REQUIRED for objects with in RFC 3339 [RFC3339]. This field is REQUIRED for objects with
"pending" or "valid" in the status field. "pending" or "valid" in the status field.
identifiers (required, array of object): An array of identifier identifiers (required, array of object): An array of identifier
objects that the order pertains to. objects that the order pertains to.
type (required, string): The type of identifier. type (required, string): The type of identifier.
skipping to change at page 23, line 31 skipping to change at page 24, line 38
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). For final
orders (in the "valid" or "invalid" state), the authorizations orders (in the "valid" or "invalid" state), the authorizations
that were completed. Each entry is a URL from which an that were completed. Each entry is a URL from which an
authorization can be fetched with a GET request. authorization can be fetched with a GET request.
finalize (requred, 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.
{ {
"status": "valid", "status": "valid",
"expires": "2015-03-01T14:09:00Z", "expires": "2015-03-01T14:09:00Z",
skipping to change at page 24, line 30 skipping to change at page 25, line 30
], ],
"finalize": "https://example.com/acme/acct/1/order/1/finalize", "finalize": "https://example.com/acme/acct/1/order/1/finalize",
"certificate": "https://example.com/acme/cert/1234" "certificate": "https://example.com/acme/cert/1234"
} }
Any identifier of type "dns" in a new-order request MAY have a Any identifier of type "dns" in a new-order request MAY have a
wildcard domain name as its value. A wildcard domain name consists wildcard domain name as its value. A wildcard domain name consists
of a single asterisk character followed by a single full stop of a single asterisk character followed by a single full stop
character ("_.") followed by a domain name as defined for use in the character ("*.") followed by a domain name as defined for use in the
Subject Alternate Name Extension by RFC 5280 . An authorization Subject Alternate Name Extension by RFC 5280 [RFC5280]. An
returned by the server for a wildcard domain name identifier MUST NOT authorization returned by the server for a wildcard domain name
include the asterisk and full stop ("_[RFC5280].") prefix in the identifier MUST NOT include the asterisk and full stop ("*.") prefix
authorization identifier value. in the authorization identifier value. The returned authorization
MUST include the optional "wildcard" field, with a value of true.
The elements of the "authorizations" and "identifiers" array are The elements of the "authorizations" and "identifiers" array are
immutable once set. The server MUST NOT change the contents either immutable once set. The server MUST NOT change the contents of
array after they are created. If a client observes a change in the either array after they are created. If a client observes a change
contents of either array, then it SHOULD consider the order invalid. in the contents of either array, then it SHOULD consider the order
invalid.
The "authorizations" array in the challenge SHOULD reflect all The "authorizations" array of the order SHOULD reflect all
authorizations that the CA takes into account in deciding to issue, authorizations that the CA takes into account in deciding to issue,
even if some authorizations were fulfilled in earlier orders or in even if some authorizations were fulfilled in earlier orders or in
pre-authorization transactions. For example, if a CA allows multiple pre-authorization transactions. For example, if a CA allows multiple
orders to be fulfilled based on a single authorization transaction, orders to be fulfilled based on a single authorization transaction,
then it SHOULD reflect that authorization in all of the orders. then it SHOULD reflect that authorization in all of the orders.
7.1.4. Authorization Objects 7.1.4. Authorization Objects
An ACME authorization object represents a server's authorization for An ACME authorization object represents a server's authorization for
an account to represent an identifier. In addition to the an account to represent an identifier. In addition to the
skipping to change at page 25, line 18 skipping to change at page 26, line 24
The structure of an ACME authorization resource is as follows: The structure of an ACME authorization resource is as follows:
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", "processing", "valid", "invalid" Possible values are: "pending", "valid", "invalid", "deactivated",
and "revoked". 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
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. For final
authorizations, it contains the challenges that were successfully authorizations, it contains the challenges that were successfully
completed. completed.
wildcard (optional, boolean): For authorizations created as a result
of a newOrder request containing a DNS identifier with a value
that contained a wildcard prefix this field MUST be present, and
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
with the ASCII Compatible Encoding prefix "xn-" as defined in with the ASCII Compatible Encoding prefix "xn--" as defined in
[RFC5890] are properly encoded. Wildcard domain names (with "*" as [RFC5890] are properly encoded. Wildcard domain names (with "*" as
the first label) MUST NOT be included in authorization objects. the first label) MUST NOT be included in authorization objects. If
an authorization object conveys authorization for the base domain of
a newOrder DNS type identifier with a wildcard prefix then the
optional authorizations "wildcard" field MUST be present with a value
of true.
Section 8 describes a set of challenges for domain name validation. Section 8 describes a set of challenges for domain name validation.
{ {
"status": "valid", "status": "valid",
"expires": "2015-03-01T14:09:00Z", "expires": "2015-03-01T14:09:00Z",
"identifier": { "identifier": {
"type": "dns", "type": "dns",
"value": "example.org" "value": "example.org"
}, },
"challenges": [ "challenges": [
{ {
"url": "https://example.com/acme/authz/1234/0", "url": "https://example.com/acme/authz/1234/0",
"type": "http-01", "type": "http-01",
"status": "valid", "status": "valid",
"token": "DGyRejmCefe7v4NfDGDKfA" "token": "DGyRejmCefe7v4NfDGDKfA",
"validated": "2014-12-01T12:05:00Z", "validated": "2014-12-01T12:05:00Z"
"keyAuthorization": "SXQe-2XODaDxNR...vb29HhjjLPSggwiE"
} }
] ],
"wildcard": false
} }
7.1.5. Challenge Objects
An ACME challenge object represents a server's offer to validate a
client's possession of an identifier in a specific way. Unlike the
other objects listed above, there is not a single standard structure
for a challenge object. The contents of a challenge object depend on
the validation method being used. The general structure of challenge
objects and an initial set of validation methods are described in
Section 8.
7.1.6. Status Changes
Each ACME object type goes through a simple state machine over its
lifetime. The "status" field of the object indicates which state the
object is currently in.
Challenge objects are created in the "pending" state. They
transition to the "processing" state when the client responds to the
challenge (see Section 7.5.1) and the server begins attempting to
validate that the client has completed the challenge. Note that
within the "processing" state, the server may attempt to validate the
challenge multiple times (see Section 8.2). Likewise, client
requests for retries do not cause a state change. If validation is
successful, the challenge moves to the "valid" state; if there is an
error, the challenge moves to the "invalid" state.
pending
|
| Receive
| response
V
processing <-+
| | | Server retry or
| | | client retry request
| +----+
|
|
Successful | Failed
validation | validation
+---------+---------+
| |
V V
valid invalid
Authorization objects are created in the "pending" state. If one of
the challenges listed in the authorization transitions to the "valid"
state, then the authorization also changes to the "valid" state. If
there is an error while the authorization is still pending, then the
authorization transitions to the "invalid" state. Once the
authorization is in the valid state, it can expire ("expired"), be
deactivated by the client ("deactivated", see Section 7.5.2), or
revoked by the server ("revoked").
pending --------------------+
| |
| |
Error | Challenge valid |
+---------+---------+ |
| | |
V V |
invalid valid |
| |
| |
| |
+--------------+--------------+
| | |
| | |
Server | Client | Time after |
revoke | deactivate | "expires" |
V V V
revoked deactivated expired
Order objects are created in the "pending" state. Once all of the
authorizations listed in the order object are in the "valid" state,
the order transitions to the "ready" state. The order moves to the
"processing" state after the client submits a request to the order's
"finalize" URL and the CA begins the issuance process for the
certificate. Once the certificate is issued, the order enters the
"valid" state. If an error occurs at any of these stages, the order
moves to the "invalid" state. The order also moves to the "invalid"
state if it expires, or one of its authorizations enters a final
state other than "valid" ("expired", "revoked", "deactivated").
pending --------------+
| |
| All authz |
| "valid" |
V |
ready ---------------+
| |
| Receive |
| finalize |
| request |
V |
processing ------------+
| |
| Certificate | Error or
| issued | Authorization failure
V V
valid invalid
Account objects are created in the "valid" state, since no further
action is required to create an account after a successful newAccount
request. If the account is deactivated by the client or revoked by
the server, it moves to the corresponding state.
valid
|
|
+-----------+-----------+
Client | Server |
deactiv.| revoke |
V V
deactivated revoked
Note that some of these states may not ever appear in a "status"
field, depending on server behavior. For example, a server that
issues synchronously will never show an order in the "processing"
state. A server that deletes expired authorizations immediately will
never show an authorization in the "expired" state.
7.2. Getting a Nonce 7.2. Getting a Nonce
Before sending a POST request to the server, an ACME client needs to Before sending a POST request to the server, an ACME client needs to
have a fresh anti-replay nonce to put in the "nonce" header of the have a fresh anti-replay nonce to put in the "nonce" header of the
JWS. In most cases, the client will have gotten a nonce from a JWS. In most cases, the client will have gotten a nonce from a
previous request. However, the client might sometimes need to get a previous request. However, the client might sometimes need to get a
new nonce, e.g., on its first request to the server or if an existing new nonce, e.g., on its first request to the server or if an existing
nonce is no longer valid. nonce is no longer valid.
To get a fresh nonce, the client sends a HEAD request to the new- To get a fresh nonce, the client sends a HEAD request to the new-
nonce resource on the server. The server's response MUST include a nonce resource on the server. The server's response MUST include a
Replay-Nonce header field containing a fresh nonce, and SHOULD have Replay-Nonce header field containing a fresh nonce, and SHOULD have
status code 204 (No Content). The server SHOULD also respond to GET status code 200 (OK). The server SHOULD also respond to GET requests
requests for this resource, returning an empty body (while still for this resource, returning an empty body (while still providing a
providing a Replay-Nonce header) with a 204 (No Content) status. Replay-Nonce header) with a 204 (No Content) status.
HEAD /acme/new-nonce HTTP/1.1 HEAD /acme/new-nonce HTTP/1.1
Host: example.com Host: example.com
HTTP/1.1 204 No Content 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 Creation
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 containing the "contact" field and optionally a stub account object optionally containing the "contact" and
the "termsOfServiceAgreed" field. "termsOfServiceAgreed" 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 28, line 29 skipping to change at page 32, line 26
it MUST return an error of type "unsupportedContact", with a it MUST return an error of type "unsupportedContact", with a
description describing the error and what types of contact URLs the description describing the error and what types of contact URLs the
server considers acceptable. If the server rejects a contact URL for server considers acceptable. If the server rejects a contact URL for
using a supported scheme but an invalid value then the server MUST using a supported scheme but an invalid value then the server MUST
return an error of type "invalidContact". return an error of type "invalidContact".
If the server wishes to present the client with terms under which the If the server wishes to present the client with terms under which the
ACME service is to be used, it MUST indicate the URL where such terms ACME service is to be used, it MUST indicate the URL where such terms
can be accessed in the "termsOfService" subfield of the "meta" field can be accessed in the "termsOfService" subfield of the "meta" field
in the directory object, and the server MUST reject new-account in the directory object, and the server MUST reject new-account
requests that do not have the "termsOfServiceAgreed" set to "true". requests that do not have the "termsOfServiceAgreed" field set to
Clients SHOULD NOT automatically agree to terms by default. Rather, "true". Clients SHOULD NOT automatically agree to terms by default.
they SHOULD require some user interaction for agreement to terms. Rather, they SHOULD require some user interaction for 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. in a Location header field. The account URL is used as the "kid"
value in the JWS authenticating subsequent requests by this account
(See Section 6.2).
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/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",
skipping to change at page 29, line 26 skipping to change at page 33, line 41
a JWS whose payload has an "onlyReturnExisting" field set to "true" a JWS whose payload has an "onlyReturnExisting" field set to "true"
({"onlyReturnExisting": true}). If a client sends such a request and ({"onlyReturnExisting": true}). If a client sends such a request and
an account does not exist, then the server MUST return an error an account does not exist, then the server MUST return an error
response with status code 400 (Bad Request) and type response with status code 400 (Bad Request) and type
"urn:ietf:params:acme:error:accountDoesNotExist". "urn:ietf:params:acme:error:accountDoesNotExist".
7.3.2. Account Update 7.3.2. Account Update
If the client wishes to update this information in the future, it If the client wishes to update this information in the future, it
sends a POST request with updated information to the account URL. sends a POST request with updated information to the account URL.
The server MUST ignore any updates to "order" fields or any other The server MUST ignore any updates to the "orders" field or any other
fields it does not recognize. If the server accepts the update, it fields it does not recognize. If the server accepts the update, it
MUST return a response with a 200 (OK) status code and the resulting MUST return a response with a 200 (OK) status code and the resulting
account object. account object.
For example, to update the contact information in the above account, For example, to update the contact information in the above account,
the client could send the following request: the client could send the following request:
POST /acme/acct/1 HTTP/1.1 POST /acme/acct/1 HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/jose+json Content-Type: application/jose+json
skipping to change at page 30, line 7 skipping to change at page 34, line 27
"contact": [ "contact": [
"mailto:certificates@example.com", "mailto:certificates@example.com",
"mailto:admin@example.com" "mailto:admin@example.com"
] ]
}), }),
"signature": "hDXzvcj8T6fbFbmn...rDzXzzvzpRy64N0o" "signature": "hDXzvcj8T6fbFbmn...rDzXzzvzpRy64N0o"
} }
7.3.3. Account Information 7.3.3. Account Information
Servers SHOULD NOT respond to GET requests for account resources as Servers MUST NOT respond to GET requests for account resources as
these requests are not authenticated. If a client wishes to query these requests are not authenticated. If a client wishes to query
the server for information about its account (e.g., to examine the the server for information about its account (e.g., to examine the
"contact" or "certificates" fields), then it SHOULD do so by sending "contact" or "orders" fields), then it SHOULD do so by sending a POST
a POST request with an empty update. That is, it should send a JWS request with an empty update. That is, it should send a JWS whose
whose payload is an empty object ({}). payload is an empty object ({}).
7.3.4. Changes of Terms of Service 7.3.4. Changes of Terms of Service
As described above, a client can indicate its agreement with the CA's As described above, a client can indicate its agreement with the CA's
terms of service by setting the "termsOfServiceAgreed" field in its terms of service by setting the "termsOfServiceAgreed" field in its
account object to "true". account object to "true".
If the server has changed its terms of service since a client If the server has changed its terms of service since a client
initially agreed, and the server is unwilling to process a request initially agreed, and the server is unwilling to process a request
without explicit agreement to the new terms, then it MUST return an without explicit agreement to the new terms, then it MUST return an
skipping to change at page 32, line 37 skipping to change at page 36, line 37
"signature": /* MAC using MAC key from CA */ "signature": /* MAC using MAC key from CA */
} }
}), }),
"signature": "5TWiqIYQfIDfALQv...x9C2mg8JGPxl5bI4" "signature": "5TWiqIYQfIDfALQv...x9C2mg8JGPxl5bI4"
} }
If a CA requires that new-account requests contain an If a CA requires that new-account requests contain an
"externalAccountBinding" field, then it MUST provide the value "true" "externalAccountBinding" field, then it MUST provide the value "true"
in the "externalAccountRequired" subfield of the "meta" field in the in the "externalAccountRequired" subfield of the "meta" field in the
directory object. If the CA receives a new-account request without directory object. If the CA receives a new-account request without
an "externalAccountBinding" field, then it should reply with an error an "externalAccountBinding" field, then it SHOULD reply with an error
of type "externalAccountRequired". of type "externalAccountRequired".
When a CA receives a new-account request containing an When a CA receives a new-account request containing an
"externalAccountBinding" field, it decides whether or not to verify "externalAccountBinding" field, it decides whether or not to verify
the binding. If the CA does not verify the binding, then it MUST NOT the binding. If the CA does not verify the binding, then it MUST NOT
reflect the "externalAccountBinding" field in the resulting account reflect the "externalAccountBinding" field in the resulting account
object (if any). To verify the account binding, the CA MUST take the object (if any). To verify the account binding, the CA MUST take the
following steps: following steps:
1. Verify that the value of the field is a well-formed JWS 1. Verify that the value of the field is a well-formed JWS
2. Verify that the JWS protected meets the above criteria 2. Verify that the JWS protected field meets the above criteria
3. Retrieve the MAC key corresponding to the key identifier in the 3. Retrieve the MAC key corresponding to the key identifier in the
"kid" field "kid" field
4. Verify that the MAC on the JWS verifies using that MAC key 4. Verify that the MAC on the JWS verifies using that MAC key
5. Verify that the payload of the JWS represents the same key as was 5. Verify that the payload of the JWS represents the same key as was
used to verify the outer JWS (i.e., the "jwk" field of the outer used to verify the outer JWS (i.e., the "jwk" field of the outer
JWS) JWS)
skipping to change at page 33, line 28 skipping to change at page 37, line 28
7.3.6. Account Key Roll-over 7.3.6. Account Key Roll-over
A client may wish to change the public key that is associated with an A client may wish to change the public key that is associated with an
account in order to recover from a key compromise or proactively account in order to recover from a key compromise or proactively
mitigate the impact of an unnoticed key compromise. mitigate the impact of an unnoticed key compromise.
To change the key associated with an account, the client first To change the key associated with an account, the client first
constructs a key-change object describing the change that it would constructs a key-change object describing the change that it would
like the server to make: like the server to make:
account (required, string): The URL for account being modified. The account (required, string): The URL for the account being modified.
content of this field MUST be the exact string provided in the The content of this field MUST be the exact string provided in the
Location header field in response to the new-account request that Location header field in response to the new-account request that
created the account. created the account.
newKey (required, JWK): The JWK representation of the new key newKey (required, JWK): The JWK representation of the new key
The client then encapsulates the key-change object in an "inner" JWS, The client then encapsulates the key-change object in an "inner" JWS,
signed with the requested new account key (i.e., the key matching the signed with the requested new account key (i.e., the key matching the
"newKey" value). This JWS then becomes the payload for the "outer" "newKey" value). This JWS then becomes the payload for the "outer"
JWS that is the body of the ACME request. JWS that is the body of the ACME request.
skipping to change at page 35, line 15 skipping to change at page 39, line 15
4. Check that the inner JWS verifies using the key in its "jwk" 4. Check that the inner JWS verifies using the key in its "jwk"
field. field.
5. Check that the payload of the inner JWS is a well-formed key- 5. Check that the payload of the inner JWS is a well-formed key-
change object (as described above). change object (as described above).
6. Check that the "url" parameters of the inner and outer JWSs are 6. Check that the "url" parameters of the inner and outer JWSs are
the same. the same.
7. Check that the "account" field of the key-change object contains 7. Check that the "account" field of the key-change object contains
the URL for the account matching the old key the URL for the account matching the old key.
8. Check that the "newKey" field of the key-change object also 8. Check that the "newKey" field of the key-change object also
verifies the inner JWS. verifies the inner JWS.
9. Check that no account exists whose account key is the same as the 9. Check that no account exists whose account key is the same as the
key in the "newKey" field. key in the "newKey" field.
If all of these checks pass, then the server updates the If all of these checks pass, then the server updates the
corresponding account by replacing the old account key with the new corresponding account by replacing the old account key with the new
public key and returns status code 200 (OK). Otherwise, the server public key and returns status code 200 (OK). Otherwise, the server
skipping to change at page 37, line 6 skipping to change at page 41, line 6
be issued: be issued:
identifiers (required, array of object): An array of identifier identifiers (required, array of object): An array of identifier
objects that the client wishes to submit an order for. objects that the client wishes to submit an order for.
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.
notBefore (optional, string): The requested value of the notBefore notBefore (optional, string): The requested value of the notBefore
field in the certificate, in the date format defined in [RFC3339] field in the certificate, in the date format defined in [RFC3339].
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].
POST /acme/new-order HTTP/1.1 POST /acme/new-order 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",
"kid": "https://example.com/acme/acct/1", "kid": "https://example.com/acme/acct/1",
"nonce": "5XJ1L3lEkMG7tR6pA00clA", "nonce": "5XJ1L3lEkMG7tR6pA00clA",
skipping to change at page 39, line 17 skipping to change at page 43, line 17
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": "MSF2j2nawWHPxxkE3ZJtKQ", "nonce": "MSF2j2nawWHPxxkE3ZJtKQ",
"url": "https://example.com/acme/order/asdf/finalize" "url": "https://example.com/acme/order/asdf/finalize"
}), }),
"payload": base64url({ "payload": base64url({
"csr": "5jNudRx6Ye4HzKEqT5...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, 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.
skipping to change at page 39, line 46 skipping to change at page 43, line 46
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.
o "pending": The server does not believe that the client has o "pending": The server does not believe that the client has
fulfilled the requirements. Check the "authorizations" array for fulfilled the requirements. Check the "authorizations" array for
entries that are still pending. entries that are still pending.
o "processing": The server agrees that the requirements have been o "ready": The server agrees that the requirements have been
fulfilled, and is in the process of generating the certificate. fulfilled, and is awaiting finalization. Submit a finalization
Retry after the time given in the "Retry-After" header field of request.
the response, if any.
o "processing": The certificate is being issued. Send a GET request
after the time given in the "Retry-After" header field of the
response, if any.
o "valid": The server has issued the certificate and provisioned its o "valid": The server has issued the certificate and provisioned its
URL to the "certificate" field of the order. URL to the "certificate" field of the order. Download the
certificate.
HTTP/1.1 200 Ok HTTP/1.1 200 OK
Replay-Nonce: CGf81JWBsq8QyIgPCi9Q9X Replay-Nonce: CGf81JWBsq8QyIgPCi9Q9X
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",
skipping to change at page 41, line 9 skipping to change at page 45, line 13
submitted by the client. submitted by the client.
If a CA wishes to allow pre-authorization within ACME, it can offer a If a CA wishes to allow pre-authorization within ACME, it can offer a
"new authorization" resource in its directory by adding the field "new authorization" resource in its directory by adding the field
"newAuthz" with a URL for the new authorization resource. "newAuthz" with a URL for the new authorization resource.
To request authorization for an identifier, the client sends a POST To request authorization for an identifier, the client sends a POST
request to the new-authorization resource specifying the identifier request to the new-authorization resource specifying the identifier
for which authorization is being requested. for which authorization is being requested.
identifier (required, object): The identifier that the account is identifier (required, object): The identifier to appear in the
authorized to represent: resulting authorization object (see Section 7.1.4)
type (required, string): The type of identifier.
value (required, string): The identifier itself.
POST /acme/new-authz HTTP/1.1 POST /acme/new-authz 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",
"kid": "https://example.com/acme/acct/1", "kid": "https://example.com/acme/acct/1",
"nonce": "uQpSjlRb4vQVCjVYAyyUWg", "nonce": "uQpSjlRb4vQVCjVYAyyUWg",
skipping to change at page 41, line 36 skipping to change at page 45, line 36
}), }),
"payload": base64url({ "payload": base64url({
"identifier": { "identifier": {
"type": "dns", "type": "dns",
"value": "example.net" "value": "example.net"
} }
}), }),
"signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps" "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps"
} }
Note that because the identifier in a pre-authorization request is
the exact identifier to be included in the authorization object, pre-
authorization cannot be used to authorize issuance with wildcard DNS
identifiers.
Before processing the authorization request, the server SHOULD Before processing the authorization request, the server SHOULD
determine whether it is willing to issue certificates for the determine whether it is willing to issue certificates for the
identifier. For example, the server should check that the identifier identifier. For example, the server should check that the identifier
is of a supported type. Servers might also check names against a is of a supported type. Servers might also check names against a
blacklist of known high-value identifiers. If the server is blacklist of known high-value identifiers. If the server is
unwilling to issue for the identifier, it SHOULD return a 403 unwilling to issue for the identifier, it SHOULD return a 403
(Forbidden) error, with a problem document describing the reason for (Forbidden) error, with a problem document describing the reason for
the rejection. the rejection.
If the server is willing to proceed, it builds a pending If the server is willing to proceed, it builds a pending
authorization object from the inputs submitted by the client. authorization object from the inputs submitted by the client:
o "identifier" the identifier submitted by the client o "identifier" the identifier submitted by the client
o "status" MUST be "pending" unless the server has out-of-band o "status" MUST be "pending" unless the server has out-of-band
information about the client's authorization status information about the client's authorization status
o "challenges" as selected by the server's policy for this o "challenges" as selected by the server's policy for this
identifier identifier
The server allocates a new URL for this authorization, and returns a The server allocates a new URL for this authorization, and returns a
skipping to change at page 44, line 28 skipping to change at page 48, line 28
"value": "example.org" "value": "example.org"
}, },
"challenges": [ "challenges": [
{ {
"type": "http-01", "type": "http-01",
"url": "https://example.com/acme/authz/1234/0", "url": "https://example.com/acme/authz/1234/0",
"token": "DGyRejmCefe7v4NfDGDKfA" "token": "DGyRejmCefe7v4NfDGDKfA"
}, },
{ {
"type": "tls-sni-02",
"url": "https://example.com/acme/authz/1234/1",
"token": "DGyRejmCefe7v4NfDGDKfA"
},
{
"type": "dns-01", "type": "dns-01",
"url": "https://example.com/acme/authz/1234/2", "url": "https://example.com/acme/authz/1234/2",
"token": "DGyRejmCefe7v4NfDGDKfA" "token": "DGyRejmCefe7v4NfDGDKfA"
} }
] ],
"wildcard": false
} }
7.5.1. Responding to Challenges 7.5.1. Responding to Challenges
To prove control of the identifier and receive authorization, the To prove control of the identifier and receive authorization, the
client needs to respond with information to complete the challenges. client needs to respond with information to complete the challenges.
To do this, the client updates the authorization object received from To do this, the client updates the authorization object received from
the server by filling in any required information in the elements of the server by filling in any required information in the elements of
the "challenges" dictionary. the "challenges" dictionary.
skipping to change at page 45, line 19 skipping to change at page 49, line 16
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/1", "kid": "https://example.com/acme/acct/1",
"nonce": "Q_s3MWoqT05TrdkM2MTDcw", "nonce": "Q_s3MWoqT05TrdkM2MTDcw",
"url": "https://example.com/acme/authz/1234/0" "url": "https://example.com/acme/authz/1234/0"
}), }),
"payload": base64url({ "payload": base64url({}),
"keyAuthorization": "IlirfxKKXA...vb29HhjjLPSggwiE"
}),
"signature": "9cbg5JO1Gf5YLjjz...SpkUfcdPai9uVYYQ" "signature": "9cbg5JO1Gf5YLjjz...SpkUfcdPai9uVYYQ"
} }
The server updates the authorization document by updating its The server updates the authorization document by updating its
representation of the challenge with the response object provided by representation of the challenge with the response object provided by
the client. The server MUST ignore any fields in the response object the client. The server MUST ignore any fields in the response object
that are not specified as response fields for this type of challenge. that are not specified as response fields for this type of challenge.
The server provides a 200 (OK) response with the updated challenge The server provides a 200 (OK) response with the updated challenge
object as its body. object as its body.
skipping to change at page 46, line 18 skipping to change at page 50, line 12
request to the authorization URL, and the server responds with the request to the authorization URL, and the server responds with the
current authorization object. In responding to poll requests while current authorization object. In responding to poll requests while
the validation is still in progress, the server MUST return a 200 the validation is still in progress, the server MUST return a 200
(OK) response and MAY include a Retry-After header field to suggest a (OK) response and MAY include a Retry-After header field to suggest a
polling interval to the client. polling interval to the client.
GET /acme/authz/1234 HTTP/1.1 GET /acme/authz/1234 HTTP/1.1
Host: example.com Host: example.com
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json
{ {
"status": "valid", "status": "valid",
"expires": "2018-09-09T14:09:00Z", "expires": "2018-09-09T14:09:00Z",
"identifier": { "identifier": {
"type": "dns", "type": "dns",
"value": "example.org" "value": "example.org"
}, },
"challenges": [ "challenges": [
{ {
"type": "http-01" "type": "http-01",
"url": "https://example.com/acme/authz/1234/0", "url": "https://example.com/acme/authz/1234/0",
"status": "valid", "status": "valid",
"validated": "2014-12-01T12:05:00Z", "validated": "2014-12-01T12:05:00Z",
"token": "IlirfxKKXAsHtmzK29Pj8A", "token": "IlirfxKKXAsHtmzK29Pj8A"
"keyAuthorization": "IlirfxKKXA...vb29HhjjLPSggwiE"
} }
] ],
"wildcard": false
} }
7.5.2. Deactivating an Authorization 7.5.2. Deactivating an Authorization
If a client wishes to relinquish its authorization to issue If a client wishes to relinquish its authorization to issue
certificates for an identifier, then it may request that the server certificates for an identifier, then it may request that the server
deactivates each authorization associated with it by sending POST deactivates each authorization associated with it by sending POST
requests with the static object {"status": "deactivated"} to each requests with the static object {"status": "deactivated"} to each
authorization URL. authorization URL.
skipping to change at page 47, line 33 skipping to change at page 51, line 33
corresponding to the account that owns the authorization. If the corresponding to the account that owns the authorization. If the
server accepts the deactivation, it should reply with a 200 (OK) server accepts the deactivation, it should reply with a 200 (OK)
status code and the updated contents of the authorization object. status code and the updated contents of the authorization object.
The server MUST NOT treat deactivated authorization objects as The server MUST NOT treat deactivated authorization objects as
sufficient for issuing certificates. sufficient for issuing certificates.
7.6. Certificate Revocation 7.6. Certificate Revocation
To request that a certificate be revoked, the client sends a POST To request that a certificate be revoked, the client sends a POST
request to the ACME server's revoke-cert URL. The body of the POST request to the ACME server's revokeCert URL. The body of the POST is
is a JWS object whose JSON payload contains the certificate to be a JWS object whose JSON payload contains the certificate to be
revoked: revoked:
certificate (required, string): The certificate to be revoked, in certificate (required, string): The certificate to be revoked, in
the base64url-encoded version of the DER format. (Note: Because the base64url-encoded version of the DER format. (Note: Because
this field uses base64url, and does not include headers, it is this field uses base64url, and does not include headers, it is
different from PEM.) different from PEM.)
reason (optional, int): One of the revocation reasonCodes defined in reason (optional, int): One of the revocation reasonCodes defined in
Section 5.3.1 of [RFC5280] to be used when generating OCSP Section 5.3.1 of [RFC5280] to be used when generating OCSP
responses and CRLs. If this field is not set the server SHOULD responses and CRLs. If this field is not set the server SHOULD
use the unspecified (0) reasonCode value when generating OCSP omit the reasonCode CRL entry extension when generating OCSP
responses and CRLs. The server MAY disallow a subset of responses and CRLs. The server MAY disallow a subset of
reasonCodes from being used by the user. If a request contains a reasonCodes from being used by the user. If a request contains a
disallowed reasonCode the server MUST reject it with the error disallowed reasonCode the server MUST reject it with the error
type "urn:ietf:params:acme:error:badRevocationReason". The type "urn:ietf:params:acme:error:badRevocationReason". The
problem document detail SHOULD indicate which reasonCodes are problem document detail SHOULD indicate which reasonCodes are
allowed. allowed.
Revocation requests are different from other ACME requests in that
they can be signed either with an account key pair or the key pair in
the certificate.
Example using an account key pair for the signature:
POST /acme/revoke-cert HTTP/1.1 POST /acme/revoke-cert 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": /* account key */, "kid": "https://example.com/acme/acct/1",
"nonce": "JHb54aT_KTXBWQOzGYkt9A",
"url": "https://example.com/acme/revoke-cert"
}),
"payload": base64url({
"certificate": "MIIEDTCCAvegAwIBAgIRAP8...",
"reason": 4
}),
"signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4"
}
Example using the certificate key pair for the signature:
POST /acme/revoke-cert HTTP/1.1
Host: example.com
Content-Type: application/jose+json
{
"protected": base64url({
"alg": "RS256",
"jwk": /* certificate's public key */,
"nonce": "JHb54aT_KTXBWQOzGYkt9A", "nonce": "JHb54aT_KTXBWQOzGYkt9A",
"url": "https://example.com/acme/revoke-cert" "url": "https://example.com/acme/revoke-cert"
}), }),
"payload": base64url({ "payload": base64url({
"certificate": "MIIEDTCCAvegAwIBAgIRAP8...", "certificate": "MIIEDTCCAvegAwIBAgIRAP8...",
"reason": 1 "reason": 1
}), }),
"signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4"
} }
Revocation requests are different from other ACME requests in that Before revoking a certificate, the server MUST verify that the key
they can be signed either with an account key pair or the key pair in used to sign the request is authorized to revoke the certificate.
the certificate. Before revoking a certificate, the server MUST The server MUST consider at least the following accounts authorized
verify that the key used to sign the request is authorized to revoke for a given certificate:
the certificate. The server MUST consider at least the following
accounts authorized for a given certificate:
o the account that issued the certificate. o the account that issued the certificate.
o an account that holds authorizations for all of the identifiers in o an account that holds authorizations for all of the identifiers in
the certificate. the certificate.
The server MUST also consider a revocation request valid if it is The server MUST also consider a revocation request valid if it is
signed with the private key corresponding to the public key in the signed with the private key corresponding to the public key in the
certificate. certificate.
skipping to change at page 50, line 17 skipping to change at page 54, line 32
of an identifier of an identifier
Challenge objects all contain the following basic fields: Challenge objects all contain the following basic fields:
type (required, string): The type of challenge encoded in the type (required, string): The type of challenge encoded in the
object. object.
url (required, string): The URL to which a response can be posted. url (required, string): The URL to which a response can be posted.
status (required, string): The status of this challenge. Possible status (required, string): The status of this challenge. Possible
values are: "pending", "valid", and "invalid". values are: "pending", "processing", "valid", and "invalid".
validated (optional, string): The time at which the server validated validated (optional, string): The time at which the server validated
this challenge, encoded in the format specified in RFC 3339 this challenge, encoded in the format specified in RFC 3339
[RFC3339]. This field is REQUIRED if the "status" field is [RFC3339]. This field is REQUIRED if the "status" field is
"valid". "valid".
errors (optional, array of object): Errors that occurred while the error (optional, object): Error that occurred while the server was
server was validating the challenge, if any, structured as problem validating the challenge, if any, structured as a problem document
documents [RFC7807]. The server MUST NOT modify the array except [RFC7807]. Multiple errors can be indicated by using subproblems
by appending entries onto the end. The server can limit the size Section 6.6.1.
of this object by limiting the number of times it will try to
validate a challenge.
All additional fields are specified by the challenge type. If the All additional fields are specified by the challenge type. If the
server sets a challenge's "status" to "invalid", it SHOULD also server sets a challenge's "status" to "invalid", it SHOULD also
include the "errors" field to help the client diagnose why the include the "error" field to help the client diagnose why the
challenge failed. challenge failed.
Different challenges allow the server to obtain proof of different Different challenges allow the server to obtain proof of different
aspects of control over an identifier. In some challenges, like aspects of control over an identifier. In some challenges, like HTTP
HTTP, TLS SNI, and DNS, the client directly proves its ability to do and DNS, the client directly proves its ability to do certain things
certain things related to the identifier. The choice of which related to the identifier. The choice of which challenges to offer
challenges to offer to a client under which circumstances is a matter to a client under which circumstances is a matter of server policy.
of server policy.
The identifier validation challenges described in this section all The identifier validation challenges described in this section all
relate to validation of domain names. If ACME is extended in the relate to validation of domain names. If ACME is extended in the
future to support other types of identifiers, there will need to be future to support other types of identifiers, there will need to be
new challenge types, and they will need to specify which types of new challenge types, and they will need to specify which types of
identifier they apply to. identifier they apply to.
8.1. Key Authorizations 8.1. Key Authorizations
Several of the challenges in this document make use of a key All challenges defined in this document make use of a key
authorization string. A key authorization is a string that expresses authorization string. A key authorization is a string that expresses
a domain holder's authorization for a specified key to satisfy a a domain holder's authorization for a specified key to satisfy a
specified challenge, by concatenating the token for the challenge specified challenge, by concatenating the token for the challenge
with a key fingerprint, separated by a "." character: with a key fingerprint, separated by a "." character:
key-authz = token || '.' || base64url(JWK_Thumbprint(accountKey)) keyAuthorization = token || '.' || base64url(JWK_Thumbprint(accountKey))
The "JWK_Thumbprint" step indicates the computation specified in The "JWK_Thumbprint" step indicates the computation specified in
[RFC7638], using the SHA-256 digest [FIPS180-4]. As noted in JWA [RFC7638], using the SHA-256 digest [FIPS180-4]. As noted in
[RFC7518] any prepended zero octets in the fields of a JWK object [RFC7518] any prepended zero octets in the fields of a JWK object
MUST be stripped before doing the computation. MUST be stripped before doing the computation.
As specified in the individual challenges below, the token for a As specified in the individual challenges below, the token for a
challenge is a string comprised entirely of characters in the URL- challenge is a string comprised entirely of characters in the URL-
safe base64 alphabet. The "||" operator indicates concatenation of safe base64 alphabet. The "||" operator indicates concatenation of
strings. strings.
8.2. Retrying Challenges 8.2. Retrying Challenges
skipping to change at page 51, line 44 skipping to change at page 56, line 4
Clients SHOULD NOT respond to challenges until they believe that the Clients SHOULD NOT respond to challenges until they believe that the
server's queries will succeed. If a server's initial validation server's queries will succeed. If a server's initial validation
query fails, the server SHOULD retry the query after some time, in query fails, the server SHOULD retry the query after some time, in
order to account for delay in setting up responses such as DNS order to account for delay in setting up responses such as DNS
records or HTTP resources. The precise retry schedule is up to the records or HTTP resources. The precise retry schedule is up to the
server, but server operators should keep in mind the operational server, but server operators should keep in mind the operational
scenarios that the schedule is trying to accommodate. Given that scenarios that the schedule is trying to accommodate. Given that
retries are intended to address things like propagation delays in retries are intended to address things like propagation delays in
HTTP or DNS provisioning, there should not usually be any reason to HTTP or DNS provisioning, there should not usually be any reason to
retry more often than every 5 or 10 seconds. While the server is retry more often than every 5 or 10 seconds. While the server is
still trying, the status of the challenge remains "pending"; it is still trying, the status of the challenge remains "processing"; it is
only marked "invalid" once the server has given up. only marked "invalid" once the server has given up.
The server MUST provide information about its retry state to the The server MUST provide information about its retry state to the
client via the "errors" field in the challenge and the Retry-After client via the "error" field in the challenge and the Retry-After
HTTP header field in response to requests to the challenge resource. HTTP header field in response to requests to the challenge resource.
The server MUST add an entry to the "errors" field in the challenge The server MUST add an entry to the "error" field in the challenge
after each failed validation query. The server SHOULD set the Retry- after each failed validation query. The server SHOULD set the Retry-
After header field to a time after the server's next validation After header field to a time after the server's next validation
query, since the status of the challenge will not change until that query, since the status of the challenge will not change until that
time. time.
Clients can explicitly request a retry by re-sending their response Clients can explicitly request a retry by re-sending their response
to a challenge in a new POST request (with a new nonce, etc.). This to a challenge in a new POST request (with a new nonce, etc.). This
allows clients to request a retry when the state has changed (e.g., allows clients to request a retry when the state has changed (e.g.,
after firewall rules have been updated). Servers SHOULD retry a after firewall rules have been updated). Servers SHOULD retry a
request immediately on receiving such a POST request. In order to request immediately on receiving such a POST request. In order to
skipping to change at page 52, line 41 skipping to change at page 57, line 9
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,
and MUST NOT include base64 padding characters ("="). and MUST NOT include base64 padding characters ("=").
GET /acme/authz/1234/0 HTTP/1.1 GET /acme/authz/1234/0 HTTP/1.1
Host: example.com Host: example.com
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json
{ {
"type": "http-01", "type": "http-01",
"url": "https://example.com/acme/authz/0", "url": "https://example.com/acme/authz/0",
"status": "pending", "status": "pending",
"token": "LoqXcYV8q5ONbJQxbmR7SCTNo3tiAXDfowyjxAjEuX0" "token": "LoqXcYV8q5ONbJQxbmR7SCTNo3tiAXDfowyjxAjEuX0"
} }
A client responds to this challenge by constructing a key A client fulfills this challenge by constructing a key authorization
authorization from the "token" value provided in the challenge and from the "token" value provided in the challenge and the client's
the client's account key. The client then provisions the key account key. The client then provisions the key authorization as a
authorization as a resource on the HTTP server for the domain in resource on the HTTP server for the domain in question.
question.
The path at which the resource is provisioned is comprised of the The path at which the resource is provisioned is comprised of the
fixed prefix "/.well-known/acme-challenge/", followed by the "token" fixed prefix "/.well-known/acme-challenge/", followed by the "token"
value in the challenge. The value of the resource MUST be the ASCII value in the challenge. The value of the resource MUST be the ASCII
representation of the key authorization. representation of the key authorization.
GET /.well-known/acme-challenge/LoqXcYV8q5ONbJQxbmR7SCTNo3tiAXDfowyjxAjEuX0 GET /.well-known/acme-challenge/LoqXcYV8q5ONbJQxbmR7SCTNo3tiAXDfowyjxAjEuX0
Host: example.org Host: example.org
HTTP/1.1 200 OK HTTP/1.1 200 OK
LoqXcYV8q5ONbJQxbmR7SCTNo3tiAXDfowyjxAjEuX0.9jg46WB3rR_AHD-EBXdN7cBkH1WOu0tA3M9fm21mqTI Content-Type: application/octet-stream
The client's response to the validation request indicates its LoqXcYV8q5ONbJQxbmR7SCTNo3tiAXDfowyjxAjEuX0.9jg46WB3rR_AHD-EBXdN7cBkH1WOu0tA3M9fm21mqTI
agreement to this challenge by sending the server the key
authorization covering the challenge's token and the client's account
key.
keyAuthorization (required, string): The key authorization for this A client responds with an empty object ({}) to acknowledge that the
challenge. This value MUST match the token from the challenge and challenge can be validated by the server.
the client's account key.
POST /acme/authz/1234/0 POST /acme/authz/1234/0
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/1", "kid": "https://example.com/acme/acct/1",
"nonce": "JHb54aT_KTXBWQOzGYkt9A", "nonce": "JHb54aT_KTXBWQOzGYkt9A",
"url": "https://example.com/acme/authz/1234/0" "url": "https://example.com/acme/authz/1234/0"
}), }),
"payload": base64url({ "payload": base64url({}),
"keyAuthorization": "evaGxfADs...62jcerQ"
}),
"signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4"
} }
On receiving a response, the server constructs and stores the key
On receiving a response, the server MUST verify that the key authorization from the challenge "token" value and the current client
authorization in the response matches the "token" value in the account key.
challenge and the client's account key. If they do not match, then
the server MUST return an HTTP error in response to the POST request
in which the client sent the challenge.
Given a challenge/response pair, the server verifies the client's Given a challenge/response pair, the server verifies the client's
control of the domain by verifying that the resource was provisioned control of the domain by verifying that the resource was provisioned
as expected. as expected.
1. Construct a URL by populating the URL template [RFC6570] 1. Construct a URL by populating the URL template [RFC6570]
"http://{domain}/.well-known/acme-challenge/{token}", where: "http://{domain}/.well-known/acme-challenge/{token}", where:
* the domain field is set to the domain name being verified; and * the domain field is set to the domain name being verified; and
skipping to change at page 54, line 26 skipping to change at page 58, line 29
2. Verify that the resulting URL is well-formed. 2. Verify that the resulting URL is well-formed.
3. Dereference the URL using an HTTP GET request. This request MUST 3. Dereference the URL using an HTTP GET request. This request MUST
be sent to TCP port 80 on the HTTP server. be sent to TCP port 80 on the HTTP server.
4. Verify that the body of the response is well-formed key 4. Verify that the body of the response is well-formed key
authorization. The server SHOULD ignore whitespace characters at authorization. The server SHOULD ignore whitespace characters at
the end of the body. the end of the body.
5. Verify that key authorization provided by the HTTP server matches 5. Verify that key authorization provided by the HTTP server matches
the key authorization provided by the client in its response to the key authorization stored by the server.
the challenge.
The server SHOULD follow redirects when dereferencing the URL. The server SHOULD follow redirects when dereferencing the URL.
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.
8.4. TLS with Server Name Indication (TLS SNI) Challenge 8.4. DNS Challenge
The TLS with Server Name Indication (TLS SNI) validation method
proves control over a domain name by requiring the client to
configure a TLS server referenced by the DNS A and AAAA resource
records for the domain name to respond to specific connection
attempts utilizing the Server Name Indication extension [RFC6066].
The server verifies the client's challenge by accessing the TLS
server and verifying a particular certificate is presented.
type (required, string): The string "tls-sni-02"
token (required, string): A random value that uniquely identifies
the challenge. This value MUST have at least 128 bits of entropy.
It MUST NOT contain any characters outside the base64url alphabet,
including padding characters ("=").
GET /acme/authz/1234/1 HTTP/1.1
Host: example.com
HTTP/1.1 200 OK
{
"type": "tls-sni-02",
"url": "https://example.com/acme/authz/1234/1",
"status": "pending",
"token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA"
}
A client responds to this challenge by constructing a self-signed
certificate which the client MUST provision at the domain name
concerned in order to pass the challenge.
The certificate may be constructed arbitrarily, except that each
certificate MUST have exactly two subjectAlternativeNames, SAN A and
SAN B. Both MUST be dNSNames [RFC5280].
SAN A MUST be constructed as follows: compute the SHA-256 digest
[FIPS180-4] of the challenge token and encode it in lowercase
hexadecimal form. The dNSName is "x.y.token.acme.invalid", where x
is the first half of the hexadecimal representation and y is the
second half.
SAN B MUST be constructed as follows: compute the SHA-256 digest of
the key authorization and encode it in lowercase hexadecimal form.
The dNSName is "x.y.ka.acme.invalid" where x is the first half of the
hexadecimal representation and y is the second half.
The client MUST ensure that the certificate is served to TLS
connections specifying a Server Name Indication (SNI) value of SAN A.
The response to the TLS-SNI challenge simply acknowledges that the
client is ready to fulfill this challenge.
keyAuthorization (required, string): The key authorization for this
challenge. This value MUST match the token from the challenge and
the client's account key.
POST /acme/authz/1234/1
Host: example.com
Content-Type: application/jose+json
{
"protected": base64url({
"alg": "ES256",
"kid": "https://example.com/acme/acct/1",
"nonce": "JHb54aT_KTXBWQOzGYkt9A",
"url": "https://example.com/acme/authz/1234/1"
}),
"payload": base64url({
"keyAuthorization": "evaGxfADs...62jcerQ"
}),
"signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4"
}
On receiving a response, the server MUST verify that the key
authorization in the response matches the "token" value in the
challenge and the client's account key. If they do not match, then
the server MUST return an HTTP error in response to the POST request
in which the client sent the challenge.
Given a challenge/response pair, the ACME server verifies the
client's control of the domain by verifying that the TLS server was
configured appropriately, using these steps:
1. Compute SAN A and SAN B in the same way as the client.
2. Open a TLS connection to the domain name being validated,
presenting SAN A in the SNI field. This connection MUST be sent
to TCP port 443 on the TLS server. In the ClientHello initiating
the TLS handshake, the server MUST include a server_name
extension (i.e., SNI) containing SAN A. The server SHOULD ensure
that it does not reveal SAN B in any way when making the TLS
connection, such that the presentation of SAN B in the returned
certificate proves association with the client.
3. Verify that the certificate contains a subjectAltName extension
containing dNSName entries of SAN A and SAN B and no other
entries. The comparison MUST be insensitive to case and ordering
of names.
If all of the above verifications succeed, then the validation is
successful. Otherwise, the validation fails.
8.5. 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 ("="). including padding characters ("=").
GET /acme/authz/1234/2 HTTP/1.1 GET /acme/authz/1234/2 HTTP/1.1
Host: example.com Host: example.com
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json
{ {
"type": "dns-01", "type": "dns-01",
"url": "https://example.com/acme/authz/1234/2", "url": "https://example.com/acme/authz/1234/2",
"status": "pending", "status": "pending",
"token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA" "token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA"
} }
A client responds to this challenge by constructing a key A client fulfills this challenge by constructing a key authorization
authorization from the "token" value provided in the challenge and from the "token" value provided in the challenge and the client's
the client's account key. The client then computes the SHA-256 account key. The client then computes the SHA-256 digest [FIPS180-4]
digest [FIPS180-4] of the key authorization. of the key authorization.
The record provisioned to the DNS contains the base64url encoding of The record provisioned to the DNS contains the base64url encoding of
this digest. The client constructs the validation domain name by this digest. The client constructs the validation domain name by
prepending the label "_acme-challenge" to the domain name being prepending the label "_acme-challenge" to the domain name being
validated, then provisions a TXT record with the digest value under validated, then provisions a TXT record with the digest value under
that name. For example, if the domain name being validated is that name. For example, if the domain name being validated is
"example.org", then the client would provision the following DNS "example.org", then the client would provision the following DNS
record: record:
_acme-challenge.example.org. 300 IN TXT "gfj9Xq...Rg85nM" _acme-challenge.example.org. 300 IN TXT "gfj9Xq...Rg85nM"
The response to the DNS challenge provides the computed key A client responds with an empty object ({}) to acknowledge that the
authorization to acknowledge that the client is ready to fulfill this challenge can be validated by the server.
challenge.
keyAuthorization (required, string): The key authorization for this
challenge. This value MUST match the token from the challenge and
the client's account key.
POST /acme/authz/1234/2 POST /acme/authz/1234/2
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/1", "kid": "https://example.com/acme/acct/1",
"nonce": "JHb54aT_KTXBWQOzGYkt9A", "nonce": "JHb54aT_KTXBWQOzGYkt9A",
"url": "https://example.com/acme/authz/1234/2" "url": "https://example.com/acme/authz/1234/2"
}), }),
"payload": base64url({ "payload": base64url({}),
"keyAuthorization": "evaGxfADs...62jcerQ"
}),
"signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4" "signature": "Q1bURgJoEslbD1c5...3pYdSMLio57mQNN4"
} }
On receiving a response, the server constructs and stores the key
On receiving a response, the server MUST verify that the key authorization from the challenge "token" value and the current client
authorization in the response matches the "token" value in the account key.
challenge and the client's account key. If they do not match, then
the server MUST return an HTTP error in response to the POST request
in which the client sent the challenge.
To validate a DNS challenge, the server performs the following steps: To validate a DNS challenge, the server performs the following steps:
1. Compute the SHA-256 digest [FIPS180-4] of the key authorization 1. Compute the SHA-256 digest [FIPS180-4] of the stored key
authorization
2. Query for TXT records for the validation domain name 2. Query for TXT records for the validation domain name
3. Verify that the contents of one of the TXT records match the 3. Verify that the contents of one of the TXT records match the
digest value digest value
If all of the above verifications succeed, then the validation is If all of the above verifications succeed, then the validation is
successful. If no DNS record is found, or DNS record and response successful. If no DNS record is found, or DNS record and response
payload do not pass these checks, then the validation fails. payload do not pass these checks, then the validation fails.
skipping to change at page 64, line 15 skipping to change at page 66, line 15
+------------+-----------------+--------------+-----------+ +------------+-----------------+--------------+-----------+
| Field Name | Field Type | Configurable | Reference | | Field Name | Field Type | Configurable | Reference |
+------------+-----------------+--------------+-----------+ +------------+-----------------+--------------+-----------+
| identifier | object | true | RFC XXXX | | identifier | object | true | RFC XXXX |
| | | | | | | | | |
| status | string | false | RFC XXXX | | status | string | false | RFC XXXX |
| | | | | | | | | |
| expires | string | false | RFC XXXX | | expires | string | false | RFC XXXX |
| | | | | | | | | |
| challenges | array of object | false | RFC XXXX | | challenges | array of object | false | RFC XXXX |
| | | | |
| wildcard | boolean | false | 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.4. Error Types 9.7.4. Error Types
This registry lists values that are used within URN values that are This registry lists values that are used within URN values that are
provided in the "type" field of problem documents in ACME. provided in the "type" field of problem documents in ACME.
skipping to change at page 67, line 22 skipping to change at page 69, line 22
o Reference: Where the validation method is defined o Reference: Where the validation method is defined
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 |
| | | | | | | | | |
| tls-sni-02 | 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-02 | RESERVED | N | N/A |
+------------+-----------------+------+-----------+ +------------+-----------------+------+-----------+
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 take the same set of actions to fulfill two and server to follow the same set of actions to fulfill two different
different validation mechanisms. 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
be registered. For example, a CA might wish to register a validation be registered. For example, a CA might wish to register a validation
method in order to support its use with the ACME extensions to CAA method in order to support its use with the ACME extensions to CAA
[I-D.ietf-acme-caa]. [I-D.ietf-acme-caa].
[[ 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 ]]
10. Security Considerations 10. Security Considerations
skipping to change at page 70, line 17 skipping to change at page 72, line 17
key in the challenge response over the ACME channel. key in the challenge response over the ACME channel.
The association of challenges to identifiers is typically done by The association of challenges to identifiers is typically done by
requiring the client to perform some action that only someone who requiring the client to perform some action that only someone who
effectively controls the identifier can perform. For the challenges effectively controls the identifier can perform. For the challenges
in this document, the actions are: in this document, the actions are:
o HTTP: Provision files under .well-known on a web server for the o HTTP: Provision files under .well-known on a web server for the
domain domain
o TLS SNI: Configure a TLS server for the domain
o DNS: Provision DNS resource records for the domain o DNS: Provision DNS resource records for the domain
There are several ways that these assumptions can be violated, both There are several ways that these assumptions can be violated, both
by misconfiguration and by attacks. For example, on a web server by misconfiguration and by attacks. For example, on a web server
that allows non-administrative users to write to .well-known, any that allows non-administrative users to write to .well-known, any
user can claim to own the web server's hostname by responding to an user can claim to own the web server's hostname by responding to an
HTTP challenge, and likewise for TLS configuration and TLS SNI. HTTP challenge. Similarly, if a server that can be used for ACME
Similarly, if a server that can be used for ACME validation is validation is compromised by a malicious actor, then that malicious
compromised by a malicious actor, then that malicious actor can use actor can use that access to obtain certificates via ACME.
that access to obtain certificates via ACME.
The use of hosting providers is a particular risk for ACME The use of hosting providers is a particular risk for ACME
validation. If the owner of the domain has outsourced operation of validation. If the owner of the domain has outsourced operation of
DNS or web services to a hosting provider, there is nothing that can DNS or web services to a hosting provider, there is nothing that can
be done against tampering by the hosting provider. As far as the be done against tampering by the hosting provider. As far as the
outside world is concerned, the zone or website provided by the outside world is concerned, the zone or website provided by the
hosting provider is the real thing. hosting provider is the real thing.
More limited forms of delegation can also lead to an unintended party More limited forms of delegation can also lead to an unintended party
gaining the ability to successfully complete a validation gaining the ability to successfully complete a validation
transaction. For example, suppose an ACME server follows HTTP transaction. For example, suppose an ACME server follows HTTP
redirects in HTTP validation and a website operator provisions a redirects in HTTP validation and a website operator provisions a
catch-all redirect rule that redirects requests for unknown resources catch-all redirect rule that redirects requests for unknown resources
to a different domain. Then the target of the redirect could use to a different domain. Then the target of the redirect could use
that to get a certificate through HTTP validation since the that to get a certificate through HTTP validation since the
validation path will not be known to the primary server. validation path will not be known to the primary server.
The DNS is a common point of vulnerability for all of these The DNS is a common point of vulnerability for all of these
challenges. An entity that can provision false DNS records for a challenges. An entity that can provision false DNS records for a
domain can attack the DNS challenge directly and can provision false domain can attack the DNS challenge directly and can provision false
A/AAAA records to direct the ACME server to send its TLS SNI or HTTP A/AAAA records to direct the ACME server to send its HTTP validation
validation query to a remote server of the attacker's choosing. query to a remote server of the attacker's choosing. There are a few
There are a few different mitigations that ACME servers can apply: different mitigations that ACME servers can apply:
o Always querying the DNS using a DNSSEC-validating resolver o Always querying the DNS using a DNSSEC-validating resolver
(enhancing security for zones that are DNSSEC-enabled) (enhancing security for zones that are DNSSEC-enabled)
o Querying the DNS from multiple vantage points to address local o Querying the DNS from multiple vantage points to address local
attackers attackers
o Applying mitigations against DNS off-path attackers, e.g., adding o Applying mitigations against DNS off-path attackers, e.g., adding
entropy to requests [I-D.vixie-dnsext-dns0x20] or only using TCP entropy to requests [I-D.vixie-dnsext-dns0x20] or only using TCP
skipping to change at page 71, line 33 skipping to change at page 73, line 30
passive attacker on the validation channel can observe the correct passive attacker on the validation channel can observe the correct
validation response and even replay it, but that response can only be validation response and even replay it, but that response can only be
used with the account key for which it was generated. used with the account key for which it was generated.
An active attacker on the validation channel can subvert the ACME An active attacker on the validation channel can subvert the ACME
process, by performing normal ACME transactions and providing a process, by performing normal ACME transactions and providing a
validation response for his own account key. The risks due to validation response for his own account key. The risks due to
hosting providers noted above are a particular case. hosting providers noted above are a particular case.
It is RECOMMENDED that the server perform DNS queries and make HTTP It is RECOMMENDED that the server perform DNS queries and make HTTP
and TLS connections from various network perspectives, in order to connections from various network perspectives, in order to make MitM
make MitM attacks harder. attacks harder.
10.3. Denial-of-Service Considerations 10.3. Denial-of-Service Considerations
As a protocol run over HTTPS, standard considerations for TCP-based As a protocol run over HTTPS, standard considerations for TCP-based
and HTTP-based DoS mitigation also apply to ACME. and HTTP-based DoS mitigation also apply to ACME.
At the application layer, ACME requires the server to perform a few At the application layer, ACME requires the server to perform a few
potentially expensive operations. Identifier validation transactions potentially expensive operations. Identifier validation transactions
require the ACME server to make outbound connections to potentially require the ACME server to make outbound connections to potentially
attacker-controlled servers, and certificate issuance can require attacker-controlled servers, and certificate issuance can require
skipping to change at page 74, line 12 skipping to change at page 76, line 9
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. Default Virtual Hosts 11.2. Token Entropy
In many cases, TLS-based services are deployed on hosted platforms
that use the Server Name Indication (SNI) TLS extension to
distinguish between different hosted services or "virtual hosts".
When a client initiates a TLS connection with an SNI value indicating
a provisioned host, the hosting platform routes the connection to
that host.
When a connection comes in with an unknown SNI value, one might
expect the hosting platform to terminate the TLS connection.
However, some hosting platforms will choose a virtual host to be the
"default", and route connections with unknown SNI values to that
host.
In such cases, the owner of the default virtual host can complete a
TLS-based challenge (e.g., "tls-sni-02") for any domain with an A
record that points to the hosting platform. This could result in
mis-issuance in cases where there are multiple hosts with different
owners resident on the hosting platform.
A CA that accepts TLS-based proof of domain control should attempt to
check whether a domain is hosted on a domain with a default virtual
host before allowing an authorization request for this host to use a
TLS-based challenge. Typically, systems with default virtual hosts
do not allow the holder of the default virtual host to control what
certificates are presented on a request-by-request basis. Rather,
the default virtual host can configure which certificate is presented
in TLS on a fairly static basis, so that the certificate presented
should be stable over small intervals.
A CA can detect such a bounded default vhost by initiating TLS
connections to the host with random SNI values within the namespace
used for the TLS-based challenge (the "acme.invalid" namespace for
"tls-sni-02"). If it receives the same certificate on two different
connections, then it is very likely that the server is in a default
virtual host configuration. Conversely, if the TLS server returns an
unrecognized_name alert, then this is an indication that the server
is not in a default virtual host configuration.
11.3. Token Entropy
The http-01, tls-sni-02 and dns-01 validation methods mandate the The http-01, and dns-01 validation methods mandate the usage of a
usage of a random token value to uniquely identify the challenge. random token value to uniquely identify the challenge. The value of
The value of the token is required to contain at least 128 bits of the token is required to contain at least 128 bits of entropy for the
entropy for the following security properties. First, the ACME following security properties. First, the ACME client should not be
client should not be able to influence the ACME server's choice of able to influence the ACME server's choice of token as this may allow
token as this may allow an attacker to reuse a domain owner's an attacker to reuse a domain owner's previous challenge responses
previous challenge responses for a new validation request. Secondly, for a new validation request. Secondly, the entropy requirement
the entropy requirement prevents ACME clients from implementing a prevents ACME clients from implementing a "naive" validation server
"naive" validation server that automatically replies to challenges that automatically replies to challenges without participating in the
without participating in the creation of the initial authorization creation of the initial authorization request.
request.
11.4. Malformed Certificate Chains 11.3. 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 an file of type "application/pem-certificate-chain",
a client SHOULD verify that the file contains only encoded a 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.
o Peter Eckersley, EFF o Peter Eckersley, EFF
skipping to change at page 75, line 49 skipping to change at page 77, line 4
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.
o Peter Eckersley, EFF o Peter Eckersley, EFF
o Eric Rescorla, Mozilla o Eric Rescorla, Mozilla
o Seth Schoen, EFF o Seth Schoen, EFF
o Alex Halderman, University of Michigan o Alex Halderman, University of Michigan
o Martin Thomson, Mozilla o Martin Thomson, Mozilla
o Jakub Warmuz, University of Oxford o Jakub Warmuz, University of Oxford
o Sophie Herold, Hemio
This document draws on many concepts established by Eric Rescorla's This document draws on many concepts established by Eric Rescorla's
"Automated Certificate Issuance Protocol" draft. Martin Thomson "Automated Certificate Issuance Protocol" draft. Martin Thomson
provided helpful guidance in the use of HTTP. provided helpful guidance in the use of HTTP.
13. References 13. References
13.1. Normative References 13.1. Normative References
[FIPS180-4] [FIPS180-4]
Department of Commerce, National., "NIST FIPS 180-4, Department of Commerce, National., "NIST FIPS 180-4,
skipping to change at page 77, line 38 skipping to change at page 78, line 47
[RFC5890] Klensin, J., "Internationalized Domain Names for [RFC5890] Klensin, J., "Internationalized Domain Names for
Applications (IDNA): Definitions and Document Framework", Applications (IDNA): Definitions and Document Framework",
RFC 5890, DOI 10.17487/RFC5890, August 2010, RFC 5890, DOI 10.17487/RFC5890, August 2010,
<https://www.rfc-editor.org/info/rfc5890>. <https://www.rfc-editor.org/info/rfc5890>.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988, [RFC5988] Nottingham, M., "Web Linking", RFC 5988,
DOI 10.17487/RFC5988, October 2010, DOI 10.17487/RFC5988, October 2010,
<https://www.rfc-editor.org/info/rfc5988>. <https://www.rfc-editor.org/info/rfc5988>.
[RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS)
Extensions: Extension Definitions", RFC 6066,
DOI 10.17487/RFC6066, January 2011,
<https://www.rfc-editor.org/info/rfc6066>.
[RFC6068] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' [RFC6068] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto'
URI Scheme", RFC 6068, DOI 10.17487/RFC6068, October 2010, URI Scheme", RFC 6068, DOI 10.17487/RFC6068, October 2010,
<https://www.rfc-editor.org/info/rfc6068>. <https://www.rfc-editor.org/info/rfc6068>.
[RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
and D. Orchard, "URI Template", RFC 6570, and D. Orchard, "URI Template", RFC 6570,
DOI 10.17487/RFC6570, March 2012, DOI 10.17487/RFC6570, March 2012,
<https://www.rfc-editor.org/info/rfc6570>. <https://www.rfc-editor.org/info/rfc6570>.
[RFC6844] Hallam-Baker, P. and R. Stradling, "DNS Certification [RFC6844] Hallam-Baker, P. and R. Stradling, "DNS Certification
skipping to change at page 78, line 35 skipping to change at page 79, line 40
2015, <https://www.rfc-editor.org/info/rfc7515>. 2015, <https://www.rfc-editor.org/info/rfc7515>.
[RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518,
DOI 10.17487/RFC7518, May 2015, DOI 10.17487/RFC7518, May 2015,
<https://www.rfc-editor.org/info/rfc7518>. <https://www.rfc-editor.org/info/rfc7518>.
[RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK) [RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK)
Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September
2015, <https://www.rfc-editor.org/info/rfc7638>. 2015, <https://www.rfc-editor.org/info/rfc7638>.
[RFC7797] Jones, M., "JSON Web Signature (JWS) Unencoded Payload
Option", RFC 7797, DOI 10.17487/RFC7797, February 2016,
<https://www.rfc-editor.org/info/rfc7797>.
[RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP
APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016,
<https://www.rfc-editor.org/info/rfc7807>. <https://www.rfc-editor.org/info/rfc7807>.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26, Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017, RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>. <https://www.rfc-editor.org/info/rfc8126>.
13.2. Informative References 13.2. Informative References
 End of changes. 117 change blocks. 
446 lines changed or deleted 478 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/